Biblelib

Release Build status codecov Commit activity Docs Code style with black Imports with isort License

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

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:

Code Language Source translation
apd Sudanese Arabic Van Dyck Bible (OT); Biblica Sudanese Arabic NT
arb Arabic Van Dyck Bible (Smith-Van Dyck, 1865)
bis Bislama Baibel long Bislama (BSSP, 1995)
fra French Bible en français courant / Louis Segond
hau Hausa Littafi Mai Tsarki (Bible Society of Nigeria)
hin Hindi Bible Society of India Hindi Old Version (Re-edited)
ibo Igbo Akwụkwọ Nsọ (Bible Society of Nigeria)
ind Indonesian Terjemahan Baru (LAI, 1974/rev.)
nep Nepali Pavitra Grantha (Nepal Bible Society)
nld Dutch Herziene Statenvertaling (HSV, 2010)
por Portuguese Almeida Revista e Corrigida
rus Russian Synodal Translation (Синодальный перевод, 1876)
spa Spanish Reina-Valera / NVI
swh Swahili Swahili Union Version (Toleo la Umoja)
tpi Tok Pisin Baibel long Tok Pisin (BSPNG, 1989)
vie Vietnamese Kinh Thánh Tin Lành 1925
zhs Chinese (Simplified) Chinese Union Version Simplified (和合本简体)
zht Chinese (Traditional) Chinese Union Version Traditional (和合本)
zlm Malay Alkitab dalam Bahasa Malaysia (BSM/BSS)

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:

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

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for sboisen from gravatar.com sboisen

Credits

Author: Sean Boisen

Requires

Python <3.14, >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

biblelib-0.6.0.tar.gz (545.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

biblelib-0.6.0-py3-none-any.whl (561.1 kB view details)

Uploaded Python 3

File details

Details for the file biblelib-0.6.0.tar.gz.

File metadata

  • Download URL: biblelib-0.6.0.tar.gz
  • Upload date:
  • Size: 545.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.14.7 Darwin/25.5.0

File hashes

Hashes for biblelib-0.6.0.tar.gz
Algorithm Hash digest
SHA256 ef76b39e64faaaa8fc3995e68ce574b9760a24abb519e158668861320a9328db
MD5 9327ce58235ea39fa5fe09b76f1e09df
BLAKE2b-256 70abc4830710d775e97a544fd1adbd964938f0cb49ecb5ccec16d49abdda4def

See more details on using hashes here.

File details

Details for the file biblelib-0.6.0-py3-none-any.whl.

File metadata

  • Download URL: biblelib-0.6.0-py3-none-any.whl
  • Upload date:
  • Size: 561.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.14.7 Darwin/25.5.0

File hashes

Hashes for biblelib-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 dbd1d4a7197fe896c757f970dc4497dd3fb26da18400d2fbd35678d9be12868a
MD5 31cc8754a7eba0115f0d8c38b454e9fd
BLAKE2b-256 3ef8ec00b6ed163f3c27eb496679bd0bdfed158e76569703f08dfdb494a05109

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.29

2 files

0.3.28

2 files

0.3.27

2 files

0.3.26

2 files

0.3.25

2 files

0.3.24

2 files

0.3.23

2 files

0.3.22

2 files

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.12

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.28

2 files

0.2.27

2 files

0.2.26

2 files

0.2.25

2 files

0.2.24

2 files

0.2.23

2 files

0.2.22

2 files

0.2.21

2 files

0.2.19

2 files

0.2.18

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page