Skip to main content

Tools to work with USFM references

Project description


Build Status Coverage Status

A validator & lookup tool for USFM (Unified Standard Format Markers) Biblical references.


This project requires Python 3.6 or higher


To install use

pip install usfm-references


Import one of the methods like

from usfm_references import valid_chapter, valid_chapter_or_intro, valid_usfm, valid_verse, valid_multi_usfm

The validation methods all start with valid_. They take a single parameter which should be a string representation of a USFM reference. And they all return a boolean value representing whether the string was valid for the type that the method is validating against.

For example, if you have a string my_reference with a reference of Genesis 1:1, the appropriate USFM reference would be GEN.1.1. You could use the valid_verse method to ensure it is correct like

if valid_verse(my_reference):
    # do stuff

NOTE: These validators match a regular expression pattern. That conforms to the general USFM standard. They do NOT ensure that the USFM actually exists in any particular Bible version.

The currently supported validators are:

  • valid_chapter - Ensures the passed string is a valid USFM chapter reference
  • valid_chapter_or_intro - Ensures the passed string is either a valid USFM chapter or intro reference
  • valid_usfm - Ensures the passed string is a valid USFM reference (can be verse, chapter, or intro)
  • valid_multi_usfm - Ensures that the passed string is a valid set of USFM reference (can be verse, chapter, or intro)
  • valid_verse - Ensures the passed string is a valid USFM verse reference

Other methods include conversion such as convert_book_to_canon. Import like:

from usfm_references import convert_book_to_canon

Conversion methods all start with convert_ and the method names should be self-explanatory as far as what params go in and what is returned.

convert_book_to_canon can be used like:

canon = convert_book_to_canon("GEN")
print(canon)  # "ot"


This project is tested in CI with Python 3.6-3.8. One of these must be installed before developing and testing locally.

This project uses pip-tools for dependency management.

Running tests

./ && pytest --cov=usfm_references tests/

Before committing any code

We have a pre-commit hook which can be used to run linters before committing. You can symlink it to run before each commit by changing directory to the repo and running

cd .git/hooks
ln -s ../../pre-commit pre-commit

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

USFM References-1.4.0.tar.gz (5.5 kB view hashes)

Uploaded Source

Built Distribution

USFM_References-1.4.0-py2.py3-none-any.whl (5.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page