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,70 @@
|
||||
# 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.md).
|
||||
`cli.checkout()` finds the repository root that `check`, `build`, `stress` and `site` work on.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Command line
|
||||
|
||||
One command, `paperspec`, with six subcommands.
|
||||
`python -m paperspec` runs the same program.
|
||||
`paperspec --version` prints the package version and the Unicode version it pins, and `paperspec COMMAND --help` prints a command's options, advice and examples.
|
||||
|
||||
| Command | Works | Does |
|
||||
| --- | --- | --- |
|
||||
| [`validate`](#validate) | anywhere the package is installed with its `tools` extra | Validate packages, or run proposed corrections through the gate. |
|
||||
| [`load`](#load) | anywhere the package is installed with its `tools` extra | Validate packages and load them into a SQLite database. |
|
||||
| [`check`](#check) | in a checkout | Check the whole repository. |
|
||||
| [`build`](#build) | in a checkout | Rebuild `fixtures/` and `vectors/` from their sources. |
|
||||
| [`stress`](#stress) | in a checkout | Stress the oracle with random inputs. |
|
||||
| [`site`](#site) | in a checkout | Build the website into `_site/`. |
|
||||
|
||||
A misspelled command gets a suggestion, and an option a command does not know is refused.
|
||||
"In a checkout" means the repository an editable install points at, or else the one around the current folder.
|
||||
|
||||
## validate
|
||||
|
||||
```text
|
||||
paperspec validate [-h] [--correction PROPOSALS] [--max-size BYTES] PACKAGE [PACKAGE ...]
|
||||
```
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `PACKAGE` | A package folder or a zipped package (`.sct.zip`), unpacked under the specification's path rules first. |
|
||||
| `--correction PROPOSALS` | A JSON file holding one proposed correction, or a JSON Lines file of several, run through the gate against the one package given. Each record that would be appended to `corrections.jsonl` is printed, until one is refused. Nothing is written. |
|
||||
| `--max-size BYTES` | Refuse a zipped package that expands past this many bytes (default 1073741824). |
|
||||
|
||||
Each failure is printed to standard error as `package: where: rule: message`.
|
||||
Exit status: 0 when everything is valid, 1 when something is refused, 2 for a usage error.
|
||||
|
||||
## load
|
||||
|
||||
```text
|
||||
paperspec load [-h] --sqlite DATABASE [--bundle] [--built-from REV] [--store STORE] [--max-size BYTES] PACKAGE [PACKAGE ...]
|
||||
```
|
||||
|
||||
| Option | Meaning |
|
||||
| --- | --- |
|
||||
| `PACKAGE` | A package folder or a zipped package. Every package is validated first, and nothing is loaded if any fails. |
|
||||
| `--sqlite DATABASE` | The database file, created with the tables of `sql/` if it does not exist. Files with no table of their own are copied into `DATABASE.assets/`. |
|
||||
| `--bundle` | Build a new `scienting-bundle/1` file with the full-text search index. Needs `--built-from`. |
|
||||
| `--built-from REV` | With `--bundle`: the store revision the packages come from. |
|
||||
| `--store STORE` | With `--bundle`: the store's name (default: the packages' common store). |
|
||||
| `--max-size BYTES` | As for `validate`. |
|
||||
|
||||
## check
|
||||
|
||||
```text
|
||||
paperspec check [-h] [--quick]
|
||||
```
|
||||
|
||||
`--quick` skips the byte-for-byte rebuild.
|
||||
Exit status: 0 when every check passed, 1 otherwise.
|
||||
|
||||
## build
|
||||
|
||||
```text
|
||||
paperspec build [-h] [--out DIR]
|
||||
```
|
||||
|
||||
Without `--out` it rewrites `fixtures/` and `vectors/` in the checkout; with it, it builds into `DIR` instead.
|
||||
|
||||
## stress
|
||||
|
||||
```text
|
||||
paperspec stress [-h] [--seed SEED] [--rounds ROUNDS]
|
||||
```
|
||||
|
||||
`--seed` sets the random seed (default 20261014) and `--rounds` the cases per property (default 200).
|
||||
Exit status: 0 when every property held, 1 otherwise.
|
||||
|
||||
## site
|
||||
|
||||
```text
|
||||
paperspec site [-h] [--out DIR] [--base-url URL]
|
||||
```
|
||||
|
||||
`--out` sets the output folder, which must not be the repository or contain it (default `_site/` in the checkout).
|
||||
`--base-url` sets the site's address for canonical links (default `https://paperspec.scient.ing`).
|
||||
@@ -0,0 +1,6 @@
|
||||
# Reference
|
||||
|
||||
- [Command line](cli.md): the `paperspec` command, its six subcommands and every option.
|
||||
- [Python API](api.md): the modules of the package and what each is for.
|
||||
|
||||
The formats the code implements are specified at <https://paperspec.scient.ing/spec/>, and the JSON Schemas, SQL and test vectors are at the same address.
|
||||
Reference in new issue
Block a user