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
2.8 KiB
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).
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.
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."))
{"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.
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)
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.
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.
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 lists the modules.