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,36 @@
|
||||
# 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 check` rebuilds 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`, `referencing` and `cryptography` on 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 `validate` and `load` work on an installed package.
|
||||
`check`, `build`, `stress` and `site` need a checkout of the repository.
|
||||
- `paperspec validate --correction` reports 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](../reference/api.md) 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 `provisional` and may still change.
|
||||
Reference in new issue
Block a user