usfm3

usfm3 is a Python binding for the Rust usfm3 parser.

It exposes a staged API so live-editor code can stay on tokens/CST until it actually needs AST-backed output.

Installation

pip install usfm3

Quick Start

import usfm3

parsed = usfm3.parse(text)

tokens = usfm3.tokenize(text)
cst = usfm3.parse_cst(text)
ast_document = usfm3.parse_ast(text, diagnostics=True)

ast = parsed.ast()
source_map = parsed.source_map()
diagnostics = parsed.diagnostics

usj = parsed.to_usj()
usj_with_spans = parsed.to_usj(spans=True)
usx = parsed.to_usx()
usfm = parsed.to_usfm()
vref = parsed.to_vref()

API

`usfm3.parse(usfm: str, diagnostics: bool = False) -> ParsedDocument`

Returns a lazy parsed handle.

`usfm3.parse_cst(usfm: str) -> dict`

Returns a JSON-friendly CST tree.

`usfm3.parse_ast(usfm: str, diagnostics: bool = False) -> dict`

Returns:

{
    "ast": ...,
    "source_map": ...,
    "diagnostics": list | None,
}

`usfm3.tokenize(usfm: str) -> list[dict]`

Returns token spans suitable for editor tooling.

`ParsedDocument`

cst() -> dict
ast() -> dict
source_map() -> dict
to_usj(spans: bool = False) -> dict
to_usx() -> str
to_usfm() -> str
to_vref() -> dict[str, str]
diagnostics -> list[dict] | None

Notes

Diagnostics are only computed when diagnostics=True.
Diagnostics are a flat list with severity, code, message, span, and optional anchor_cst.
AST nodes do not include spans.
spans=True on to_usj() derives inline span data from the source map.

License

MIT

Metadata

Release files for usfm3 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for usfm3 0.2.1
File	Size	Uploaded
usfm3-0.2.1.tar.gz	81.5 kB	May 11, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for usfm3 0.2.1
File	Interpreter	ABI	Platform	Reset
usfm3-0.2.1-cp313-cp313-win_amd64.whl 292.3 kB May 11, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details
usfm3-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 442.4 kB May 11, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.17+ x86-64	Details
usfm3-0.2.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 434.9 kB May 11, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.17+ ARM64	Details
usfm3-0.2.1-cp313-cp313-macosx_11_0_arm64.whl 389.6 kB May 11, 2026	CPython 3.13	CPython 3.13	macOS 11.0+ ARM64	Details

Total release size: 1.6 MB

Release files / usfm3-0.2.1.tar.gz

Download URL	usfm3-0.2.1.tar.gz
Size	81.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`2a7f0c5a18f2a39f09ebb666bd10389d28844d42aada10ffe90bf7a714744c55`
BLAKE2b-256 checksum How to use checksums	`1452017a60d3bb6d07a529596bdef5a346acbf68ccea3eaf90ed244c8d1f856b`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jcuenod/usfm3
Publishing commit: github.com/jcuenod/usfm3/tree/da23f604fb0defe5c9d174e936902337e156f179

Workflow

Publishing configuration: github.com/jcuenod/usfm3/blob/da23f604fb0defe5c9d174e936902337e156f179/.github/workflows/publish-pypi.yml
Publishing logs: github.com/jcuenod/usfm3/actions/runs/25696661125/attempts/1

Artifact

Subject: usfm3-0.2.1.tar.gz
SHA-256 checksum: 2a7f0c5a18f2a39f09ebb666bd10389d28844d42aada10ffe90bf7a714744c55 Verifying attestations

Release files / usfm3-0.2.1-cp313-cp313-win_amd64.whl

Download URL	usfm3-0.2.1-cp313-cp313-win_amd64.whl
Size	292.3 kB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`21f84a2e331c4acdebfae2a70c25eaf0e9d44089d25b73616154f9198720064c`
BLAKE2b-256 checksum How to use checksums	`c5c01b43af749b6bb17b50b055cdb4a8f724e1648c21689f3601379da19eccca`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jcuenod/usfm3
Publishing commit: github.com/jcuenod/usfm3/tree/da23f604fb0defe5c9d174e936902337e156f179

