Files
paperspec/docs/package/reference/api.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

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.