Metadata-Version: 2.5
Name: bible-figures-of-speech
Version: 0.1.0
Summary: Figures of speech in the Bible: a catalog of figure types and verse-indexed instances, derived from unfoldingWord Translation Notes.
Project-URL: Homepage, https://github.com/TangoGroup/figures-of-speech
Project-URL: Issues, https://github.com/TangoGroup/figures-of-speech/issues
Author-email: Gloo <noreply@gloo.us>
License-Expression: MIT AND CC-BY-SA-4.0
License-File: LICENSE
License-File: src/bible_figures_of_speech/data/LICENSE
Keywords: bible,bible-translation,figures-of-speech,translation-notes,unfoldingword
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Religion
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Religion
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.12
Requires-Dist: biblelib>=0.6
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# figures-of-speech

Dataset describing biblical figures of speech and listing instances. 

The original figures of speech data comes from unfoldingWord's
[translationCore® —
unfoldingWord](https://translationcore.com/translationcore/) suite,
and is provided under a [CC BY-SA 4.0
License](https://door43.org/en/copyright-and-licensing/).

The data was
reorganized and extended by Sean Boisen (Gloo, LLC), and is provided
under a [CC BY-SA 4.0
License](https://door43.org/en/copyright-and-licensing/). 

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.

```bash
pip install bible-figures-of-speech
```

Or, before a PyPI release, straight from GitHub:

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

Requires Python 3.12 or 3.13 (the upper bound comes from
[biblelib](https://pypi.org/project/biblelib/), used for verse references).

## Usage

```python
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`](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`](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

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