statute-utils

statute-utils recognizes Philippine statutory citations, resolves them against an explicit statute catalog, builds searchable SQLite artifacts from curated legal trees, and renders those trees as reusable HTML.

Version 2.0 requires Python 3.14 or newer and publishes inline type information.

uv add statute-utils

Start with extraction

The package-root API is intentionally small. extract_rules() returns the shared prelawsql.Rule model when category and serial are enough:

from statute_utils import extract_rules

rules = list(extract_rules("Republic Act Nos. 386 and 7160"))
assert [(rule.cat.value, rule.num) for rule in rules] == [
    ("ra", "386"),
    ("ra", "7160"),
]

Use an explicit, read-only catalog snapshot when a database relationship needs canonical corpus identity:

from statute_utils import StatuteCatalog, extract_rule_matches

catalog = StatuteCatalog.open("data/main.db")
match = next(extract_rule_matches("1987 Constitution", catalog=catalog))
assert match.statute_id == "const-1987-1987-02-02-1"

Catalog construction reads SQLite once. Candidate lookup performs no later database reads, and an existing snapshot does not silently change when its artifact path is atomically replaced.

Build the SQLite artifact

The canonical command rebuilds package-owned tables and views in a sibling staging database, validates that database, and publishes it with an atomic file replacement:

builder rebuild-trees \
  --db-name data/main.db \
  --statutes-folder ../corpus-statutes \
  --codifications-folder ../corpus-codifications

Use the root progress option before the command when CI needs stable records:

builder --progress plain rebuild-trees \
  --db-name data/main.db \
  --statutes-folder ../corpus-statutes \
  --codifications-folder ../corpus-codifications

Warning: the builder does not require source directories to exist or require the glob to select at least one file. For CLI rebuilds, verify the reported sources count before accepting an artifact; embedded callers should also validate the returned receipt. A zero-source rebuild can publish an empty package-owned surface.

Higher-level artifact producers that already own the connection, transaction, validation, and publication boundary can use statute_utils.rebuild.build_trees_into().

Documentation

• Documentation overview
• Getting started
• Extract and resolve citations
• Build and publish artifacts
• Python API and errors
• Upgrade to 2.0

For repository work, just check runs formatting and lint checks, Pyright and package type verification, documentation source/build/site checks, strict Marimo checks, the coverage-gated test suite, and a source-independent package build.