versiref-bible 0.1.0

Access Bibles using versiref

VersiRef Bible

VersiRef is a Python package for sophisticated parsing, manipulation, and printing of references to the Bible.

versiref-bible provides access to Bibles in an SQLite-based format: ranges of verses can be retrieved by reference, and verse text can be searched with SQLite FTS5. VersiRef parses the references and handles versification.

The command-line interface is designed for use by an LLM: output is compact plain text, one verse per line as reference⇥text (TAB-separated).

Documentation

• Building Databases — the build command (producers).
• Querying Databases — the show, search, and info commands (consumers).

Installation

uv sync

This installs the versiref-bible command into the project environment (run it with uv run versiref-bible …).

Commands

build — create a database from a text file

Reads a CCAT-format .cat file where each line is Abbrev C:V text (the abbreviation is a BibleWorks-style book name) and writes an SQLite database. Each verse is stored as one row, keyed by an integer verse key computed under the chosen versification, plus an FTS5 index over the verse text. CCAT footnotes/formatting are kept as plain text for now.

uv run versiref-bible build BIBLE.cat --versification eng --title "My Bible"

Options:

• -v, --versification (required) — named versification of the Bible (eng, lxx, cei, …).
• -o, --output — database path (default: input name with a .db suffix).
• --title — human-readable title stored in the database.
• --book-style — reference style whose names map the file's abbreviations (default en-bibleworks).
• --encoding — input text encoding (default utf-8; the CEI sample needs cp1252).

Lines whose book abbreviation is unrecognized (e.g. the Sirach prologue Sip), or whose book is absent from the chosen versification, are skipped with a warning on stderr.

show — print the verses of a reference

uv run versiref-bible show BIBLE.db "John 3:16-18"

• --style — reference style for parsing the input and labelling output (default en-sbl).
• --from-versification — interpret the reference in this versification and map it to the database's versification.

The reference is parsed in the style you choose, so use that style's conventions (e.g. --style it-cei expects Gen 1,1-3, not Gen 1:1-3).

search — full-text search verse text

uv run versiref-bible search BIBLE.db "living water" --limit 10

QUERY uses SQLite FTS5 syntax (e.g. light, "living water", love AND world). Results are in canonical verse order by default.

• -n, --limit — maximum verses to return (default 20).
• --in — restrict the search to a reference (e.g. --in "Gen 1", --in "John").
• --order — canonical (default, verse order) or relevance (bm25 ranking).
• --style — reference style for labelling output and parsing --in (default en-sbl).

info — show database metadata

uv run versiref-bible info BIBLE.db

Prints the stored metadata (title, versification, source, build time, …) and the verse count.

Development

uv run pytest        # tests
uv run ruff check    # lint
uv run mypy src      # type-check