usfm-references

Utilities for parsing, validating and manipulating USFM (Unified Standard Format Markers) references.

This library provides:

• validators for USFM strings (verse, chapter, intro, multi references)
• a Reference model for composing and formatting references

Requirements

Python 3.9 or newer. The project CI runs on 3.9–3.12.

Installation

Install from PyPI:

pip install usfm-references

Quick Usage

Validate USFM reference strings using the valid_ helpers:

from usfm_references import valid_verse, valid_chapter, valid_multi_usfm

valid_verse("GEN.1.1")               # True
valid_chapter("GEN.1")               # True
valid_multi_usfm("GEN.1.1+GEN.1.3")  # True

Get a book's canon grouping:

from usfm_references import convert_book_to_canon

convert_book_to_canon("GEN")  # 'ot'

Look up a USFM book code from an English book name or common abbreviation:

from usfm_references import convert_book_name_to_usfm

convert_book_name_to_usfm("Genesis")          # 'GEN'
convert_book_name_to_usfm("Gen")              # 'GEN'
convert_book_name_to_usfm("1 Samuel")         # '1SA'
convert_book_name_to_usfm("I Samuel")         # '1SA'
convert_book_name_to_usfm("Song of Solomon")  # 'SNG'
convert_book_name_to_usfm("Apocalypse")       # 'REV'
convert_book_name_to_usfm("GEN")              # 'GEN'  (USFM codes pass through)
convert_book_name_to_usfm("Not a book")       # None

The lookup is case-insensitive and ignores surrounding whitespace and trailing punctuation. Numbered books accept arabic, roman, and word forms (e.g. 1Sam, I Sam, First Samuel). Returns None for unrecognized input.

Reference Model

The Reference dataclass is a convenient way to parse, build and format USFM references. It normalizes verse ranges (they are kept sorted and merged when intersecting or adjacent).

Examples:

from usfm_references import Reference

Reference.from_string("GEN.1")                # whole chapter -> Reference(book='GEN', chapter=1)
Reference.from_string("GEN.1.1-3")            # verse range -> verses [(1, 3)]
Reference.from_string("GEN.1.1+GEN.1.3")      # multiple verses -> verses [(1, 1), (3, 3)]
Reference.from_string("GEN.INTRO1")           # intro chapter -> intro=1

# Overlapping/adjacent ranges are merged:
str(Reference.from_string("GEN.1.1+GEN.1.2+GEN.1.3"))  # 'GEN.1.1-3'

Development

For local development, create a venv and install dev dependencies (project uses pip-tools):

make venv

Run linting and formatting:

make lint

Run tests:

make test

A pre-commit hook is provided to lint and run tests before each commit. To install it, run:

(cd .git/hooks && ln -s ../../pre-commit pre-commit)