Workflow

Publishing configuration: github.com/jcuenod/usfm3/blob/da23f604fb0defe5c9d174e936902337e156f179/.github/workflows/publish-pypi.yml
Publishing logs: github.com/jcuenod/usfm3/actions/runs/25696661125/attempts/1

Artifact

Subject: usfm3-0.2.1-cp313-cp313-win_amd64.whl
SHA-256 checksum: 21f84a2e331c4acdebfae2a70c25eaf0e9d44089d25b73616154f9198720064c Verifying attestations

Release files / usfm3-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	usfm3-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	442.4 kB
Tags	CPython 3.13 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`f5d7f76a702147b5ac7b2b7e72d83575d9abb6ac6f78c6339710005d579fc705`
BLAKE2b-256 checksum How to use checksums	`c9d4041112910d637bad950798000d25632a4a7a1cdebead81e8ba1d6a668279`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jcuenod/usfm3
Publishing commit: github.com/jcuenod/usfm3/tree/da23f604fb0defe5c9d174e936902337e156f179

Workflow

Publishing configuration: github.com/jcuenod/usfm3/blob/da23f604fb0defe5c9d174e936902337e156f179/.github/workflows/publish-pypi.yml
Publishing logs: github.com/jcuenod/usfm3/actions/runs/25696661125/attempts/1

Artifact

Subject: usfm3-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: f5d7f76a702147b5ac7b2b7e72d83575d9abb6ac6f78c6339710005d579fc705 Verifying attestations

Release files / usfm3-0.2.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	usfm3-0.2.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size	434.9 kB
Tags	CPython 3.13 Linux glibc 2.17+ ARM64
SHA-256 checksum How to use checksums	`03ef68e1f631f09ce77fb12299219e6feb6c62e4102dfea3b71e6095994acb29`
BLAKE2b-256 checksum How to use checksums	`b13bf613c49bc638f79b9397a7e61467301d96815b4e3cb4cfd335ec4c285356`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jcuenod/usfm3
Publishing commit: github.com/jcuenod/usfm3/tree/da23f604fb0defe5c9d174e936902337e156f179

Workflow

Publishing configuration: github.com/jcuenod/usfm3/blob/da23f604fb0defe5c9d174e936902337e156f179/.github/workflows/publish-pypi.yml
Publishing logs: github.com/jcuenod/usfm3/actions/runs/25696661125/attempts/1

Artifact

Subject: usfm3-0.2.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
SHA-256 checksum: 03ef68e1f631f09ce77fb12299219e6feb6c62e4102dfea3b71e6095994acb29 Verifying attestations

Release files / usfm3-0.2.1-cp313-cp313-macosx_11_0_arm64.whl

Download URL	usfm3-0.2.1-cp313-cp313-macosx_11_0_arm64.whl
Size	389.6 kB
Tags	CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`06a26637ff9711ad43ba60365f626a1749301ea0fe7d18c8a1be5056b1bd2b1e`
BLAKE2b-256 checksum How to use checksums	`30f549228d5080d990c87c47a64d491fec644b53a2142a2a17401340d9ed7dec`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jcuenod/usfm3
Publishing commit: github.com/jcuenod/usfm3/tree/da23f604fb0defe5c9d174e936902337e156f179

Workflow

Publishing configuration: github.com/jcuenod/usfm3/blob/da23f604fb0defe5c9d174e936902337e156f179/.github/workflows/publish-pypi.yml
Publishing logs: github.com/jcuenod/usfm3/actions/runs/25696661125/attempts/1

Artifact

Subject: usfm3-0.2.1-cp313-cp313-macosx_11_0_arm64.whl
SHA-256 checksum: 06a26637ff9711ad43ba60365f626a1749301ea0fe7d18c8a1be5056b1bd2b1e Verifying attestations