versiref-bible 0.1.0__tar.gz

versiref_bible-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael F. Polis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

versiref_bible-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: versiref-bible
+Version: 0.1.0
+Summary: Access Bibles using versiref
+Author: Fr. John Lawrence M. Polis
+Author-email: Fr. John Lawrence M. Polis <emptier-sank-dose@duck.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Religion
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Religion
+Classifier: Topic :: Text Processing
+Requires-Dist: versiref>=0.5.1
+Requires-Dist: click>=8.1.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/fiapps/versiref-bible
+Project-URL: Issues, https://github.com/fiapps/versiref-bible/issues
+Description-Content-Type: text/markdown
+
+# VersiRef Bible
+
+[VersiRef](https://github.com/fiapps/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](docs/building.md) — the `build` command (producers).
+- [Querying Databases](docs/querying.md) — the `show`, `search`, and `info` commands (consumers).
+
+## Installation
+
+```sh
+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.
+
+```sh
+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
+
+```sh
+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
+
+```sh
+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
+
+```sh
+uv run versiref-bible info BIBLE.db
+```
+
+Prints the stored metadata (title, versification, source, build time, …) and the verse count.
+
+## Development
+
+```sh
+uv run pytest        # tests
+uv run ruff check    # lint
+uv run mypy src      # type-check
+```

versiref_bible-0.1.0/README.md

@@ -0,0 +1,93 @@
+# VersiRef Bible
+
+[VersiRef](https://github.com/fiapps/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](docs/building.md) — the `build` command (producers).
+- [Querying Databases](docs/querying.md) — the `show`, `search`, and `info` commands (consumers).
+
+## Installation
+
+```sh
+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.
+
+```sh
+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
+
+```sh
+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
+
+```sh
+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
+
+```sh
+uv run versiref-bible info BIBLE.db
+```
+
+Prints the stored metadata (title, versification, source, build time, …) and the verse count.
+
+## Development
+
+```sh
+uv run pytest        # tests
+uv run ruff check    # lint
+uv run mypy src      # type-check
+```

versiref_bible-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "versiref-bible"
+version = "0.1.0"
+description = "Access Bibles using versiref"
+readme = "README.md"
+authors = [
+    { name = "Fr. John Lawrence M. Polis", email = "emptier-sank-dose@duck.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Religion",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Religion",
+    "Topic :: Text Processing",
+]
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "versiref>=0.5.1",
+    "click>=8.1.0",
+]
+
+[project.scripts]
+versiref-bible = "versiref.bible.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/fiapps/versiref-bible"
+Issues = "https://github.com/fiapps/versiref-bible/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "versiref.bible"
+
+[tool.mypy]
+mypy_path = "src"
+namespace_packages = true
+explicit_package_bases = true
+
+[tool.ruff.lint]
+select = ["D"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D101", "D102", "D103"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "ruff>=0.15.1",
+]

versiref_bible-0.1.0/src/versiref/bible/__init__.py

@@ -0,0 +1,16 @@
+"""Access Bibles stored in an SQLite database with versiref."""
+
+from versiref.bible.builder import build_database
+from versiref.bible.database import Database
+from versiref.bible.models import BuildStats, Verse
+from versiref.bible.reader import format_verse, search_verses, show_verses
+
+__all__ = [
+    "BuildStats",
+    "Database",
+    "Verse",
+    "build_database",
+    "format_verse",
+    "search_verses",
+    "show_verses",
+]

versiref_bible-0.1.0/src/versiref/bible/builder.py

@@ -0,0 +1,115 @@
+"""Build a SQLite Bible database from a CCAT-format text file."""
+
+import datetime
+from pathlib import Path
+
+from versiref import RefStyle, SimpleBibleRef, Versification
+
+from .database import SCHEMA_VERSION, Database
+from .models import BuildStats, Verse
+
+
+def _parse_line(line: str) -> tuple[str, int, int, str] | None:
+    """Parse one CCAT line ``Abbrev C:V text`` into its components.
+
+    Returns ``(abbrev, chapter, verse, text)`` or ``None`` if the line does not
+    match the expected shape. CCAT footnotes/formatting in ``text`` are kept
+    verbatim (parsing them is future work).
+    """
+    abbrev, _, rest = line.partition(" ")
+    cv, _, text = rest.partition(" ")
+    if not abbrev or ":" not in cv:
+        return None
+    chapter_s, _, verse_s = cv.partition(":")
+    try:
+        return abbrev, int(chapter_s), int(verse_s), text
+    except ValueError:
+        return None
+
+
+def build_database(
+    input_path: str | Path,
+    output_path: str | Path,
+    *,
+    versification: str,
+    title: str | None = None,
+    book_style: str = "en-bibleworks",
+    encoding: str = "utf-8",
+) -> BuildStats:
+    """Build a Bible database from a CCAT-format ``.cat`` file.
+
+    Each non-blank line is read as ``Abbrev C:V text``. The abbreviation is
+    mapped to a Paratext book ID via the ``book_style`` recognized names, and a
+    verse key is computed under ``versification``. Lines whose abbreviation is
+    unrecognized (e.g. the Sirach prologue ``Sip``) or whose book is absent from
+    the versification are warned-and-skipped — see :class:`BuildStats`.
+
+    Args:
+        input_path: Source ``.cat`` file.
+        output_path: Destination database (overwritten if it exists).
+        versification: Named versification for the Bible (e.g. ``eng``).
+        title: Human-readable title stored in metadata.
+        book_style: Named reference style whose recognized names map the
+            file's book abbreviations (default ``en-bibleworks``).
+        encoding: Text encoding of the input file (default ``utf-8``;
+            the CEI sample needs ``cp1252``).
+
+    Returns:
+        A :class:`BuildStats` summary of what was stored and skipped.
+
+    """
+    input_path = Path(input_path)
+    output_path = Path(output_path)
+
+    vers = Versification.named(versification)
+    recognized = RefStyle.named(book_style).recognized_names
+
+    stats = BuildStats()
+    verses: dict[int, Verse] = {}
+
+    with input_path.open(encoding=encoding) as handle:
+        for raw in handle:
+            line = raw.rstrip("\n")
+            if not line.strip():
+                continue
+            parsed = _parse_line(line)
+            if parsed is None:
+                stats.malformed += 1
+                continue
+            abbrev, chapter, verse, text = parsed
+
+            book_id = recognized.get(abbrev)
+            if book_id is None:
+                stats.unknown_books[abbrev] = stats.unknown_books.get(abbrev, 0) + 1
+                continue
+
+            # range_keys yields nothing when the book is not in this
+            # versification; that is the off-scheme, warn-and-skip case.
+            ranges = list(SimpleBibleRef.for_range(book_id, chapter, verse).range_keys(vers))
+            if not ranges:
+                stats.off_scheme_books[abbrev] = (
+                    stats.off_scheme_books.get(abbrev, 0) + 1
+                )
+                continue
+
+            key = ranges[0][0]
+            if key in verses:
+                stats.duplicates += 1
+            verses[key] = Verse(key, book_id, chapter, verse, text)
+
+    stats.stored = len(verses)
+
+    output_path.unlink(missing_ok=True)
+    with Database(output_path) as db:
+        db.create_schema()
+        db.insert_verses(verses.values())
+        db.rebuild_fts()
+        db.set_metadata("schema_version", SCHEMA_VERSION)
+        db.set_metadata("versification", versification)
+        db.set_metadata("source", input_path.name)
+        db.set_metadata("verse_count", str(stats.stored))
+        db.set_metadata("built_at", datetime.datetime.now().isoformat(timespec="seconds"))
+        if title is not None:
+            db.set_metadata("title", title)
+
+    return stats

versiref_bible-0.1.0/src/versiref/bible/cli.py

@@ -0,0 +1,243 @@
+"""Command-line interface for versiref-bible."""
+
+import sys
+from pathlib import Path
+
+import click
+from versiref import RefStyle
+
+from .builder import build_database
+from .database import Database
+from .models import BuildStats
+from .reader import format_verse, search_verses, show_verses
+
+
+@click.group()
+@click.version_option(package_name="versiref-bible")
+def main() -> None:
+    """Access Bibles stored in an SQLite database with versiref."""
+    pass
+
+
+def _report_build(stats: BuildStats, output: Path) -> None:
+    """Print a build summary, sending skip warnings to stderr."""
+    click.echo(f"✓ Built {output} ({stats.stored} verses)")
+    if stats.unknown_books:
+        total = sum(stats.unknown_books.values())
+        names = ", ".join(sorted(stats.unknown_books))
+        click.echo(
+            f"  warning: skipped {total} line(s) with unrecognized book "
+            f"abbreviations: {names}",
+            err=True,
+        )
+    if stats.off_scheme_books:
+        total = sum(stats.off_scheme_books.values())
+        names = ", ".join(sorted(stats.off_scheme_books))
+        click.echo(
+            f"  warning: skipped {total} line(s) in books not in the "
+            f"versification: {names}",
+            err=True,
+        )
+    if stats.malformed:
+        click.echo(
+            f"  warning: skipped {stats.malformed} malformed line(s)", err=True
+        )
+    if stats.duplicates:
+        click.echo(
+            f"  warning: {stats.duplicates} duplicate verse key(s) (last kept)",
+            err=True,
+        )
+
+
+@main.command()
+@click.argument(
+    "input_file", type=click.Path(exists=True, dir_okay=False, path_type=Path)
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_file",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Output database path [default: INPUT with a .db suffix]",
+)
+@click.option(
+    "-v",
+    "--versification",
+    required=True,
+    help="Named versification of the Bible (e.g. eng, lxx, cei).",
+)
+@click.option("--title", default=None, help="Human-readable title for the Bible.")
+@click.option(
+    "--book-style",
+    default="en-bibleworks",
+    show_default=True,
+    help="Reference style whose names map the file's book abbreviations.",
+)
+@click.option(
+    "--encoding",
+    default="utf-8",
+    show_default=True,
+    help="Text encoding of the input file (the CEI sample needs cp1252).",
+)
+def build(
+    input_file: Path,
+    output_file: Path | None,
+    versification: str,
+    title: str | None,
+    book_style: str,
+    encoding: str,
+) -> None:
+    """Build a Bible database from a CCAT-format text file.
+
+    Each line of INPUT_FILE is read as ``Abbrev C:V text``. Lines whose book
+    abbreviation is unrecognized, or whose book is not in the chosen
+    versification, are skipped with a warning.
+    """
+    output = output_file or input_file.with_suffix(".db")
+    try:
+        stats = build_database(
+            input_file,
+            output,
+            versification=versification,
+            title=title,
+            book_style=book_style,
+            encoding=encoding,
+        )
+        _report_build(stats, output)
+    except (ValueError, LookupError, OSError) as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument(
+    "database", type=click.Path(exists=True, dir_okay=False, path_type=Path)
+)
+@click.argument("reference")
+@click.option(
+    "--style",
+    default="en-sbl",
+    show_default=True,
+    help="Reference style for parsing input and labelling output.",
+)
+@click.option(
+    "--from-versification",
+    default=None,
+    help="Interpret REFERENCE in this versification and map it to the database's.",
+)
+def show(
+    database: Path,
+    reference: str,
+    style: str,
+    from_versification: str | None,
+) -> None:
+    """Print the verses covered by a Bible REFERENCE, one per line.
+
+    Each line is ``reference<TAB>text``.
+    """
+    try:
+        verses, db_vers = show_verses(
+            database,
+            reference,
+            style_name=style,
+            from_versification=from_versification,
+        )
+        if not verses:
+            click.echo("No verses found.", err=True)
+            return
+        ref_style = RefStyle.named(style)
+        for verse in verses:
+            click.echo(format_verse(verse, ref_style, db_vers))
+    except (ValueError, LookupError) as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument(
+    "database", type=click.Path(exists=True, dir_okay=False, path_type=Path)
+)
+@click.argument("query")
+@click.option(
+    "-n",
+    "--limit",
+    type=int,
+    default=20,
+    show_default=True,
+    help="Maximum number of verses to return.",
+)
+@click.option(
+    "--in",
+    "scope",
+    default=None,
+    help='Restrict the search to a reference (e.g. "Gen 1", "John").',
+)
+@click.option(
+    "--order",
+    type=click.Choice(["canonical", "relevance"]),
+    default="canonical",
+    show_default=True,
+    help="Result order: canonical (verse order) or relevance (bm25 rank).",
+)
+@click.option(
+    "--style",
+    default="en-sbl",
+    show_default=True,
+    help="Reference style for labelling output and parsing --in.",
+)
+def search(
+    database: Path,
+    query: str,
+    limit: int,
+    scope: str | None,
+    order: str,
+    style: str,
+) -> None:
+    """Full-text search verse text with FTS5 QUERY.
+
+    QUERY uses SQLite FTS5 syntax (e.g. ``light``, ``"living water"``,
+    ``love AND world``). Output is ``reference<TAB>text``, in canonical verse
+    order by default (use ``--order relevance`` for bm25 ranking).
+    """
+    try:
+        verses, total, db_vers = search_verses(
+            database, query, limit=limit, scope=scope, order=order, style_name=style
+        )
+        if not verses:
+            click.echo("No matching verses.", err=True)
+            return
+        ref_style = RefStyle.named(style)
+        for verse in verses:
+            click.echo(format_verse(verse, ref_style, db_vers))
+        if total > len(verses):
+            click.echo(
+                f"… showing {len(verses)} of {total} matches "
+                f"(raise --limit to see more)",
+                err=True,
+            )
+    except (ValueError, LookupError) as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument(
+    "database", type=click.Path(exists=True, dir_okay=False, path_type=Path)
+)
+def info(database: Path) -> None:
+    """Show metadata and verse count for a Bible database."""
+    try:
+        with Database(database) as db:
+            metadata = db.get_all_metadata()
+            count = db.count_verses()
+        for key, value in metadata.items():
+            click.echo(f"{key}: {value}")
+        click.echo(f"verses: {count}")
+    except (ValueError, OSError) as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

versiref_bible-0.1.0/src/versiref/bible/database.py

@@ -0,0 +1,230 @@
+"""Database schema and operations for versiref-bible."""
+
+import sqlite3
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from typing import Any
+
+from .models import Verse
+
+SCHEMA_VERSION = "1.0"
+
+SCHEMA_SQL = """
+-- Key-value metadata (title, versification, source, etc.)
+CREATE TABLE IF NOT EXISTS metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+-- One row per Bible verse. verse_key is the BBCCCVVV integer computed under
+-- the database's versification; it doubles as the FTS5 rowid.
+CREATE TABLE IF NOT EXISTS verses (
+    verse_key INTEGER PRIMARY KEY,
+    book_id   TEXT NOT NULL,
+    chapter   INTEGER NOT NULL,
+    verse     INTEGER NOT NULL,
+    text      TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_verses_bcv ON verses(book_id, chapter, verse);
+
+-- FTS5 full-text index over verse text (external content = verses table)
+CREATE VIRTUAL TABLE IF NOT EXISTS verses_fts USING fts5(
+    text,
+    content='verses',
+    content_rowid='verse_key'
+);
+"""
+
+
+def _range_clause(ranges: Sequence[tuple[int, int]]) -> tuple[str, list[Any]]:
+    """Build an ``OR`` of ``verse_key BETWEEN`` clauses for a set of key ranges.
+
+    Returns the parenthesised SQL fragment and its bound parameters. An empty
+    ``ranges`` yields ``("1=0", [])`` so the caller matches nothing.
+    """
+    if not ranges:
+        return "1=0", []
+    parts = ["verse_key BETWEEN ? AND ?"] * len(ranges)
+    params: list[Any] = []
+    for start, end in ranges:
+        params.extend((start, end))
+    return "(" + " OR ".join(parts) + ")", params
+
+
+class Database:
+    """Manages SQLite database connections and operations for a Bible."""
+
+    def __init__(self, db_path: str | Path):
+        """Initialize the database wrapper.
+
+        Args:
+            db_path: Path to the SQLite database file.
+
+        """
+        self.db_path = Path(db_path)
+        self.conn: sqlite3.Connection | None = None
+
+    def __enter__(self) -> "Database":
+        """Open the connection on context entry."""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Close the connection on context exit."""
+        self.close()
+
+    def connect(self) -> None:
+        """Open the database connection."""
+        self.conn = sqlite3.connect(self.db_path)
+        self.conn.row_factory = sqlite3.Row
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self.conn:
+            self.conn.close()
+            self.conn = None
+
+    def _require_conn(self) -> sqlite3.Connection:
+        if self.conn is None:
+            raise RuntimeError("Database not connected")
+        return self.conn
+
+    def create_schema(self) -> None:
+        """Create the database schema if it does not exist."""
+        conn = self._require_conn()
+        conn.executescript(SCHEMA_SQL)
+        conn.commit()
+
+    def set_metadata(self, key: str, value: str) -> None:
+        """Set a single metadata key-value pair."""
+        conn = self._require_conn()
+        conn.execute(
+            "INSERT OR REPLACE INTO metadata (key, value) VALUES (?, ?)", (key, value)
+        )
+        conn.commit()
+
+    def get_metadata(self, key: str) -> str | None:
+        """Return a metadata value by key, or None if absent."""
+        conn = self._require_conn()
+        cursor = conn.execute("SELECT value FROM metadata WHERE key = ?", (key,))
+        row = cursor.fetchone()
+        return row["value"] if row else None
+
+    def get_all_metadata(self) -> dict[str, str]:
+        """Return all metadata as a dictionary."""
+        conn = self._require_conn()
+        cursor = conn.execute("SELECT key, value FROM metadata ORDER BY key")
+        return {row["key"]: row["value"] for row in cursor.fetchall()}
+
+    def insert_verses(self, verses: Iterable[Verse]) -> None:
+        """Bulk-insert verses in a single transaction.
+
+        Does not rebuild the FTS index; call :meth:`rebuild_fts` afterwards.
+        """
+        conn = self._require_conn()
+        conn.executemany(
+            "INSERT OR REPLACE INTO verses (verse_key, book_id, chapter, verse, text)"
+            " VALUES (?, ?, ?, ?, ?)",
+            [(v.key, v.book_id, v.chapter, v.verse, v.text) for v in verses],
+        )
+        conn.commit()
+
+    def rebuild_fts(self) -> None:
+        """Rebuild the FTS5 index from the external-content verses table."""
+        conn = self._require_conn()
+        conn.execute("INSERT INTO verses_fts(verses_fts) VALUES('rebuild')")
+        conn.commit()
+
+    def count_verses(self) -> int:
+        """Return the total number of stored verses."""
+        conn = self._require_conn()
+        cursor = conn.execute("SELECT COUNT(*) AS n FROM verses")
+        return int(cursor.fetchone()["n"])
+
+    def verses_in_ranges(self, ranges: Sequence[tuple[int, int]]) -> list[Verse]:
+        """Return verses whose key falls in any of the given key ranges.
+
+        Args:
+            ranges: ``(start_key, end_key)`` pairs (inclusive).
+
+        Returns:
+            Matching verses ordered by verse key (i.e. canonical order).
+
+        """
+        conn = self._require_conn()
+        clause, params = _range_clause(ranges)
+        cursor = conn.execute(
+            "SELECT verse_key, book_id, chapter, verse, text FROM verses"
+            f" WHERE {clause} ORDER BY verse_key",
+            params,
+        )
+        return [_row_to_verse(row) for row in cursor.fetchall()]
+
+    def search(
+        self,
+        query: str,
+        limit: int,
+        ranges: Sequence[tuple[int, int]] | None = None,
+        order: str = "canonical",
+    ) -> list[Verse]:
+        """Full-text search verse text.
+
+        Args:
+            query: FTS5 MATCH query.
+            limit: Maximum number of verses to return.
+            ranges: Optional key ranges to restrict the search to.
+            order: ``"canonical"`` for verse-key (Bible) order, or
+                ``"relevance"`` for FTS5 bm25 rank (best first), tie-broken by
+                verse key.
+
+        Returns:
+            Matching verses in the requested order, capped at ``limit``.
+
+        """
+        if order not in ("canonical", "relevance"):
+            raise ValueError(f"Invalid order {order!r}: use 'canonical' or 'relevance'.")
+        conn = self._require_conn()
+        sql = [
+            "SELECT v.verse_key, v.book_id, v.chapter, v.verse, v.text",
+            "FROM verses_fts f JOIN verses v ON v.verse_key = f.rowid",
+            "WHERE f.text MATCH ?",
+        ]
+        params: list[Any] = [query]
+        if ranges is not None:
+            clause, range_params = _range_clause(ranges)
+            sql.append(f"AND {clause}")
+            params.extend(range_params)
+        if order == "relevance":
+            sql.append("ORDER BY f.rank, v.verse_key")
+        else:
+            sql.append("ORDER BY v.verse_key")
+        sql.append("LIMIT ?")
+        params.append(limit)
+        cursor = conn.execute("\n".join(sql), params)
+        return [_row_to_verse(row) for row in cursor.fetchall()]
+
+    def count_matches(
+        self, query: str, ranges: Sequence[tuple[int, int]] | None = None
+    ) -> int:
+        """Count verses matching an FTS5 query (ignoring any limit)."""
+        conn = self._require_conn()
+        sql = ["SELECT COUNT(*) AS n FROM verses_fts f WHERE f.text MATCH ?"]
+        params: list[Any] = [query]
+        if ranges is not None:
+            clause, range_params = _range_clause(ranges)
+            # f.rowid is the verse_key; reuse the same clause column name.
+            sql.append("AND " + clause.replace("verse_key", "f.rowid"))
+            params.extend(range_params)
+        cursor = conn.execute("\n".join(sql), params)
+        return int(cursor.fetchone()["n"])
+
+
+def _row_to_verse(row: sqlite3.Row) -> Verse:
+    return Verse(
+        key=row["verse_key"],
+        book_id=row["book_id"],
+        chapter=row["chapter"],
+        verse=row["verse"],
+        text=row["text"],
+    )

versiref_bible-0.1.0/src/versiref/bible/models.py

@@ -0,0 +1,48 @@
+"""Data models for versiref-bible."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Verse:
+    """A single Bible verse stored in the database.
+
+    Attributes:
+        key: Integer verse key (BBCCCVVV) from ``range_keys`` under the
+            database's versification; also the FTS5 rowid.
+        book_id: Paratext book ID (e.g. ``JHN``).
+        chapter: Chapter number.
+        verse: Verse number.
+        text: Verse text.
+
+    """
+
+    key: int
+    book_id: str
+    chapter: int
+    verse: int
+    text: str
+
+
+@dataclass
+class BuildStats:
+    """Summary of a ``build`` run, for reporting to the operator.
+
+    Attributes:
+        stored: Number of verses written to the database.
+        unknown_books: Abbreviation -> count for tokens the book style did not
+            recognize (e.g. the Sirach prologue ``Sip``).
+        off_scheme_books: Abbreviation -> count for books not present in the
+            chosen versification (no integer key can be computed).
+        malformed: Number of non-blank lines that did not parse as
+            ``Abbrev C:V text``.
+        duplicates: Number of lines whose verse key collided with an earlier
+            line (later line wins).
+
+    """
+
+    stored: int = 0
+    unknown_books: dict[str, int] = field(default_factory=dict)
+    off_scheme_books: dict[str, int] = field(default_factory=dict)
+    malformed: int = 0
+    duplicates: int = 0

versiref_bible-0.1.0/src/versiref/bible/reader.py

@@ -0,0 +1,123 @@
+"""Query a Bible database: show verses by reference and full-text search."""
+
+import sqlite3
+from pathlib import Path
+
+from versiref import RefParser, RefStyle, SimpleBibleRef, Versification
+
+from .database import Database
+from .models import Verse
+
+
+def _db_versification(db: Database) -> Versification:
+    """Return the versification a database was built with."""
+    name = db.get_metadata("versification")
+    if name is None:
+        raise ValueError("Database has no 'versification' metadata; rebuild it.")
+    return Versification.named(name)
+
+
+def format_verse(verse: Verse, style: RefStyle, versification: Versification) -> str:
+    """Format a verse as ``reference<TAB>text`` for plain-text output.
+
+    The reference label is formatted with ``style`` under ``versification``;
+    verse text is single-line in CCAT, so the tab keeps the line unambiguous.
+    """
+    label = SimpleBibleRef.for_range(
+        verse.book_id, verse.chapter, verse.verse
+    ).format(style, versification)
+    return f"{label}\t{verse.text}"
+
+
+def show_verses(
+    db_path: str | Path,
+    reference: str,
+    *,
+    style_name: str = "en-sbl",
+    from_versification: str | None = None,
+) -> tuple[list[Verse], Versification]:
+    """Return the verses covered by a Bible reference.
+
+    Args:
+        db_path: Path to the Bible database.
+        reference: A Bible reference string (parsed by versiref).
+        style_name: Reference style used to parse ``reference`` and to label
+            output (default ``en-sbl``).
+        from_versification: If given, interpret ``reference`` in this
+            versification and map it to the database's versification.
+
+    Returns:
+        ``(verses, db_versification)`` — verses in canonical order plus the
+        database's versification (for labelling).
+
+    Raises:
+        ValueError: If the reference cannot be parsed.
+
+    """
+    with Database(db_path) as db:
+        db_vers = _db_versification(db)
+        source_vers = (
+            Versification.named(from_versification)
+            if from_versification is not None
+            else db_vers
+        )
+        parser = RefParser(RefStyle.named(style_name), source_vers)
+        ref = parser.parse(reference, silent=True)
+        if ref is None:
+            raise ValueError(f"Could not parse reference: {reference!r}")
+        if from_versification is not None:
+            mapped = ref.map_to(db_vers)
+            if mapped is None:
+                raise ValueError(
+                    f"Could not map {reference!r} from {from_versification} to "
+                    f"the database's versification."
+                )
+            ref = mapped
+        verses = db.verses_in_ranges(list(ref.range_keys()))
+        return verses, db_vers
+
+
+def search_verses(
+    db_path: str | Path,
+    query: str,
+    *,
+    limit: int = 20,
+    scope: str | None = None,
+    order: str = "canonical",
+    style_name: str = "en-sbl",
+) -> tuple[list[Verse], int, Versification]:
+    """Full-text search verse text.
+
+    Args:
+        db_path: Path to the Bible database.
+        query: FTS5 MATCH query.
+        limit: Maximum number of verses to return.
+        scope: Optional Bible reference restricting the search (parsed in the
+            database's versification).
+        order: ``"canonical"`` for verse (Bible) order, or ``"relevance"`` for
+            bm25 rank (best first, tie-broken by verse order).
+        style_name: Reference style used to parse ``scope`` and to label output.
+
+    Returns:
+        ``(verses, total_matches, db_versification)`` where ``total_matches``
+        is the match count before ``limit`` was applied.
+
+    Raises:
+        ValueError: If the scope reference or the FTS query is invalid.
+
+    """
+    with Database(db_path) as db:
+        db_vers = _db_versification(db)
+        ranges: list[tuple[int, int]] | None = None
+        if scope is not None:
+            parser = RefParser(RefStyle.named(style_name), db_vers)
+            scope_ref = parser.parse(scope, silent=True)
+            if scope_ref is None:
+                raise ValueError(f"Could not parse scope reference: {scope!r}")
+            ranges = list(scope_ref.range_keys())
+        try:
+            results = db.search(query, limit, ranges, order)
+            total = db.count_matches(query, ranges)
+        except sqlite3.OperationalError as exc:
+            raise ValueError(f"Invalid search query {query!r}: {exc}") from exc
+        return results, total, db_vers