Technical Reference

add_bible

pythonbible.add_bible(version: Version, bible_type: str, version_bible: Bible) → None

Add the Bible to the dictionary of Bibles.

This should allow a user to BYOB (bring your own Bible) to the library, which can be useful if a user has licensed a copyrighted Bible (which is not included in the pythonbible library) for use within their application.

Parameters:

  • version (Version) – The version of the Bible

  • bible_type (str) – The type of the Bible

  • version_bible (Bible) – The Bible to add

Bible

class pythonbible.Bible(version: Version, scripture_content: str, verse_start_indices: dict[int, int], verse_end_indices: dict[int, int], max_verses: dict[Book, dict[int, int]], short_titles: dict[Book, str], long_titles: dict[Book, str], is_html: bool = False)

The Bible class.

The Bible class contains the scripture content for a version and format along with the functionality necessary to get the scripture content for a verse or range of verses.

Parameters:

  • version (Version) – The version of the Bible.

  • scripture_content (str) – The scripture content for the Bible.

  • verse_start_indices (dict[int, int]) – The start indices for each verse.

  • verse_end_indices (dict[int, int]) – The end indices for each verse.

  • max_verses (dict[Book, dict[int, int]]) – The maximum verses for each book and chapter.

  • short_titles (dict[Book, str]) – The short titles for each book.

  • long_titles (dict[Book, str]) – The long titles for each book.

  • is_html (bool) – Whether the scripture content is HTML.

get_number_of_chapters(book: Book) → int

Get the number of chapters in the given book.

Parameters:

book (Book) – a book of the Bible

Returns:

the number of chapters in the given book

Return type:

int

Raises:

VersionMissingBookError – if the book is not valid for the version

get_number_of_verses(book: Book, chapter: int) → int

Get the number of verses in the given book and chapter.

Parameters:

  • book (Book) – a book of the Bible

  • chapter (int) – a chapter number

Returns:

the number of verses in the given book and chapter

Return type:

int

Raises:
get_scripture(start_verse_id: int, end_verse_id: int | None = None) → str

Get the scripture content for the given verse ID or range of verse IDs.

Parameters:

  • start_verse_id (int) – The starting verse ID.

  • end_verse_id (int | None) – The ending verse ID.

Returns:

The scripture content for the given verse ID or range of verse IDs.

Return type:

str

Raises:

VersionMissingVerseError – if a verse ID is not valid for the version

get_verse_ids() → tuple[int, ...]

Get all verse IDs in this Bible version.

Returns:

A tuple of all verse IDs

Return type:

tuple[int, …]

is_valid_verse_id(verse_id: int) → bool

Check if the given verse ID is valid in this Bible version.

Parameters:

verse_id (int) – a verse id

Returns:

True if the verse_id is valid; otherwise, False.

Return type:

bool

Book

class pythonbible.Book(*values)

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(*values)

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, bible: Bible | None = None) → tuple[int, ...]

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

Parameters:

  • reference (NormalizedReference) – A normalized reference

  • bible (Bible | None) – An optional Bible object to validate verse ids against

Returns:

The tuple of verse ids associated with the reference

Return type:

tuple[int, …]

Raises:

convert_references_to_verse_ids

pythonbible.convert_references_to_verse_ids(references: list[NormalizedReference], bible: Bible | None = None) → list[int]

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

Parameters:

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

  • bible (Bible | None) – An optional Bible object to validate verse ids against

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], bible: Bible | None = None) → list[NormalizedReference]

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

Parameters:

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

  • bible (Bible | None) – An optional Bible object to validate verse ids against

Returns:

The list of normalized references associated with the verse ids

Return type:

list[NormalizedReference]

Raises:

count_books

pythonbible.count_books(references: list[NormalizedReference], bible: Bible | None = None) → int
pythonbible.count_books(reference: NormalizedReference, bible: Bible | None = None) → int
pythonbible.count_books(reference: str, bible: Bible | None = None) → 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

  • bible (Bible | None) – An optional Bible object to validate against

Returns:

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

Return type:

int

Raises:

VersionMissingBookError – If a book in the reference is not present in the given Bible version

count_chapters

pythonbible.count_chapters(references: list[NormalizedReference], bible: Bible | None = None) → int
pythonbible.count_chapters(reference: NormalizedReference, bible: Bible | None = None) → int
pythonbible.count_chapters(reference: str, bible: Bible | None = None) → int

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

Parameters:

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

  • bible (Bible | None) – An optional Bible object to validate against

Returns:

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

Return type:

