core.utils.utils_output

File:

EuljiroBible/core/utils/utils_output.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.

Provides functions for formatting Bible verses and saving them atomically to output files for EuljiroBible. Handles both GUI and CLI output logic.

core.utils.utils_output.format_output(versions, book, chapter, verse_range, verses_dict, tr, for_whitebox=False, lang_code='ko', bible_data=None, version_alias=None, book_alias=None)[source]

Formats Bible verses into a string for display or file output. Handles single/multiple versions, single verse or range, and appends metadata footer.

Parameters:

  • versions (list) – Selected Bible versions.

  • book (str) – Canonical book key (e.g., “Genesis”).

  • chapter (int) – Chapter number.

  • verse_range (tuple) – (start_verse, end_verse), (-1 for full chapter).

  • verses_dict (dict) – Nested verse dictionary structure.

  • tr (function) – Translation function (GUI: Qt tr, CLI: identity).

  • for_whitebox (bool) – Whether formatting is for overlay whitebox.

  • lang_code (str) – Language code (e.g., “ko”, “en”).

  • bible_data (BibleDataLoader, optional) – Optional Bible data access.

  • version_alias (dict, optional) – Version aliases mapping.

  • book_alias (dict, optional) – Book name alias mapping.

Returns:

Final formatted multi-line text.

Return type:

str

core.utils.utils_output.atomic_write(path, content, retries=5, delay=0.5)[source]

Atomically writes content to file using .tmp replacement pattern. Prevents data corruption and handles permission issues gracefully.

Parameters:

  • path (str) – Output file path.

  • content (str) – Text content to write.

  • retries (int) – Retry attempts on failure (default 5).

  • delay (float) – Seconds between retries.

Raises:

Exception – Re-raised if final write attempt fails.

core.utils.utils_output.resolve_output_path(settings, key='output_path')[source]

Resolves and validates output path from user settings. Ensures directory exists and avoids invalid platform-specific paths.

Parameters:

  • settings (dict) – User/application settings.

  • key (str) – Settings key to read path from.

Returns:

Absolute, safe output path.

Return type:

str

core.utils.utils_output.save_to_files(merged, settings, parent=None)[source]

Saves the final merged text to disk using an atomic write strategy. Ensures the file’s modified timestamp is updated so that external listeners (e.g., slide interruptor) can detect the change.

Parameters:

  • merged (str) – Final display text to save.

  • settings (dict) – Configuration containing output path.

  • parent (QWidget, optional) – For GUI error dialogs. Defaults to None.