Metadata-Version: 2.3
Name: statute-utils
Version: 2.0
Summary: Toolkit for Philippine rules.
Requires-Dist: prelawsql>=1.0.1
Requires-Dist: beautifulsoup4>=4.15
Requires-Dist: click>=8.4
Requires-Dist: jinja2>=3.1.6
Requires-Dist: lxml>=6.1
Requires-Dist: markdown>=3.10
Requires-Dist: markdownify>=1.2.3
Requires-Dist: markupsafe>=3.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0
Requires-Dist: sqlite-utils>=4.1
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# statute-utils

![GitHub CI](https://github.com/justmars/statute-utils/actions/workflows/ci.yml/badge.svg)

`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.

```sh
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:

```py
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:

```py
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:

```sh
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:

```sh
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](https://github.com/justmars/statute-utils/blob/main/docs/index.md)
- [Getting started](https://github.com/justmars/statute-utils/blob/main/docs/getting-started.md)
- [Extract and resolve citations](https://github.com/justmars/statute-utils/blob/main/docs/extract.md)
- [Build and publish artifacts](https://github.com/justmars/statute-utils/blob/main/docs/build.md)
- [Python API and errors](https://github.com/justmars/statute-utils/blob/main/docs/api.md)
- [Upgrade to 2.0](https://github.com/justmars/statute-utils/blob/main/docs/migration.md)

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.
