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
This commit is contained in:
alexmandClaude committed 2026-10-19 04:23:49 -04:00
1 parent bdbf03ebee
commit 30d310f64d
37 files changed
+1005 -83

No files matched your search

+66
View File
@@ -0,0 +1,66 @@
# 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.