int

Raises:

VersionMissingBookError – If a book in the reference is not present in the given Bible version

count_verses

pythonbible.count_verses(references: list[NormalizedReference], bible: Bible | None = None) → int
pythonbible.count_verses(reference: NormalizedReference, bible: Bible | None = None) → int
pythonbible.count_verses(reference: str, bible: Bible | None = None) → int

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

Parameters:

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

  • bible (Bible | None) – An optional Bible object to validate against

Returns:

The count of verses included in the given list of references

Return type:

int

Raises:

format_scripture_references

pythonbible.format_scripture_references(references: list[NormalizedReference] | None, bible: Bible | None = 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

  • bible (Bible | None) – An optional Bible object to format against

  • kwargs (Any) – Additional keyword arguments to pass to the formatter functions

Returns:

A human-readable string of the given normalized scripture references

Return type:

str

Raises:

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

Raises:

format_single_reference

pythonbible.format_single_reference(reference: NormalizedReference, include_books: bool = True, include_chapters: bool = True, bible: Bible | None = None, **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

  • bible (Bible | None) – An optional Bible object to format against

  • kwargs (Any) – Additional keyword arguments to pass to the formatter functions

Returns:

A human-readable string of the given normalized scripture reference

Return type:

str

Raises:

get_bible

pythonbible.get_bible(version: Version, bible_type: str) → Bible

Return the Bible for the given version and format.

Parameters:

  • version (Version) – The version of the Bible

  • bible_type (str) – The type of the Bible

Returns:

The Bible for the given version and type

Return type:

Bible

Raises:

MissingBiblePackageError – If no package is found for the given version

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_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, bible: Bible | None = None) → int

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

Parameters:

  • book (Book) – a book of the Bible

  • bible (Bible | None) – an optional Bible object to check for chapter existence

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, bible: Bible | None = None) → 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

  • bible (Bible | None) – an optional Bible object to check for verse existence

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, bible: Bible | 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

  • bible (Bible | None) – An optional Bible object to validate against

Returns:

The list of found scripture references

Return type:

list[NormalizedReference]

get_verse_id

pythonbible.get_verse_id(book: Book, chapter: int, verse: int, bible: Bible | None = None) → 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

  • bible (Bible | None) – an optional Bible object to check for verse existence

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, bible: Bible | None = None) → bool

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

Parameters:

  • book (Book) – a book of the Bible

  • bible (Bible | None) – an optional Bible object to check for book existence

Returns:

True if the given book is valid; otherwise, False

Return type:

bool

is_valid_chapter

pythonbible.is_valid_chapter(book: Book, chapter: int, bible: Bible | None = None) → 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

  • bible (Bible | None) – an optional Bible object to check for chapter existence

Returns:

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

Return type:

bool

is_valid_reference

pythonbible.is_valid_reference(reference: NormalizedReference, bible: Bible | None = None) → 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

  • bible (Bible | None) – an optional Bible object to check for verse existence

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, bible: Bible | None = None) → 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

  • bible (Bible | None) – an optional Bible object to check for verse existence

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, bible: Bible | None = None) → bool

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

Parameters:

  • verse_id (int) – a verse id

  • bible (Bible | None) – an optional Bible object to check for verse existence

Returns:

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

Return type:

bool

MissingBiblePackageError

exception pythonbible.MissingBiblePackageError

Raised when the Bible package for a given version is not found.

normalize_reference

pythonbible.normalize_reference(reference: str, bible: Bible | None = None) → list[NormalizedReference]

Convert a scripture reference string into a list of normalized tuple references.

Parameters:

  • reference (str) – a string that is a scripture reference

  • bible (Bible | None) – an optional Bible object to validate against

Returns:

a list of tuples. each tuple is in the format (book, start_chapter, start_verse, end_chapter, end_verse)

Return type:

list[NormalizedReference]

NormalizedReference

class pythonbible.NormalizedReference(book: Book, start_chapter: int | None = None, start_verse: int | None = None, end_chapter: int | None = None, end_verse: int | None = None, 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(*values)

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

VersionMissingBookError

exception pythonbible.VersionMissingBookError(version: Version, book: Book)

Raised when the book for a given version is missing from the version.

VersionMissingChapterError

exception pythonbible.VersionMissingChapterError(version: Version, book: Book, chapter: int)

Raised when the chapter for a given version is missing from the version.

VersionMissingVerseError

exception pythonbible.VersionMissingVerseError(version: Version, verse_id: int)

Raised when the verse for a given version is missing from the version.