usfmtc 0.4

USFM reference parser

USFMTC Module

Introduction

The USFMTC module is a module for reading and writing USFM scripture files in all their formats: USFM, USX and USJ. It is designed to be a reference implementation of the standard. It also has support for Scripture References.

import sys, usfmtc
from usfmtc.versification import cached_versification
from usfmtc.reference import Ref, RefList

engvrs = cached_versification("eng")   # can also be a path to a .vrs file
usxdoc = usfmtc.readFile(sys.argv[1])
usxdoc.canonicalise()
# usxdoc.reversify(engvrs, None)
usxdoc.saveAs(sys.argv[2])

r = Ref("ISA 9:1-4")      # returns a RefRange
canr = engvrs.remap(r, None)    # one way conversion
print(canr)     # prints "ISA 8:23-9:3"
rlist = RefList("JHN 3:16, GEN 1:1, PSA 23, ISA 53, PSA 23:1")
print(rlist.simplify())     # GEN 1:1; PSA 23; ISA 53; JHN 3:16
print(Ref("PSA 23").end())  # PSA 23:6
print(Ref("PSA 23:10").isvalid())   # False

newdoc = usxdoc.getrefs(Ref("PSA 23:2-4"))
print(newdoc.outUsfm(None))     # A new doc of just PSA 23:2-4

The internal representation of the data is as an ElementTree structure conforming to the USX standard.

See the tests/test_\*.py files for more examples. See also pydoc usfmtc.

Utilities

usfmtc comes with a few utilities:

• usfmconv: Converts from one serialisation to another
• usfmreversify: Change the versification of a file to something different
• urnc2rng: Convert to relax-NG

Installation

python3 -m venv venv
source venv/bin/activate
pip install .

To install the dev profile with extra optional dependencies:

pip install .[dev]