bible-io 1.1.0

Bible parsing package

Bible-IO

A Python package for loading and working with structured Bible text data. The package reads JSON exports of Bible translations and exposes convenient classes for navigating books, chapters, and verses or running simple searches.

Features

• Parse Bible translations from JSON files into rich Python objects.
• Access books, chapters, and verses via BibleBookEnum or numeric helper methods.
• Run fast, case-insensitive word searches using a cached reverse index across all verses.
• Pythonic error handling with custom exceptions for missing references.

Installation

Install the package from PyPI:

pip install bible-io

Python 3.10 or later is required.

Getting Started

from bible_io import Bible, BibleBookEnum

# Load a translation exported in the supported JSON structure
# The loader accepts either strings or Path objects.
bible = Bible("path/to/en_kjv.json")

# Retrieve a specific chapter (Genesis 1) using the enum identifiers
for verse in bible.get_verses(BibleBookEnum.Genesis, 1):
    print(f"Genesis 1:{verse.verse_number} {verse.text}")

# Access a book via the BibleBookEnum or by numeric index
john = bible.get_book(BibleBookEnum.John)
acts = bible.get_book_by_id(44)  # Book numbers are 1-indexed

# Fetch John 3:16 and print the verse text
john_316 = john.get_verse(3, 16)
print(john_316.text)

# Parse refs directly from text using the Bible's JSON language metadata
print(bible.get_verse_by_ref("John 3:16").text)
for verse in bible.get_verse_range_by_ref("John 3:16-18"):
    print(verse)

# Or use one helper that accepts either a single verse or a range
result = bible.get_by_ref("John 3:16-18")
print(result)

# Search the entire translation (case-insensitive)
for verse in bible.search("shepherd"):
    print(verse)

# If you edit verse text at runtime, refresh the cached search index
bible.invalidate_search_index()

The high-level API centres around four classes:

• Bible - container for all loaded books and the cached search index.
• Book - holds the chapters of a single Bible book.
• Chapter - manages the verses inside a chapter and validates access.
• Verse - stores an individual verse with helpers such as contains_word.

Additional helper enums are re-exported from bible_io, and exceptions live in bible_io.errors.

Search Index

Repeated searches reuse a cached word-to-verse index that is generated on demand. Queries are normalized by lowercasing and removing punctuation, and multi-word searches return deduplicated matches for any token in the phrase. If you mutate verse text after loading (for example, when normalizing or annotating data), call invalidate_search_index() on the Bible instance so the next search rebuilds the index with the updated content.

JSON Structure

The loader expects Bible data in the following JSON format:

{
    "id": "kjv",
    "name": "King James Version",
    "description": "The King James Version (Oxford 1769) is a standardized revision of the classic 1611 English Bible.",
    "language": "English",
    "books": {
        "gn": {
            "name": "Genesis",
            "chapters": {
                "1": {
                    "1": "In the beginning God created the heaven and the earth.",
                    "2": "And the earth was without form, and void; and darkness {was} upon the face of the deep. And the Spirit of God moved upon the face of the waters.",
                    "3": "And God said, Let there be light: and there was light."
                },
                "2": {
                    "1": "Thus the heavens and the earth were finished, and all the host of them.",
                    "2": "And on the seventh day God ended his work which he had made; and he rested on the seventh day from all his work which he had made.",
                    "3": "And God blessed the seventh day, and sanctified it: because that in it he had rested from all his work which God created and made. "
                }
            }
        }
    }
}

Each book entry uses a compact abbreviation (e.g., "gn" for Genesis). The loader maps these abbreviations onto BibleBook enum members and constructs the corresponding hierarchy of Book, Chapter, and Verse objects.

Check https://github.com/m0ty/bible-io-json repository for ready to use bible .json files.

Running the Tests

The repository uses pytest for automated tests. After installing the package's dependencies (via pip install . or pip install -e .), run:

pytest

If you prefer uv, you can run the suite via:

uv run pytest

The test suite expects the sample translation at test/bible_versions/en_kjv.json.

License

MIT License - see the LICENSE file for details.