core.utils.bible_data_loader

File:: EuljiroWorship/core/utils/bible_data_loader.py
Author:: Benjamin Jaedon Choi - https://github.com/saintbenjamin
Affiliated Church:: The Eulji-ro Presbyterian Church [대한예수교장로회(통합) 을지로교회]
Address:: The Eulji-ro Presbyterian Church, 24-10, Eulji-ro 20-gil, Jung-gu, Seoul 04549, South Korea
Telephone:: +82-2-2266-3070
E-mail:: euljirochurch [at] G.M.A.I.L. (replace [at] with @ and G.M.A.I.L as you understood.)
License:: MIT License with Attribution Requirement (see LICENSE file for details); Copyright (c) 2025 The Eulji-ro Presbyterian Church.

Handles lazy loading and caching of Bible text and metadata from JSON sources.

This module provides a unified data access layer for Bible-related resources, including:

Bible version aliases
Book name aliases
Canonical book names
Custom sort order
Full Bible text data

All Bible text JSON files are loaded lazily and cached in memory on first access to minimize startup cost and disk I/O.

class core.utils.bible_data_loader.BibleDataLoader(json_dir=None, text_dir=None)[source]

Bases: object

Lazy-loading data manager for Bible text and metadata.

This loader provides on-demand (lazy) access to Bible JSON resources and caches loaded content in memory to avoid repeated disk I/O.

It loads and exposes:

Version alias metadata (e.g., full name → short label)
Book alias / canonical naming metadata
Canonical book name table (per language)
Version sort order metadata
Per-version Bible text JSON files (loaded only when first accessed)

The class is shared by both EuljiroBible and EuljiroWorship and therefore keeps several compatibility helpers and legacy-style accessors.

json_dir

Directory containing Bible metadata JSON files (aliases, canonical names, and sort order).

Type:: str

text_dir

Directory containing Bible text JSON files (per-version text).

Type:: str

aliases_version

Parsed content of aliases_version.json. Typically maps a version key to either a string alias or a nested dict containing localized aliases, depending on your data schema.

Type:: dict

aliases_book

Parsed content of aliases_book.json. Used for book name aliasing and compatibility mapping.

Type:: dict

standard_book

Parsed content of standard_book.json. Maps canonical book IDs to a per-language display name dictionary (e.g., {"John": {"ko": "...", "en": "John"}}).

Type:: dict

sort_order

Parsed content of the configured sort-order JSON (e.g., prefix → rank). Used by get_sort_key() for stable version ordering in UI/CLI.

Type:: dict

data

In-memory cache of loaded Bible text, keyed by version key. Structure is typically data[version][book][chapter][verse] = text.

Type:: dict

Note

Version JSON is loaded lazily by get_verses(). Use load_version() or load_versions() to preload explicitly.
Some methods exist primarily for cross-project compatibility and are not necessarily used by every code path.

__init__(json_dir=None, text_dir=None)[source]

Initialize the Bible data loader.

Optional directory overrides can be supplied for testing or alternative data layouts.

Parameters:

json_dir (str, optional) – Directory containing Bible metadata JSON files (aliases, canonical names, sort order).
text_dir (str, optional) – Directory containing Bible text JSON files.

Returns:

None

get_verses(version)[source]

Retrieve all verses for a given Bible version.

The version data is loaded from disk only once and cached internally for subsequent access.

Parameters:: version (str) – Bible version key (e.g. “NKRV”, “KJV”).
Returns:: Nested dictionary structure containing the full Bible text for the specified version.
Return type:: dict

get_books_for_version(version)[source]

Return the list of books available in a given Bible version.

Parameters:: version (str) – Bible version key.
Returns:: List of book identifiers present in the version.
Return type:: list

_load_json(file_path)[source]

Safely load a JSON file and return its contents.

If loading fails, an empty dictionary is returned and a warning is printed to the console.

Parameters:: file_path (str) – Absolute path to the JSON file.
Returns:: Parsed JSON content, or an empty dict on failure.
Return type:: dict

get_standard_book(book_id, lang_code)[source]

Return the localized canonical name of a Bible book.

Parameters:

book_id (str) – Canonical book identifier (e.g. “John”).
lang_code (str) – Language code (e.g. “ko”, “en”).

Returns:

Localized book name if available, otherwise the book ID.

Return type:

str

get_sort_key()[source]

Return a sorting key function for Bible version names.

The key function sorts versions using a predefined regional prefix order followed by lexicographical ordering.

This method is required by both GUI and CLI code paths. DO NOT DELETE.

Parameters:: None
Returns:: Callable suitable for use as the key argument in sorted().
Return type:: function

load_version(version_key)[source]

Explicitly load a Bible version into memory.

This method forces loading even if lazy access has not yet occurred.

Parameters:: version_key (str) – Bible version key (filename without extension).
Returns:: None

load_versions(target_versions=None)[source]

Load multiple Bible versions into memory.

If no target list is provided, all available versions in the text directory are loaded.

Parameters:: target_versions (list, optional) – List of version keys to load.
Returns:: None

get_max_verse(version, book, chapter)[source]

Return the maximum verse number for a given chapter.

Parameters:

version (str) – Bible version key.
book (str) – Book identifier.
chapter (int) – Chapter number.

Returns:

Maximum verse number, or 0 if unavailable.

Return type:

int

extract_verses(versions, book, chapter, verse_range)[source]

Extract a specific verse range across multiple Bible versions.

Parameters:

versions (list) – List of Bible version keys.
book (str) – Book identifier.
chapter (int) – Chapter number.
verse_range (tuple) – (start, end) or (start, -1) for full chapter.

Returns:

Nested dictionary of extracted verses grouped by version.

Return type:

dict

get_verses_for_display(versions=None, book=None, chapter=None, verse_range=None)[source]

Return either a filtered verse subset or full Bible data.

Parameters:

versions (list, optional) – Bible version keys.
book (str, optional) – Book identifier.
chapter (int, optional) – Chapter number.
verse_range (tuple, optional) – Verse range.

Returns:

Structured Bible text data.

Return type:

dict

get_book_alias(lang_code='ko')[source]

Return mapping of book IDs to localized aliases.

Parameters:: lang_code (str) – Language code.
Returns:: Mapping of book_id -> localized name.
Return type:: dict

get_version_alias(lang_code='ko')[source]

Return mapping of Bible version keys to localized aliases.

Parameters:: lang_code (str) – Language code.
Returns:: Mapping of version_key -> alias string.
Return type:: dict

get_verse(version, book, chapter, verse)[source]

Retrieve a single verse from the loaded Bible data.

This method exists for compatibility with the EuljiroWorship system.

Parameters:

version (str) – Bible version key.
book (str) – Book identifier.
chapter (int) – Chapter number.
verse (int) – Verse number.

Returns:

Verse text if found, otherwise None.

Return type:

str | None