Biblelib

Utilities for working with Bible books, references, pericopes, and other units. Note this does not include any actual Bible texts.

• Github repository: <https://github.com/Clear-Bible/Biblelib
• Documentation may eventually arrive at https://clear-bible.github.io/Biblelib/ but can be found in the docs directory, and built using mkdocs.

Installation

$ pip install biblelib

Data

Most data ships inside the package (book metadata, versification vref files and scheme JSON), so the library works offline out of the box.

The two large Macula word-level mapping tables (used by biblelib.word.mappings and biblelib.word.fromubs) are the exception: they are downloaded on first use and cached locally, rather than bundled. They are verified against pinned SHA256 hashes.

• The cache location follows the OS convention (e.g. ~/Library/Caches/biblelib on macOS, ~/.cache/biblelib on Linux). Set the BIBLELIB_DATA_DIR environment variable to relocate it.

• To pre-populate the cache while online — for offline/air-gapped use, or to avoid concurrent downloads when running a parallel (pytest-xdist) test suite — run the bundled command:

  $ biblelib-download-data
  

Importing biblelib and biblelib.word never triggers a download; data is fetched only when a mapping is actually used.

Usage

Book metadata

from biblelib.book import Books

books = Books()
books["MRK"]           # <Book: MRK>
books["MRK"].name      # 'Mark'
books["MRK"].osisID    # 'Mark'
books.fromosis("Matt").name      # 'Matthew'
books.frombiblia("Mk").usfmname  # 'MRK'
books.findbook("Ge")             # <Book: GEN>  (searches all schemes)

Rendering Bible references

BCVID (book-chapter-verse) and BCVIDRange are the primary reference types. Several rendering methods are available:

from biblelib.word import BCVID, BCVIDRange

ref = BCVID("41004003")      # Mark 4:3
ref.to_usfm()                # 'MRK 4:3'
ref.to_nameref()             # 'Mark 4:3'    (full English name)
ref.to_abbrevref()           # 'Mk 4:3'      (biblia abbreviation)
ref.to_osisID()              # 'Mark 4:3'
ref.to_biblia()              # 'Mk 4:3'

rng = BCVIDRange(BCVID("41004003"), BCVID("41004008"))
rng.to_nameref()             # 'Mark 4:3-4:8'
rng.to_abbrevref()           # 'Mk 4:3-4:8'

Localized rendering

to_nameref() and to_abbrevref() accept an optional lang parameter using ISO 639-3 three-letter codes. The following languages are currently bundled:

Note: Non-English book names and abbreviations were AI-generated from the named source translations and should be verified by native-language speakers before production use, particularly for deuterocanonical and extended-canon entries.

from biblelib.word import BCVID, BCVIDRange

ref = BCVID("01001001")
ref.to_nameref(lang="fra")    # 'Genèse 1.1'
ref.to_abbrevref(lang="fra")  # 'Gn 1.1'
ref.to_nameref(lang="nld")    # 'Genesis 1:1'
ref.to_abbrevref(lang="hau")  # 'Far 1:1'
ref.to_nameref(lang="vie")    # 'Sáng Thế Ký 1:1'
ref.to_abbrevref(lang="vie")  # 'St 1:1'

rng = BCVIDRange(BCVID("41004003"), BCVID("41004008"))
rng.to_nameref(lang="fra")    # 'Marc 4.3-4.8'
rng.to_abbrevref(lang="fra")  # 'Mc 4.3-4.8'

Note that the chapter-verse separator is language-specific (English and most languages use :, French uses .).

You can also work with LocalizedBooks directly:

from biblelib.book import get_localized_books

fra = get_localized_books("fra")
fra.get_name("GEN")    # 'Genèse'
fra.get_abbrev("GEN")  # 'Gn'
fra.cv_sep             # '.'

Adding a language

Create biblelib/book/books_<lang>.tsv (e.g. books_spa.tsv for Spanish) with three tab-separated columns and optional metadata comments:

# cv_sep: .
usfmname	name	abbrev
GEN	Génesis	Gn
EXO	Éxodo	Éx
...

Supported metadata comments:

No code changes are required. The new language is available immediately via lang="spa" (or whatever code you used).

Acknowledgements

• Book abbreviations incorporate public conventions developed by
  • Unified Standard Format Markers 3.0.0 (USFM), which is © Copyright 2018, United Bible Societies.
  • The Open Scripture Information Standard (OSIS)
  • Logos Bible Software
• Versification information included consulting sources from:
  • The Copenhagen Alliance for Open Biblical Resources
  • Paratext
• Word-level mapping data (downloaded on demand) comes from:
  • Clear-Bible/macula-greek: GNT word-level identifier mappings, © Clear Bible, Inc., CC BY 4.0
  • Clear-Bible/macula-hebrew: Macula → MARBLE Hebrew mappings, © Clear Bible, Inc., CC BY 4.0