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
2.3 KiB
2.3 KiB
About
Status
The formats are at version 0.1.0.
Of the 32 formats, 19 are candidate and 13 are provisional; registry/formats.json in the repository lists each with its media type, schema, status and chapter.
The Python package is at an alpha stage (the Development Status :: 3 - Alpha classifier).
Its version comes from git tags, so a tag v0.1.1 builds as 0.1.1 and later commits as 0.1.2.devN.
Design commitments
- The code defines the expected values.
No expected value in a vector or fixture is typed by hand: the oracle computes it, and
paperspec checkrebuilds everything and compares it byte for byte. - Standard library first.
Every module imports with the standard library alone.
Schema validation and the Ed25519 and HKDF functions import
jsonschema,referencingandcryptographyon first use, through the package's extras. - Clarity over speed. The oracle is a slow, plain program. The verifiable random function (RFC 9381) and ML-DSA-65 (FIPS 204) are written out in Python and checked against those standards' own test vectors.
- One Python. The specification pins the Unicode 16.0 character data that normalization and the character classes come from, so the package refuses to import on a Python with another version. Python 3.14 is the only one that matches.
Known limits and unfinished parts
This documentation describes what the code does.
Where an older guide, a doc comment or the --help text says something different, the code wins, and this section lists the differences.
- The package is an oracle, not a production reader or writer. It has not been measured for speed or for large corpora; the formats are built for a team-scale corpus of hundreds of documents.
- Only
validateandloadwork on an installed package.check,build,stressandsiteneed a checkout of the repository. paperspec validate --correctionreports a proposals file that is not valid JSON with a Python traceback, not a one-line message.- The Python API has no generated reference yet: the API page is written by hand from the code's docstrings.
- The package is not on the studio's registry until a version tag is pushed.
[CHECK: no tag exists yet] - Thirteen formats are
provisionaland may still change.