Quillmark: Python bindings
Python bindings for Quillmark, a schema-driven document engine.
Maintained by TTQ.
Installation
pip install quillmark
The package is typed: it ships py.typed and stubs for the whole surface, so
mypy, Pyright, and IDE completion see real signatures rather than Any.
Quick Start
from quillmark import Quillmark, Quill, Document, OutputFormat
engine = Quillmark() # backend registry + render dispatcher
quill = Quill.from_path("path/to/quill") # portable, declarative config data
markdown = """~~~
$quill: my_quill
$kind: main
title: Hello World
~~~
# Hello
"""
parsed = Document.from_markdown(markdown)
result = engine.render(quill, parsed, OutputFormat.PDF)
result.artifacts[0].save("output.pdf")
API surface
Python is a Tier-1 binding: field I/O flows through quill.writer(doc) and
quill.reader(doc), the schema-bound write/read front doors. Document carries
the quill-free surface: parse, storage, structure, $ext / $seed, and
remove_field. There is no opaque field store and no anchor-preserving content
lane (install / revise / apply_change + the import_markdown /
export_markdown / rebase / map_pos codec); those are WASM-only by scope,
serving live editors that Python does not target. See
prose/canon/BINDINGS.md.
Names follow snake_case; the shared model (the Document / Card shapes,
Diagnostics, the storage DTO) is identical to the
@quillmark/wasm package's. Python renders in one shot via
engine.render; the iterative render-session and canvas-preview surface is
WASM-only (see prose/canon/PREVIEW.md).
Capability principle: a Quill is portable, declarative config data,
quill.metadata is a pure, infallible snapshot of the quill: section.
The format probe (supported_formats) and rendering (render) are resolved
by the engine, against a quill; they raise QuillmarkError
(code engine::backend_not_found) only if the declared backend isn't
registered.
Quillmark
engine = Quillmark()
engine.registered_backends() # ['typst', 'pdfform'] (order not guaranteed)
engine.render(quill, parsed, OutputFormat.PDF) # ppi=, pages=, producer= optional
engine.supported_formats(quill) # [OutputFormat.PDF, ...] (raises if backend unregistered)
Quill
quill = Quill.from_path("path/to/quill") # pure config load: no backend resolved here
quill.backend_id # "typst" (declared backend)
quill.blueprint # auto-generated annotated Markdown blueprint
quill.schema # structured dict of the quill's document schema
quill.metadata # pure config snapshot of the quill: section (never raises)
quill.quill_ref # "name@version"
doc = quill.parse(markdown) # the bound door: parse + conform, the primary ingestion path
diags = quill.conform(doc) # the same walk in place on a transported document ([] = at rest)
diags = quill.validate(parsed) # list of validation::* diagnostic dicts ([] = valid)
seed = quill.seed_document() # starter Document seeded from `example:` values
main = quill.seed_main() # just the $kind: main card (dict, like doc.main)
card = quill.seed_card("note") # one starter composable card (dict), None if kind undeclared
writer = quill.writer(doc) # schema-bound typed write front door
reader = quill.reader(doc) # schema-bound interpreted read front door
Writer: quill.writer(doc)
The typed write front door. Resolves each field's type from the bound quill, so a
name the schema does not declare is a typo (UnknownField), not a fallback. Holds
both handles by reference and owns neither, ephemeral by convention: bind, write,
discard.
w = quill.writer(doc)
w.set("title", "On Taro") # typed-commit one field (mismatch raises now)
w.set_all({"title": "T", "author": "A"}) # atomic batch; one diagnostic per bad field
w.revise_body("A **taro** essay.") # body write (edit semantics; a body has no field schema)
w.revise_field("bio", "make it **bold**") # typed *and* anchor-preserving content write (codec by declared type)
w.add_card("quotes", {"author": "Basho"}, "…", at=None) # make + typed commit + insert (at appends/inserts)
w.remove_card(0)
w.card(0).set("author", "Issa") # a CardWriter: .index, .kind, .set, .set_all, .revise_body, .revise_field
Reader: quill.reader(doc)
The interpreted read front door and the read twin of Writer. get reads each
field by its declared type: a richtext field to its markdown projection, a
plaintext field to its literal text, every other type its canonical value
verbatim. get_content is the same read at the other end of the codec, handing
back the field's Content as a dict whichever lane stored it.
v = quill.reader(doc)
v.get("bio") # richtext → markdown str; scalar → its value; absent → None
# undeclared name raises UnknownField; undecodable content raises FieldDecode
v.get_content("bio") # the `Content` dict {text, lines, marks, islands}; absent → None
# a type that is not a content leaf raises FieldNotContent
v.body_markdown() # the main body markdown (quill-free body read)
v.card(0).kind # the composable card's $kind
v.card(0).get("author") # a card field, interpreted by its $kind schema
v.card(0).body_markdown()
RenderResult / Artifact
result.artifacts # [Artifact, ...]
result.warnings # [Diagnostic, ...]
result.format # OutputFormat
result.render_time_ms # float
artifact.format # OutputFormat
artifact.bytes # bytes
artifact.mime_type # 'application/pdf', 'image/svg+xml', ...
artifact.save("out.pdf")
Document
doc = Document("my_quill") # blank canvas: $quill only, no fields, no cards
doc = Document.from_markdown(markdown)
emitted = doc.to_markdown()
stored = doc.to_json()
restored = Document.from_json(stored)
maybe = Document.try_from_json(blob) # None when not a DTO
Document.storage_version_of(blob) # raw tag (incl. unknown futures)
Document.current_storage_version() # what this build writes
Document.format_rules() # card-yaml authoring rules (static text)
Document.quill_ref_hint() # $quill reference grammar (static text)
Document.blueprint_instruction("taro") # LLM/MCP blueprint header for a quill
doc.clone()
doc.equals(other)
doc.card_count
doc.main; doc.cards; doc.body; doc.warnings # total-read snapshots (dicts); body is a content dict
doc.card(0) # one card, same dict shape as main (out of range raises)
doc.seed_overlay("note") # one $seed[kind] overlay, or None
doc.set_quill_ref("other@1.0")
# Structure (quill-free, a card kind is a name, not a schema fact):
doc.insert_card(Document.make_card("note", {"x": 1}, "..."), at=None) # at appends/inserts
doc.remove_card(0) # returns the Card dict, or None
doc.move_card(2, 0); doc.set_card_kind(0, "summary")
doc.remove_field("title") # remove has no lane; card=i targets a composable card
# Out-of-band consumer state (never rendered):
doc.store_ext({"agent": {"pinned": True}}) # whole $ext map; card=i for a composable card
doc.store_ext_namespace("agent", {"n": 1}) # one slot, siblings preserved; card=i too
doc.remove_ext_namespace("agent"); doc.remove_ext()
doc.store_seed_overlay("note", {"tag": "T"}) # per-kind $seed overlay; new cards spawn with it
doc.remove_seed_overlay("note")
Setting a field's value is the writer's job (quill.writer(doc).set(...)): a
field write needs the schema, and Document is quill-free. Reading a field's
interpreted value is the reader's (quill.reader(doc).get(...)).
Schema model
A field's cell is inferred from whether the schema declares a default::
- Unendorsed (no
default:): the blueprint renders the!must_fillmarker (carrying the field'sexampleas a suggested value when one exists). An absent Unendorsed field zero-fills silently. A!must_fillmarker left in the document is non-fatal: it emits thevalidation::must_fillwarning and still renders. Partial documents are accepted;engine.render(quill, doc)only raises for malformed input. - Endorsed (with
default:): the blueprint renders the default value with a type-only# <type>annotation (shippable as-is), and the default is used when the document omits the field.
There is no required: axis on FieldSchema.
Error contract
A single exception type (QuillmarkError) is raised for every failure
mode. Every raised exception carries a non-empty .diagnostics list of
Diagnostic objects. This matches the WASM binding's contract.
try:
Document.from_markdown(bad_md)
except QuillmarkError as exc:
for d in exc.diagnostics:
print(d.severity, d.code, d.message, d.path)
print(str(d)) # canonical pretty-printed text (matches CLI / WASM)
Mutator failures (invalid field names, kind names, out-of-range indices) carry
a namespaced edit::* code on diagnostics[0]: edit::invalid_field_name,
edit::unknown_field, edit::index_out_of_range, edit::field_coercion_failed, …:
the same taxonomy WASM uses. Route on diagnostics[0].code, never on message
text.
Changelog
See the changelog and the GitHub Releases page for release notes and version history.
Development
uv venv
uv pip install -e ".[dev]"
uv run pytest
python/quillmark/_quillmark.pyi is hand-written and must track src/. No CI
job gates it, so after changing the surface run the stub against the built
module yourself:
uv pip install mypy
uv run python -m mypy.stubtest --ignore-disjoint-bases quillmark
License
Apache-2.0
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file quillmark-0.103.0-cp310-abi3-win_amd64.whl.
File metadata
- Download URL: quillmark-0.103.0-cp310-abi3-win_amd64.whl
- Upload date:
- Size: 16.3 MB
- Tags: CPython 3.10+, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5ce12b9570ff5a7ad7f926b3bc5b1015259717d79e662198e07ee4639c9eeebf
|
|
| MD5 |
a814288f609fad8a146af5fba7961734
|
|
| BLAKE2b-256 |
b2af9e340a941c846250f092e6447337b8775f5343de69a00d8ecf8c745e9061
|
Provenance
The following attestation bundles were made for quillmark-0.103.0-cp310-abi3-win_amd64.whl:
Publisher:
release.yml on borb-sh/quillmark
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
quillmark-0.103.0-cp310-abi3-win_amd64.whl -
Subject digest:
5ce12b9570ff5a7ad7f926b3bc5b1015259717d79e662198e07ee4639c9eeebf - Sigstore transparency entry: 2390213953
- Sigstore integration time:
-
Permalink:
borb-sh/quillmark@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Branch / Tag:
refs/heads/main - Owner: https://github.com/borb-sh
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Trigger Event:
pull_request
-
Statement type:
File details
Details for the file quillmark-0.103.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: quillmark-0.103.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 17.5 MB
- Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ed51959175312a430f1b56c8edba8beaeaf35c02246b92ccb377f46cca604643
|
|
| MD5 |
3ba9c7b857c3feb54ea9bf5394d3cf2a
|
|
| BLAKE2b-256 |
7a41aec5bea1c13288ed4eeb6b64c19d6b929052a86d7c78db578e15ff2bf329
|
Provenance
The following attestation bundles were made for quillmark-0.103.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:
Publisher:
release.yml on borb-sh/quillmark
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
quillmark-0.103.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl -
Subject digest:
ed51959175312a430f1b56c8edba8beaeaf35c02246b92ccb377f46cca604643 - Sigstore transparency entry: 2390213583
- Sigstore integration time:
-
Permalink:
borb-sh/quillmark@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Branch / Tag:
refs/heads/main - Owner: https://github.com/borb-sh
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Trigger Event:
pull_request
-
Statement type:
File details
Details for the file quillmark-0.103.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: quillmark-0.103.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 16.7 MB
- Tags: CPython 3.10+, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9765f81da7f54b30a38b3f5ba4b609abfdf37b156c068bd2525a4823513d7ec7
|
|
| MD5 |
832bb6b4fb3813e171ad05f54b64522c
|
|
| BLAKE2b-256 |
4f57d45b512e2d613e18af807e3b0538092ad3773092ed95935d50f17b8bbf88
|
Provenance
The following attestation bundles were made for quillmark-0.103.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:
Publisher:
release.yml on borb-sh/quillmark
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
quillmark-0.103.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl -
Subject digest:
9765f81da7f54b30a38b3f5ba4b609abfdf37b156c068bd2525a4823513d7ec7 - Sigstore transparency entry: 2390214231
- Sigstore integration time:
-
Permalink:
borb-sh/quillmark@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Branch / Tag:
refs/heads/main - Owner: https://github.com/borb-sh
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Trigger Event:
pull_request
-
Statement type:
File details
Details for the file quillmark-0.103.0-cp310-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: quillmark-0.103.0-cp310-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 15.4 MB
- Tags: CPython 3.10+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9eb85429a6f69a5a509cd88e631f27e6c4fc310a340dfd8b6d655269886eea82
|
|
| MD5 |
2485e1def0665f6df2b475c02887cf9f
|
|
| BLAKE2b-256 |
e16748cf9128df1ef91c259f5d8640084a79882917798f189d6e0d9123e14e9b
|
Provenance
The following attestation bundles were made for quillmark-0.103.0-cp310-abi3-macosx_11_0_arm64.whl:
Publisher:
release.yml on borb-sh/quillmark
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
quillmark-0.103.0-cp310-abi3-macosx_11_0_arm64.whl -
Subject digest:
9eb85429a6f69a5a509cd88e631f27e6c4fc310a340dfd8b6d655269886eea82 - Sigstore transparency entry: 2390213192
- Sigstore integration time:
-
Permalink:
borb-sh/quillmark@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Branch / Tag:
refs/heads/main - Owner: https://github.com/borb-sh
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b504a49fe3ba014924ff7e1228b01fd6f0ac2dec -
Trigger Event:
pull_request
-
Statement type:
