Add the Zensical documentation of the Python package (docs/package, built by the docs workflow), merge the standard publish workflow with the setuptools-scm tag check, add the SPDX header rule to ruff, restructure the README, and point every repository and registry address at the Gitea organization papers. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# Use the library
|
|
|
|
The modules of `paperspec` compute every value the formats define, so a program that writes or reads packages can import them instead of reimplementing the specification.
|
|
Every module imports with the standard library alone.
|
|
Schema validation needs `paperspec[schema]`, and Ed25519 and HKDF need `paperspec[crypto]`; `paperspec[tools]` installs both ([Install](../start/install.md)).
|
|
|
|
## Canonical JSON and hashes
|
|
|
|
`jcs.dumps` writes the canonical JSON the formats hash and store: sorted keys, no spaces, and numbers written as an ECMAScript engine would.
|
|
`text.sha256_hex` hashes a string, and `text.norm` applies the normalization the five hashes start from.
|
|
|
|
```python
|
|
from paperspec import jcs, text
|
|
|
|
print(jcs.dumps({"b": 1.0, "a": [2, "é"]}))
|
|
print(text.norm("a b\n c"))
|
|
print(text.sha256_hex("The two parameter sets agree to within 2% for every bond."))
|
|
```
|
|
|
|
```text
|
|
{"a":[2,"é"],"b":1}
|
|
a b c
|
|
175bfc8867816a9761fd5bb9ffc956df6d9e7f203870961a5485fc1912cb663a
|
|
```
|
|
|
|
## Validate a package
|
|
|
|
`package.validate` checks a package folder against every rule and returns a report whose `errors` list is empty when the package is valid.
|
|
The schema store reads the schemas from wherever the package carries them, in an installed wheel or at the root of a checkout.
|
|
|
|
```python
|
|
from paperspec import package, resources
|
|
from paperspec.schema import Store
|
|
|
|
store = Store(resources.path("schemas"))
|
|
report = package.validate("fixtures/packages/hale2026harmonic-damb", store)
|
|
print(bool(report), report.errors)
|
|
```
|
|
|
|
```text
|
|
True []
|
|
```
|
|
|
|
Each entry of `errors` is a dictionary with `rule`, `where` and `message`, the three fields `paperspec validate` prints.
|
|
|
|
## Read a package and run the gate
|
|
|
|
`package.read_state` reads a package folder into a state that holds its nodes, and `corrections.gate` runs a proposed correction against it without changing it.
|
|
It returns the state the correction would produce and the record it would append, or raises `tree.Refusal`, which names the rule broken.
|
|
|
|
```python
|
|
from paperspec import corrections, package, resources
|
|
from paperspec.schema import Store
|
|
|
|
state = package.read_state("fixtures/packages/tiny2026tiny-j4qm")
|
|
store = Store(resources.path("schemas"))
|
|
new_state, record = corrections.gate(state, proposal, store)
|
|
```
|
|
|
|
Here `proposal` is a parsed correction such as the one in [Validate a package](validate-a-package.md).
|
|
|
|
## Check your own code against the vectors
|
|
|
|
The vectors travel with the package as the data subpackage `paperspec.vectors`, and `resources.path("vectors")` finds the folder in an installed wheel and in an editable install alike.
|
|
Four of them, `resolve.jsonl`, `grading.jsonl`, `targets.jsonl` and `traces.jsonl`, name a fixture package, and the fixtures stay in the repository.
|
|
The [reference](../reference/api.md) lists the modules.
|