biblelib 0.4.1

Utilities for working with metadata for Bible books, references, pericopes, and other units.

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

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:

Code	Language	Source translation
arb	Arabic	Van Dyck Bible (Smith-Van Dyck, 1865)
fra	French	Bible en français courant / Louis Segond
hin	Hindi	Bible Society of India Hindi Old Version (Re-edited)
ind	Indonesian	Terjemahan Baru (LAI, 1974/rev.)
por	Portuguese	Almeida Revista e Corrigida
rus	Russian	Synodal Translation (Синодальный перевод, 1876)
spa	Spanish	Reina-Valera / NVI
swh	Swahili	Swahili Union Version (Toleo la Umoja)
zhs	Chinese (Simplified)	Chinese Union Version Simplified (和合本简体)
zht	Chinese (Traditional)	Chinese Union Version Traditional (和合本)

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="zht")    # '創世記 1:1'
ref.to_abbrevref(lang="rus")  # 'Быт 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:

Key	Description	Default
cv_sep	Chapter-verse separator character	:

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