core.utils.bible_data_loader

File:: EuljiroBible/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

get_available_versions()[source]

Return all Bible version keys that actually exist under the text directory.

This method inspects the Bible text directory directly and derives version keys from the available *.json filenames. It is used when the application needs the true list of install-time/runtime-available Bible versions instead of relying on alias metadata files.

Returns:: Sorted list of version keys derived from <text_dir>/*.json.
Return type:: List[str]

Note

Failures while scanning the directory are logged and an empty list is returned so callers can fail gracefully.

_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_version_display_name(version_key, lang_code='ko')[source]

Return a user-facing display label for a Bible version.

The display label prefers aliases_version.json when available and falls back to the raw version key (usually the source JSON filename without extension).

Parameters:

version_key (str) – Bible version key / filename stem.
lang_code (str) – Language code used when alias entries are nested dictionaries.

Returns:

Alias label when available, otherwise version_key.

Return type:

str

Note

This method is intentionally display-oriented. It does not validate whether the version exists on disk; callers should pair it with get_available_versions() when availability matters.

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