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
4.7 KiB
Python API
The package paperspec is a set of small modules, one for each part of the specification, and each opens with a docstring that says what it is for.
This page is written by hand from those docstrings and lists the modules and the functions most programs call; help(paperspec.MODULE) has the rest.
The base package needs only the standard library.
schema needs paperspec[schema], and the Ed25519 and HKDF functions of crypto need paperspec[crypto]; both import their packages on first use.
Two aliases are shared by the type annotations: jsontypes.Record, one parsed JSON object, and jsontypes.StrPath, a path given as text or as a path object.
A function that takes a path returns text unless its docstring says otherwise.
A rule that is broken raises tree.Refusal, whose rule attribute names the rule as the specification's conformance chapter lists it.
paperspec.resources.path(name) returns the folder schemas, sql or vectors, in an installed wheel and in a checkout alike.
Text, hashes and canonical JSON
| Module | For | Main functions |
|---|---|---|
text |
Normalization, IDs and small helpers shared by the rest. | norm, sha256_hex, collapse_ws, letter_first, mint_node_id, record_id, cp_to_utf16 |
jcs |
Canonical JSON, RFC 8785. | dumps, dumpb, loads_line |
hashing |
The plain, strict and lossy projections of a node, and its five content values. | compute, plain, strict, lossy, own_content, meta_hash, Hasher, Index |
notation |
Simple math notation and its canonical linear form. | fold_math, complex_key, fold_plain_text |
keys |
Work and document keys. | work_key, unique_work_key, document_key, split_key |
The document
| Module | For | Main functions |
|---|---|---|
model |
The node tree of scienting-doc/1. |
Doc, anchor_class, the tables of allowed children and attributes |
tree |
Establishing a document from a nested tree, and the structural checks. | establish, mint_ids, validate_structure, validate_references, Refusal |
anchors |
Addresses, anchors and their resolution. | parse_address, format_address, make_anchor, resolve |
align |
Alignment of two readings of one paper. | align, classify, similarity |
fingerprint |
Page fingerprints and download-stamp rules. | fingerprint, is_stamp |
targets |
The target set of targeted F3. | target_set |
Packages, corrections and the database
| Module | For | Main functions |
|---|---|---|
package |
Writing, reading and validating a package folder or a zipped package. | validate, validate_zip, read_state, write, write_zip, read_zip, read_json, read_jsonl |
corrections |
The correction gate and the state it works on. | gate, apply, State |
schema |
JSON Schema validation with the keyword subset the schemas are restricted to. | Store, validate, lint |
db |
The database form. | create, create_bundle, load, unload, index |
Signatures, receipts and the log
| Module | For | Main functions |
|---|---|---|
crypto |
Keyed hashing, Merkle roots and proofs, Ed25519, HKDF and did:key. |
merkle_root, inclusion_path, verify_inclusion, consistency_proof, verify_consistency, ed25519_sign, ed25519_verify, did_key |
receipts |
Receipts, revocations, levels and spot-check sampling. | seal, verify_signature, statuses, effective_levels, sample, upper_bound |
log |
The team's transparency log and its signed checkpoints. | sign_checkpoint, verify_checkpoint, write_log, read_log |
vrf |
ECVRF-EDWARDS25519-SHA512-TAI, RFC 9381. | prove, verify, proof_to_hash |
mldsa |
ML-DSA-65, FIPS 204, in plain Python. | keygen, sign, verify |
Layers, rights and grading
| Module | For | Main functions |
|---|---|---|
rights |
Rights records, policies and stage checks. | effective, combine, check, backend_allowed |
traces |
Traced citations. | resolve, problems, disputed |
structures |
Chemical structures tied to words. | scan, problems |
sequences |
Biological sequences tied to words. | residues, problems |
data |
Data tied to words. | problems |
grade |
Grading a submission against an exercise key. | grade, key_anchors |
The problems functions of the four annotation modules return the rules an annotation breaks, as a list of {"rule", "message"} records in the order checked.
The command
paperspec.cli holds the subcommands of the paperspec command, one module each, with a run(args) function that returns the exit status; see Command line.
cli.checkout() finds the repository root that check, build, stress and site work on.