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

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_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.