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:
37 files changed
+1005
-83
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user