figures-of-speech

Dataset describing biblical figures of speech and listing instances.

The original figures of speech data comes from unfoldingWord's translationCore® — unfoldingWord suite, and is provided under a CC BY-SA 4.0 License.

The data was reorganized and extended by Sean Boisen (Gloo, LLC), and is provided under a CC BY-SA 4.0 License.

The code for accessing the data is by Drew Bronson (Gloo) and is provided under an MIT license.

Note there is no data for these books:

• NUM
• 1CH
• 2CH
• ECC
• ISA
• JER
• EZK
• DAN
• AMO
• ZEC

Install

The Python package is bible-figures-of-speech. The data (19 figure types and about 27,000 verse-indexed instances) ships inside it, so no separate download or checkout is needed.

pip install bible-figures-of-speech

Or, before a PyPI release, straight from GitHub:

pip install git+https://github.com/TangoGroup/figures-of-speech

Requires Python 3.12 or 3.13 (the upper bound comes from biblelib, used for verse references).

Usage

from bible_figures_of_speech import FiguresOfSpeech

fos = FiguresOfSpeech()  # loads the bundled data

# The type catalog, keyed by translationAcademy slug
metaphor = fos.types["figs-metaphor"]
print(metaphor.label, "-", metaphor.summary)

# Instances overlapping a passage
for note in fos.notes_for("JUD 1:2-4"):
    print(note.ref, note.title, note.translation)
    print(note.alternate_translations)

# Everything for one book, or the whole dataset
mark = fos.instances("MRK")
total = sum(1 for _ in fos.iter_instances())

notes_for() accepts a USFM reference string ("MRK 1:2", "MRK 1:4-8", "MRK 1:40-2:3", "ROM 3:1-ROM 3:9"), a biblelib BCVID or BCVIDRange, or any object with .start and .end verses that have .book, .chapter and .verse (the PassageLike protocol). Each instance's passage is a biblelib BCVIDRange.

Each FigureInstance keeps all of the source fields (id, ref, source_text, translation, original_comment, and comments as a tuple of Comment(comment, alternate_translations)), joined to its FigureType as figure. For convenience, it also offers title, comment and alternate_translations (from the first interpretation), plus body, a display-ready summary.

To load a different copy of the data (for example, a newer snapshot), pass its directory: FiguresOfSpeech(Path("path/to/figures_of_speech")).

Data

See src/bible_figures_of_speech/data/README.md for the full field-by-field description, scope and known limitations, and src/bible_figures_of_speech/data/LICENSE for the data license and attribution. The data is a snapshot generated 2026-09-16. Attribution constants are available as bible_figures_of_speech.PUBLISHER, DATA_LICENSE and DATA_LICENSE_URL.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv build