Technical Reference#

Book#

class pythonbible.Book(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Book is an Enum that contains all the books of the Bible.

Parameters:

  • name (str) – the unique text identifier of the book

  • value (int) – the unique numerical identifier of the book

  • title (str) – the common English name of the book

  • regular_expression (str) – the regular expression for the book

  • abbreviations (tuple[str, ...]) – the allowed title abbreviations for the book

Book Members#

Name

Value

Title

GENESIS

1

Genesis

EXODUS

2

Exodus

LEVITICUS

3

Leviticus

NUMBERS

4

Numbers

DEUTERONOMY

5

Deuteronomy

JOSHUA

6

Joshua

JUDGES

7

Judges

RUTH

8

Ruth

SAMUEL_1

9

1 Samuel

SAMUEL_2

10

2 Samuel

KINGS_1

11

1 Kings

KINGS_2

12

2 Kings

CHRONICLES_1

13

1 Chronicles

CHRONICLES_2

14

2 Chronicles

EZRA

15

Ezra

NEHEMIAH

16

Nehemiah

ESTHER

17

Esther

JOB

18

Job

PSALMS

19

Psalms

PROVERBS

20

Proverbs

ECCLESIASTES

21

Ecclesiastes

SONG_OF_SONGS

22

Song of Songs

ISAIAH

23

Isaiah

JEREMIAH

24

Jeremiah

LAMENTATIONS

25

Lamentations

EZEKIEL

26

Ezekiel

DANIEL

27

Daniel

HOSEA

28

Hosea

JOEL

29

Joel

AMOS

30

Amos

OBADIAH

31

Obadiah

JONAH

32

Jonah

MICAH

33

Micah

NAHUM

34

Nahum

HABAKKUK

35

Habakkuk

ZEPHANIAH

36

Zephaniah

HAGGAI

37

Haggai

ZECHARIAH

38

Zechariah

MALACHI

39

Malachi

MATTHEW

40

Matthew

MARK

41

Mark

LUKE

42

Luke

JOHN

43

John

ACTS

44

Acts

ROMANS

45

Romans

CORINTHIANS_1

46

1 Corinthians

CORINTHIANS_2

47

2 Corinthians

GALATIANS

48

Galatians

EPHESIANS

49

Ephesians

PHILIPPIANS

50

Philippians

COLOSSIANS

51

Colossians

THESSALONIANS_1

52

1 Thessalonians

THESSALONIANS_2

53

2 Thessalonians

TIMOTHY_1

54

1 Timothy

TIMOTHY_2

55

2 Timothy

TITUS

56

Titus

PHILEMON

57

Philemon

HEBREWS

58

Hebrews

JAMES

59

James

PETER_1

60

1 Peter

PETER_2

61

2 Peter

JOHN_1

62

1 John

JOHN_2

63

2 John

JOHN_3

64

3 John

JUDE

65

Jude

REVELATION

66

Revelation

ESDRAS_1

67

1 Esdras

TOBIT

68

Tobit

WISDOM_OF_SOLOMON

69

Wisdom of Solomon

ECCLESIASTICUS

70

Ecclesiasticus

MACCABEES_1

71

1 Maccabees

MACCABEES_2

72

2 Maccabees

BookGroup#

class pythonbible.BookGroup(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

BookGroup is an Enum containing the default Bible book groupings.

Parameters:

  • name (str) – the unique text identifier of the book group

  • value (int) – the unique numerical identifier of the book group

  • regular_expression (str) – the regular expression used to find mentions of the book group when searching for references

  • books (tuple[Book, ...]) – the list of books included in the book group

Book Group Members#

Name

Value

Regular Expression

Books

OLD_TESTAMENT

1

Old Testament

Genesis, Exodus, Leviticus, Numbers, Deuteronomy, Joshua, Judges, Ruth, 1 Samuel, 2 Samuel, 1 Kings, 2 Kings, 1 Chronicles, 2 Chronicles, Ezra, Nehemiah, Esther, Job, Psalms, Proverbs, Ecclesiastes, Song of Songs, Isaiah, Jeremiah, Lamentations, Ezekiel, Daniel, Hosea, Joel, Amos, Obadiah, Jonah, Micah, Nahum, Habakkuk, Zephaniah, Haggai, Zechariah, Malachi

OLD_TESTAMENT_LAW

2

Law

Genesis, Exodus, Leviticus, Numbers, Deuteronomy

OLD_TESTAMENT_HISTORY

3

History

Joshua, Judges, Ruth, 1 Samuel, 2 Samuel, 1 Kings, 2 Kings, 1 Chronicles, 2 Chronicles, Ezra, Nehemiah, Esther

OLD_TESTAMENT_POETRY_WISDOM

4

Poetry|Wisdom

Job, Psalms, Proverbs, Ecclesiastes, Song of Songs

OLD_TESTAMENT_PROPHECY

5

Prophecy

Isaiah, Jeremiah, Lamentations, Ezekiel, Daniel, Hosea, Joel, Amos, Obadiah, Jonah, Micah, Nahum, Habakkuk, Zephaniah, Haggai, Zechariah, Malachi

OLD_TESTAMENT_MAJOR_PROPHETS

6

Major Prophets

Isaiah, Jeremiah, Lamentations, Ezekiel, Daniel

OLD_TESTAMENT_MINOR_PROPHETS

7

Minor Prophets

Hosea, Joel, Amos, Obadiah, Jonah, Micah, Nahum, Habakkuk, Zephaniah, Haggai, Zechariah, Malachi

NEW_TESTAMENT

8

New Testament

Matthew, Mark, Luke, John, Acts, Romans, 1 Corinthians, 2 Corinthians, Galatians, Ephesians, Philippians, Colossians, 1 Thessalonians, 2 Thessalonians, 1 Timothy, 2 Timothy, Titus, Philemon, Hebrews, James, 1 Peter, 2 Peter, 1 John, 2 John, 3 John, Jude, Revelation

NEW_TESTAMENT_GOSPELS

9

Gospels

Matthew, Mark, Luke, John

NEW_TESTAMENT_HISTORY

10

History

Acts

NEW_TESTAMENT_EPISTLES

11

Epistles

Romans, 1 Corinthians, 2 Corinthians, Galatians, Ephesians, Philippians, Colossians, 1 Thessalonians, 2 Thessalonians, 1 Timothy, 2 Timothy, Titus, Philemon, Hebrews, James, 1 Peter, 2 Peter, 1 John, 2 John, 3 John, Jude

NEW_TESTAMENT_PAUL_EPISTLES

12

Pauline Epistles|Paul’s Epistles|Epistles of Paul

Romans, 1 Corinthians, 2 Corinthians, Galatians, Ephesians, Philippians, Colossians, 1 Thessalonians, 2 Thessalonians, 1 Timothy, 2 Timothy, Titus, Philemon

NEW_TESTAMENT_GENERAL_EPISTLES

13

General Epistles

Hebrews, James, 1 Peter, 2 Peter, 1 John, 2 John, 3 John, Jude

NEW_TESTAMENT_APOCALYPTIC

14

Apocalyptic

Revelation

BOOK_GROUPS#

BOOK_GROUPS is a provided “constant” containing the default dictionary of book groups to be used when allowing book groups to be considered when getting all of the references contained within a text.

For each entry in this dictionary, the key is the regular expression string associated with the given book group, and the value is the list of Book objects associated with the given book group.

BOOK_GROUPS contains all of the BookGroup values listed in the table above.

convert_reference_to_verse_ids#

pythonbible.convert_reference_to_verse_ids(reference: NormalizedReference) → tuple[int, ...]#

Convert the given NormalizedReference object into a tuple of verse id integers.

Parameters:

reference (NormalizedReference) – A normalized reference

Returns:

The tuple of verse ids associated with the reference

Return type:

tuple[int, …]

convert_references_to_verse_ids#

pythonbible.convert_references_to_verse_ids(references: list[NormalizedReference]) → list[int]#

Convert a list of NormalizedReference objects into a list of verse id integers.

Parameters:

references (list[NormalizedReference]) – A list of normalized references

Returns:

The list of verse ids associated with the references

Return type:

list[int]

convert_verse_ids_to_references#

pythonbible.convert_verse_ids_to_references(verse_ids: list[int]) → list[NormalizedReference]#

Convert a list of verse ids into a list of NormalizedReferences.

Parameters:

verse_ids (list[int]) – A list of verse ids

Returns:

The list of normalized references associated with the verse ids

Return type:

list[NormalizedReference]

Raises:

InvalidVerseError – if one or more of the verse_ids does not correspond to a valid verse

count_books#

pythonbible.count_books(references: list[NormalizedReference]) → int#
pythonbible.count_books(reference: NormalizedReference) → int
pythonbible.count_books(reference: str) → int

Return the count of books of the Bible included in the given list of references.

Parameters:

references (list[NormalizedReference]) – A list of normalized references

Returns:

The count of books of the Bible included in the given list of references

Return type:

int

count_chapters#

pythonbible.count_chapters(references: list[NormalizedReference]) → int#
pythonbible.count_chapters(reference: NormalizedReference) → int
pythonbible.count_chapters(reference: str) → int

Return the count of chapters in the given list of references.

Parameters:

references (list[NormalizedReference]) – A list of normalized references

Returns:

The count of chapters of books of the Bible included in the given list of references

Return type:

int

count_verses#

pythonbible.count_verses(references: list[NormalizedReference]) → int#
pythonbible.count_verses(reference: NormalizedReference) → int
pythonbible.count_verses(reference: str) → int

Return the count of verses included in the given list of references.

Parameters:

references (list[NormalizedReference]) – A list of normalized references

Returns:

The count of verses included in the given list of references

Return type:

int

format_scripture_references#

pythonbible.format_scripture_references(references: list[NormalizedReference] | None, **kwargs: Any) → str#

Return a human-readable string of the given normalized scripture references.

Parameters:

references (list[NormalizedReference]) – A list of normalized scripture references

Returns:

A human-readable string of the given normalized scripture references

Return type:

str

format_scripture_text#

pythonbible.format_scripture_text(verse_ids: list[int], **kwargs: Any) → str#

Return the formatted scripture text for the given list of verse IDs.

Parameters:

verse_ids (list[int]) – A list of integer verse ids

Returns:

The formatted scripture text for the verse ids

Return type:

str

format_single_reference#

pythonbible.format_single_reference(reference: NormalizedReference, include_books: bool = True, include_chapters: bool = True, **kwargs: Any) → str#

Return a human-readable string of the given normalized scripture reference.

Parameters:

  • reference (NormalizedReference) – A normalized scripture reference

  • include_books (bool) – If True includes the book title(s) in the returned reference string, defaults to True

  • include_chapters (bool) – If True includes the chapter number(s) in the returned reference string, defaults to True

Returns:

A human-readable string of the given normalized scripture reference

Return type:

str

get_book_chapter_verse#

pythonbible.get_book_chapter_verse(verse_id: int) → tuple[Book, int, int]#

Return the Book, chapter number, and verse number for the given verse id.

Parameters:

verse_id (int) – a verse id

Returns:

A tuple containing the Book, chapter number, and verse number for the given verse id

Return type:

tuple[Book, int, int]

Raises:

InvalidVerseError – if the verse id does not correspond to a valid verse

get_book_number#

pythonbible.get_book_number(verse_id: int) → int#

Return the book number for the given verse id.

Parameters:

verse_id (int) – a verse id

Returns:

The book number for the given verse id

Return type:

int

get_book_titles#

pythonbible.get_book_titles(book: Book, version: Version = Version.AMERICAN_STANDARD) → BookTitles#

Return the book titles for the given Book and optional Version.

Parameters:

  • book (Book) – a book of the Bible

  • version (Version) – a version of the Bible, defaults to American Standard

Returns:

the long and short titles of the given book and version

Return type:

BookTitles

Raises:

MissingBookFileError – if the book file for the given book and version does not exist

get_chapter_number#

pythonbible.get_chapter_number(verse_id: int) → int#

Return the chapter number for the given verse id.

Parameters:

verse_id (int) – a verse id

Returns:

The chapter number for the given verse id

Return type:

int

get_number_of_chapters#

pythonbible.get_number_of_chapters(book: Book) → int#

Return the number of chapters in a Book of the Bible.

Parameters:

book (Book) – a book of the Bible

Returns:

the number of chapters in the given book of the Bible

Return type:

int

get_number_of_verses#

pythonbible.get_number_of_verses(book: Book, chapter: int) → int#

Return the number of verses in a Book and chapter.

Parameters:

  • book (Book) – a book of the Bible

  • chapter (int) – a chapter of the given book of the Bible

Returns:

the number of verses in the given book and chapter

Return type:

int

Raises:

InvalidChapterError – if the given chapter isn’t a valid chapter for the given book

get_references#

pythonbible.get_references(text: str, book_groups: dict[str, tuple[Book, ...]] | None = None) → list[NormalizedReference]#

Search the text for scripture references.

Return any scripture references that are found in a list of normalized references.

Parameters:

  • text (str) – String that may contain zero or more scripture references

  • book_groups (dict[str, tuple[Book, ...]] or None) – Optional dictionary of BookGroup (e.g. Old Testament) to its related regular expression

Returns:

The list of found scripture references

Return type:

list[NormalizedReference]

get_verse_id#

pythonbible.get_verse_id(book: Book, chapter: int, verse: int) → int#

Return the verse id for the given Book, chapter number, and verse number.

Parameters:

  • book (Book) – a book of the Bible

  • chapter (int) – a chapter number for the given book of the Bible

  • verse (int) – a verse number for the given book and chapter

Returns:

the verse id for the given book, chapter, and verse

Return type:

int

Raises:

InvalidVerseError – if the verse doesn’t exist for the given book, chapter, and verse

get_verse_number#

pythonbible.get_verse_number(verse_id: int) → int#

Return the verse number for the given verse id.

Parameters:

verse_id (int) – a verse id

Returns:

The verse number for the given verse id

Return type:

int

get_verse_text#

pythonbible.get_verse_text(verse_id: int, version: Version = Version.AMERICAN_STANDARD) → str#

Return the scripture text of the given verse id and version of the Bible.

Parameters:

  • verse_id (int) – a verse id

  • version (Version) – a version of the Bible, defaults to American Standard

Returns:

The scripture text of the given verse id and version

Return type:

str

Raises:

InvalidBookError#

exception pythonbible.InvalidBookError#

Raised when the book id is not valid.

InvalidChapterError#

exception pythonbible.InvalidChapterError#

Raised when the chapter number is not valid for the given book of the Bible.

InvalidVerseError#

exception pythonbible.InvalidVerseError(message: str | None = None, verse_id: int | None = None, book: Book | None = None, chapter: int | None = None, verse: int | None = None)#

Raised when the verse id is not a valid Bible verse.

Or raised when the book, chapter, and verse number being processed is not a valid Bible verse.

is_valid_book#

pythonbible.is_valid_book(book: Book) → bool#

Check to see if the given book is a valid book of the Bible.

Parameters:

book (Book) – a book of the Bible

Returns:

True if the given book is valid; otherwise, False

Return type:

bool

is_valid_chapter#

pythonbible.is_valid_chapter(book: Book, chapter: int) → bool#

Check to see if the given Book is a valid book of the Bible.

If so, checks to see if the given chapter number is a valid chapter number for the given book.

Parameters:

  • book (Book) – a book of the Bible

  • chapter (int) – a chapter number for the given book of the Bible

Returns:

True if the given book and chapter are valid; otherwise, False

Return type:

bool

is_valid_reference#

pythonbible.is_valid_reference(reference: NormalizedReference) → bool#

Check to see if the given NormalizedReference is a valid scripture reference.

(i.e. all of the verses in the reference are valid verses)

Parameters:

reference (NormalizedReference) – a normalized reference

Returns:

True if the reference is valid; otherwise, False

Return type:

bool

is_valid_verse#

pythonbible.is_valid_verse(book: Book, chapter: int, verse: int) → bool#

Check to see if the given Book is a valid book of the Bible.

Then checks to see if the given chapter number is a valid chapter number for the given book, then checks to see if the given verse number is a valid verse number for the given book and chapter.

Parameters:

  • book (Book) – a book of the Bible

  • chapter (int) – a chapter number for the given book of the Bible

  • verse (int) – a verse number for the given book and chapter

Returns:

True if the given book, chapter, and verse are valid; otherwise, False

Return type:

bool

is_valid_verse_id#

pythonbible.is_valid_verse_id(verse_id: int) → bool#

Check to see if the given verse_id corresponds to a valid verse in the Bible.

Parameters:

verse_id (int) – a verse id

Returns:

True if the verse_id is in the list of valid verse ids; otherwise, False

Return type:

bool

MissingBookFileError#

exception pythonbible.MissingBookFileError#

Raised when the book file for a given version is not found.

MissingVerseFileError#

exception pythonbible.MissingVerseFileError#

Raised when the verse file for a given version is not found.

NormalizedReference#

class pythonbible.NormalizedReference(book: Book, start_chapter: int, start_verse: int, end_chapter: int, end_verse: int, end_book: Book | None = None)#

NormalizedReference is a dataclass that represents a single scripture reference.

The scripture reference contains one or more consecutive verses.

Parameters:

  • book (Book) – the first book of the Bible in the reference

  • start_chapter (int) – the number of the first chapter in the reference

  • start_verse (int) – the number of the first verse in the reference

  • end_chapter (int) – the number of the last chapter in the reference

  • end_verse (int) – the number of the last verse in the reference

  • end_book (Book) – the last book of the Bible in the reference if the reference contains more than one book, defaults to None

Version#

class pythonbible.Version(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Version of the Bible.

Version is an Enum containing all the currently known Ancient Language and English versions of the Bible.

Parameters:

  • name (str) – the unique text identifier of the version

  • value (str) – the unique abbreviated identifier of the version

  • title (str) – the English title of the version