Files
paperspec/docs/package/guides/use-the-library.md
T
alexmandClaude 30d310f64d Publish the package and its documentation, and move to the papers organization
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
2026-10-19 04:23:49 -04:00

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.