Quillmark — Python bindings

Python bindings for Quillmark, a schema-driven document engine.

Maintained by TTQ.

Installation

pip install quillmark

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

The Python surface mirrors the @quillmark/wasm package for the shared document model. Names follow snake_case conventions; the underlying concepts (and shapes of return values) are the same. 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"

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

`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.schema_version_of(blob)                 # raw tag (incl. unknown futures)
Document.current_schema_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

doc.set_field("title", "New")
doc.set_fields({"title": "New", "author": "A"})  # atomic batch; one diagnostic per bad field
doc.push_card(Document.make_card("note", {"x": 1}, "..."))  # or pass a Card from cards/remove_card/seed_card
# insert_card, remove_card, move_card, set_card_kind,
# set_card_field, set_card_fields, remove_card_field, replace_card_body, ...

Schema model

A field's cell is inferred from whether the schema declares a default::

Unendorsed (no default:) — the blueprint renders the !must_fill marker (carrying the field's example as a suggested value when one exists). An absent Unendorsed field zero-fills silently. A !must_fill marker left in the document is non-fatal: it emits the validation::must_fill warning 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)

EditError-shaped failures (invalid field names, kind names, out-of-range indices) prefix the message with [EditError::<Variant>] — the same format WASM uses — so callers can pattern-match on the message when they need to.

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

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quillmark-0.94.0.tar.gz (2.8 MB view details)

Uploaded Jul 15, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

quillmark-0.94.0-cp310-abi3-win_amd64.whl (16.1 MB view details)

Uploaded Jul 15, 2026 CPython 3.10+Windows x86-64

quillmark-0.94.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.3 MB view details)

Uploaded Jul 15, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

quillmark-0.94.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (16.6 MB view details)

Uploaded Jul 15, 2026 CPython 3.10+manylinux: glibc 2.17+ ARM64

quillmark-0.94.0-cp310-abi3-macosx_11_0_arm64.whl (15.4 MB view details)

Uploaded Jul 15, 2026 CPython 3.10+macOS 11.0+ ARM64

File details

Details for the file quillmark-0.94.0.tar.gz.

File metadata

Download URL: quillmark-0.94.0.tar.gz
Upload date: Jul 15, 2026
Size: 2.8 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for quillmark-0.94.0.tar.gz
Algorithm	Hash digest
SHA256	`5a8998fbf654e0f3f4d08bb33c99f79ea710e75c17bed9468e0532dd20d51583`
MD5	`80183ff69acce6fc676c87e3e80c18d5`
BLAKE2b-256	`9036cbdbf070d9f76c68759eeafbf7859a66014b7143b0f2a4ddf6907584475d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quillmark-0.94.0.tar.gz:

Publisher: release.yml on borb-sh/quillmark

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quillmark-0.94.0.tar.gz
- Subject digest: 5a8998fbf654e0f3f4d08bb33c99f79ea710e75c17bed9468e0532dd20d51583
- Sigstore transparency entry: 2176858458
- Sigstore integration time: Jul 15, 2026
Source repository:
- Permalink: borb-sh/quillmark@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Branch / Tag: refs/heads/main
- Owner: https://github.com/borb-sh
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Trigger Event: pull_request

File details

Details for the file quillmark-0.94.0-cp310-abi3-win_amd64.whl.

File metadata

Download URL: quillmark-0.94.0-cp310-abi3-win_amd64.whl
Upload date: Jul 15, 2026
Size: 16.1 MB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for quillmark-0.94.0-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`104f1817ee1e7b792d11f6eda5d97d7751fa2e24af0f6ee3923ed550c0c12d6e`
MD5	`839b756856fbffd7cf8a036152e9d4bd`
BLAKE2b-256	`7b91a924e5f33c22cec99d0d06ca0881c08ff8f21f6d3f800c948dcbfb063c97`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quillmark-0.94.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on borb-sh/quillmark

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quillmark-0.94.0-cp310-abi3-win_amd64.whl
- Subject digest: 104f1817ee1e7b792d11f6eda5d97d7751fa2e24af0f6ee3923ed550c0c12d6e
- Sigstore transparency entry: 2176858875
- Sigstore integration time: Jul 15, 2026
Source repository:
- Permalink: borb-sh/quillmark@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Branch / Tag: refs/heads/main
- Owner: https://github.com/borb-sh
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Trigger Event: pull_request

File details

Details for the file quillmark-0.94.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: quillmark-0.94.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 15, 2026
Size: 17.3 MB
Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for quillmark-0.94.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`d12e1c85c863de087a3e7ff6c28cd4fc6a52f1a00f4e80945efa452579967558`
MD5	`0ddd4a3b16d4b6576ab63dd1c1bf6fb6`
BLAKE2b-256	`b17b04f90fd0555cc2d41e877b85ba5b3ea513404e321becd594c4dab12fe003`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quillmark-0.94.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on borb-sh/quillmark

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quillmark-0.94.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: d12e1c85c863de087a3e7ff6c28cd4fc6a52f1a00f4e80945efa452579967558
- Sigstore transparency entry: 2176858985
- Sigstore integration time: Jul 15, 2026
Source repository:
- Permalink: borb-sh/quillmark@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Branch / Tag: refs/heads/main
- Owner: https://github.com/borb-sh
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Trigger Event: pull_request

File details

Details for the file quillmark-0.94.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: quillmark-0.94.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jul 15, 2026
Size: 16.6 MB
Tags: CPython 3.10+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for quillmark-0.94.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`0ea2955a9cb7c8c5ab6183766e02046f8ea35fe17b91614529acd7beb9227373`
MD5	`2539dbdae568ae62d585bde3d0c81363`
BLAKE2b-256	`15eb3cfe6a1d5ef3068dc01f5343b92b1b99ce2a58ec39ca81353afd891c4e1e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quillmark-0.94.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on borb-sh/quillmark

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quillmark-0.94.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: 0ea2955a9cb7c8c5ab6183766e02046f8ea35fe17b91614529acd7beb9227373
- Sigstore transparency entry: 2176858632
- Sigstore integration time: Jul 15, 2026
Source repository:
- Permalink: borb-sh/quillmark@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Branch / Tag: refs/heads/main
- Owner: https://github.com/borb-sh
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Trigger Event: pull_request

File details

Details for the file quillmark-0.94.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: quillmark-0.94.0-cp310-abi3-macosx_11_0_arm64.whl
Upload date: Jul 15, 2026
Size: 15.4 MB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for quillmark-0.94.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`cd061593f2bda7c7b8392b7ea7915e067192820e5bb616e2269129bffe59cc14`
MD5	`6d41c1b82d6640f3e9ce7da958d87ccb`
BLAKE2b-256	`8abdd8acc20b255407b86c3016ff9408bee111995d157071aa936f43f3caa19d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quillmark-0.94.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on borb-sh/quillmark

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quillmark-0.94.0-cp310-abi3-macosx_11_0_arm64.whl
- Subject digest: cd061593f2bda7c7b8392b7ea7915e067192820e5bb616e2269129bffe59cc14
- Sigstore transparency entry: 2176858756
- Sigstore integration time: Jul 15, 2026
Source repository:
- Permalink: borb-sh/quillmark@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Branch / Tag: refs/heads/main
- Owner: https://github.com/borb-sh
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1afd871615fd4c10335de6a03a0f7e8d8c5ff582
- Trigger Event: pull_request