alexmandClaude
607062056f
Python and Unicode
- requires-python is >=3.14,<3.15: 3.14 is the only Python with the
Unicode 16.0 data the specification pins (3.13 has 15.1, 3.15 has 17.0).
- `import paperspec` raises ImportError unless unicodedata reports
paperspec.UNICODE_VERSION (16.0.0), so a source checkout or an install
that bypasses requires-python cannot compute values on other data.
Commands
- tools/{check,build,validate,load,stress,site}.py move with history to
src/paperspec/cli/ and install as paperspec-check, -build, -validate,
-load, -stress and -site; each also runs as `python -m paperspec.cli.X`.
- paperspec.cli.require() exits with "install paperspec[tools]" when
cryptography or jsonschema is missing; paperspec.cli.checkout() finds
the repository the check, build, stress and site commands work on (the
editable install's own checkout, else the one around the current
folder) and exits with a message outside one. tools/__init__.py is gone.
- validate and load read the schemas and SQL through the new
paperspec.resources.path(), which finds them in a wheel and in an
editable install alike, so they work anywhere the package is installed.
- check runs the rebuild as `python -m paperspec.cli.build`.
- build still writes the provenance tool label "paperspec tools/build.py":
it is part of every hashed and signed fixture.
- pixi tasks and the check workflow run the commands; tools/README.md
documents them, and the other docs name the commands instead of paths.
License
- LICENSE.md gives `src/` Apache-2.0 alongside `tools/`. Since the
previous commit moved the code to src/, no row had covered it.
pixi run check passes (run as `python -m paperspec.cli.check` with src/ on
the path, since this environment cannot install the entry points); the
byte-for-byte rebuild matches, so no fixture or vector changed.
pixi.lock still needs `pixi lock`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Guides
These guides explain paperspec to someone meeting it for the first time. They serve three readers: a newcomer who has not seen the problem before, an implementer who will write a reader, writer, converter or checker, and an expert who knows the neighboring standards. The specification says exactly what each format is. The guides say what each format is for, with examples drawn from the fixtures.
| Guide | For |
|---|---|
| Overview | What paperspec is, who it serves, and how its parts fit together. |
| Concepts | The ideas behind the formats, one at a time, each with a real example. |
| Walkthrough | One paper, from a flawed first reading to a corrected, reviewed and signed document. |
| Examples | Things to run: checking hashes by hand, reading a package with a few lines of Python, querying a database. |
| Rationale | Why the formats look the way they do, and the questions they leave open. |
| Comparison | How paperspec compares with JATS, TEI, W3C Web Annotation and other schemas. |
| FAQ | Short answers to the questions people ask first. |
| Glossary | Every term, in a sentence. |
Reading orders
Newcomer. Spend a first afternoon on the overview, then the walkthrough with the fixture open beside it, then the examples. Read the concepts when a term in the walkthrough needs more than the glossary gives.
Implementer. Start with the specification's reading paths, which list the chapters to read for a reader, a converter, a store and a validator. Chapters 0, 1, 3, 4 and 5 are needed for any of them. Next, run the section "Test your implementation against a vector" in the examples. Check your work against the vectors and the fixtures. Chapter 22 of the specification defines conformance.
Expert. Read the overview for scope and for what paperspec is not, then the comparison for how it differs from existing standards.
After that, read the rationale for the reason behind each rule and the questions it leaves open.
It ends with a list of limits.
Section 0.4 of the specification and registry/formats.json give the status of each format: the version is 0.1.0, and each format is candidate or provisional.