getBible Librarian

GetBible Librarian is the Python library used to resolve scripture references, retrieve verses, and perform Unicode-aware searches against GetBible API translations. It supports standalone scripts as well as threaded and multi-process API services.

• Primary project home: https://git.vdm.dev/getBible/librarian
• GitHub deployment and releases: https://github.com/getbible/librarian
• GetBible API v2: https://api.getbible.net/v2/translations.json
• PyPI: https://pypi.org/project/getbible/

Installation

python -m pip install getbible

Python 3.10 or newer is required.

Version 3.0 narrows translation metadata in reference and search responses to six API fields. See the field contract and migration before upgrading from 2.x. This source prepares 3.0.0; pin getbible==3.0.0 after that version has been published.

Retrieve scripture

import json

from getbible import GetBible


bible = GetBible()

selection = bible.select("Genesis 1:1-3;John 3:16", "kjv")
print(json.dumps(selection, ensure_ascii=False, indent=2))

encoded = bible.scripture("Psalm 23:1-6", "kjv")
print(encoded)

select() returns the established chapter-keyed dictionary. scripture() returns the same structure encoded as JSON.

Each chapter includes only these translation fields: translation, abbreviation, lang, language, direction, and encoding, as present in the source. Book/chapter metadata, ref, and verses keep their existing structure.

Search scripture

import json

from getbible import GetBible, SearchBible, SearchLimits


bible = GetBible(
    search_limits=SearchLimits(
        max_work_units=50_000_000,
        max_response_bytes=4 * 1024 * 1024,
        deadline_seconds=5.0,
    )
)
criteria = SearchBible(
    words="all",
    match="whole_word",
    case_sensitive=False,
    scope="new_testament",
    books=("John", "1 John"),
    exclude=("darkness",),
    sort="canonical",
    limit=20,
    offset=0,
)

response = bible.search("word life", "kjv", criteria)
print(json.dumps(response, ensure_ascii=False, indent=2))

Search responses contain three top-level objects:

• query: normalized criteria, translation metadata, exact total, pagination, SHA, cache state, and deterministic search cost.
• results: the same grouped scripture object format returned by select().
• matches: ordered per-verse match metadata, including score, occurrences, and matched terms.

query.translation contains the same six translation fields used by chapter results. Full translation history and other supplemental metadata can be retrieved separately from the existing translation catalogue.

This keeps existing scripture templates reusable. With relevance sorting, matches is the authoritative cross-chapter order.

Matching is derived from the text, not chosen by the caller. Librarian classifies every run of a verse and of a query by the writing system it is actually in, and applies that system's rules, so a bare query string works in every translation the API publishes:

bible.search("神爱世人", "cus")          # Chinese, nothing delimits a word
bible.search("사랑", "korean")            # Korean, inside an inflected word
bible.search("בראשית", "modernhebrew")   # unpointed, reaches pointed text
bible.search("λογος", "moderngreek")     # unaccented, reaches accented text

There is no match mode to select and no script to detect. Applications carrying a helper that inspects the query and switches to substring should delete it. See Scripture search for the matching policy, the response contract, and the 1.x migration.

Search criteria may also be supplied as a JSON-decoded dictionary:

response = bible.search(
    "faith hope",
    "kjv",
    {
        "words": "phrase",
        "scope": "bible",
        "limit": 50,
        "offset": 0,
    },
)

Cache behavior

Reference retrieval keeps the lightweight chapter request path. Search downloads the selected full translation once, verifies it against /v2/{translation}.sha, and builds a compact in-memory postings index.

By default, full translations are cached under the operating system's user cache directory and checked every seven days. Configure a shared service cache explicitly:

from datetime import timedelta

from getbible import GetBible


bible = GetBible(
    cache_dir="/var/cache/getbible",
    cache_ttl=timedelta(days=7),
    strict_freshness=False,
    require_checksums=True,
)

Remote production checksums are required. Full corpora and their independent books indexes are completely validated before immutable, content-addressed payloads are atomically committed. A last-known-good translation remains available during temporary repository or newly published integrity failures unless strict_freshness=True.

Production caches are bounded by default. A service can warm its expected translation without issuing an artificial query and can expose cache counters to its internal metrics system:

bible = GetBible(
    cache_dir="/var/cache/getbible",
    search_corpus_limit=4,
    translation_cache_limit=4,
)
bible.warm_translation("kjv")
cache_state = bible.cache_info()

Atomically updated local mirrors can coordinate application response caches and worker-local invalidation with source_operation() and transition_source(). See Cache validation and retention.

Call bible.close() during worker shutdown, or use GetBible as a context manager in short-lived scripts.

Documentation

• Usage and reference retrieval
• Search criteria and response contract
• Translation metadata and the 3.0 migration
• Cache validation and retention
• Architecture
• Multi-process operations
• Development and releases
• AI and repository guidance

Source installation

The primary project home remains on VDM Gitea:

git clone https://git.vdm.dev/getBible/librarian.git
cd librarian
python -m venv .venv
.venv/bin/python -m pip install -e .

The GitHub deployment mirror can also be cloned:

git clone https://github.com/getbible/librarian.git
cd librarian
python -m venv .venv
.venv/bin/python -m pip install -e .

Development

./scripts/run_release_gate.sh

This creates or reuses .venv, installs every development tool, and runs the local deterministic release gate. GitHub's manually dispatchable CI workflow is the authoritative Python 3.10–3.14 check. Live API tests remain separate and intentionally opt-in:

./scripts/run_release_gate.sh --live

See the security and reliability release gate for manual commands, expected diagnostics, and GitHub workflow instructions.

License

GetBible Librarian is licensed under the GNU General Public License v2.0 or later. See LICENSE.