quilldown 0.1.1__tar.gz

quilldown-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+# typra emit metadata (regenerated from ../../spec by `npm run generate`)
+.typra-generated/
+json-ast/
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+uv.lock

quilldown-0.1.1/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [0.1.1](https://github.com/sethjuarez/quilldown/compare/quilldown-python-v0.1.0...quilldown-python-v0.1.1) (2026-09-09)
+
+
+### Documentation
+
+* **python:** tighten the runtime README ([a6a24d8](https://github.com/sethjuarez/quilldown/commit/a6a24d80ceb5570291287e337d43dbb9076dfc06))
+* **python:** tighten the runtime README ([e575ec8](https://github.com/sethjuarez/quilldown/commit/e575ec839764125657b580527a2a13e5fcdb1b5d))
+
+## 0.1.0 (2026-09-09)
+
+
+### Features
+
+* author spec/*.tsp and green Python runtime (ADR-0001 steps 4-5) ([4863232](https://github.com/sethjuarez/quilldown/commit/4863232e4939b04029ad45cff89aa6db55515102))
+* **python:** add uv-managed Python runtime passing Core conformance ([90fde38](https://github.com/sethjuarez/quilldown/commit/90fde388d28486b29787d4df204dfa6de93f2cbc))
+* **python:** autolink bare URLs, www, and emails to match comrak ([39fd350](https://github.com/sethjuarez/quilldown/commit/39fd350768d2576ed438cce5c56f7ac821d2abaa))
+* **python:** drop leading YAML front matter to match comrak ([2787194](https://github.com/sethjuarez/quilldown/commit/27871949082afd2f557cfc2ce361980db2cbcd75))
+* **python:** legalize comrak dollar-backtick code math to text ([1506568](https://github.com/sethjuarez/quilldown/commit/1506568542fe5fa6592fd09c3262967842f7f825))
+* **python:** legalize footnotes to match the Rust oracle ([cbe42d5](https://github.com/sethjuarez/quilldown/commit/cbe42d5c58337bfc8c7fda299e22158354dbb56f))
+* **python:** legalize GFM alerts to unwrapped body blocks ([bcda104](https://github.com/sethjuarez/quilldown/commit/bcda1044c5dd62bee05f9f35d5ecfc02cedfd322))
+* **python:** legalize GFM subscript with a comrak-faithful ~ pairing pass ([9d2b1b7](https://github.com/sethjuarez/quilldown/commit/9d2b1b7c3ae03a03d2cd0ae263c858eac22d8a4b))
+* **python:** legalize GFM superscript by flattening to inner content ([27f7e79](https://github.com/sethjuarez/quilldown/commit/27f7e793cbc1849a95d3c0ed948cb247542b89f1))
+* **python:** legalize images to alt text to match the Rust oracle ([8c2f120](https://github.com/sethjuarez/quilldown/commit/8c2f120a3feb87eb233563c35798bf7518efafcf))
+* **python:** legalize inline and display math to match the Rust oracle ([66f3bdb](https://github.com/sethjuarez/quilldown/commit/66f3bdb5a1679e85de8efb0102ff3162c7e0a02b))
+
+
+### Bug Fixes
+
+* **python:** legalize comrak cross-marker delimiter removal for tilde spans ([f0a5fd8](https://github.com/sethjuarez/quilldown/commit/f0a5fd80f8f2cc859b6002f2f30d1263a02f0a27))
+* **python:** unified interleaved delimiter pass for cross-marker emphasis parity ([9a4a83b](https://github.com/sethjuarez/quilldown/commit/9a4a83b8f726e3b9568a25f9739c82b3178ff7e6))
+
+
+### Documentation
+
+* **python:** document mixed-marker re-pairing exclusion found in duck review ([ad3248f](https://github.com/sethjuarez/quilldown/commit/ad3248f50027a2bdde10fd8afec0ceaeef6d8064))

quilldown-0.1.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: quilldown
+Version: 0.1.1
+Summary: Python runtime for the Quilldown shared contract (Markdown -> IR -> DOCX).
+Requires-Python: >=3.10
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.1; extra == 'docx'

quilldown-0.1.1/README.md

@@ -0,0 +1,16 @@
+# quilldown (Python runtime)
+
+The Python runtime for [quilldown](../../README.md) — Markdown → IR → `.docx` —
+implementing the shared [`spec/`](../../spec) contract per
+[ADR-0001](../../docs/adr/0001-polyglot-quilldown-via-shared-contract.md).
+
+It ships its own lowering (Markdown → IR, via `markdown-it-py`) and emitter
+(IR → `.docx`, via `python-docx`) on top of the typra-generated IR model and
+conformance vectors, keeping it differentially faithful to the Rust reference
+engine.
+
+## Develop
+
+```sh
+uv run pytest -q   # conformance + vector suite
+```

quilldown-0.1.1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "quilldown"
+version = "0.1.1"
+description = "Python runtime for the Quilldown shared contract (Markdown -> IR -> DOCX)."
+requires-python = ">=3.10"
+dependencies = [
+    "markdown-it-py>=3.0",
+    "mdit-py-plugins>=0.4",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+docx = ["python-docx>=1.1"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "python-docx>=1.1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quilldown", "src/quilldown_spec"]

quilldown-0.1.1/src/quilldown/__init__.py

@@ -0,0 +1,38 @@
+"""Quilldown Python runtime: the hand-authored `lower`/`emit` seam that
+implements the generated `Quilldown` Protocol from the shared spec."""
+from __future__ import annotations
+
+from quilldown_spec import Document, RenderStats, RenderOptions, ConvertOptions
+
+from .parser import markdown_to_ir
+from .render import compute_stats, render_docx
+
+__all__ = ["Runtime", "lower", "emit", "render_docx"]
+
+
+class Runtime:
+    """Concrete implementation of the `Quilldown` seam Protocol."""
+
+    def lower(self, markdown: str, options: "ConvertOptions | None" = None) -> Document:
+        return Document.load(markdown_to_ir(markdown))
+
+    async def lower_async(self, markdown: str, options: "ConvertOptions | None" = None) -> Document:
+        return self.lower(markdown, options)
+
+    def emit(self, doc: Document, options: "RenderOptions | None" = None) -> RenderStats:
+        doc_dict = doc.save() if isinstance(doc, Document) else doc
+        return RenderStats.load(compute_stats(doc_dict))
+
+    async def emit_async(self, doc: Document, options: "RenderOptions | None" = None) -> RenderStats:
+        return self.emit(doc, options)
+
+
+_DEFAULT = Runtime()
+
+
+def lower(markdown: str, options: "ConvertOptions | None" = None) -> Document:
+    return _DEFAULT.lower(markdown, options)
+
+
+def emit(doc: Document, options: "RenderOptions | None" = None) -> RenderStats:
+    return _DEFAULT.emit(doc, options)

quilldown-0.1.1/src/quilldown/autolink.py

@@ -0,0 +1,392 @@
+"""GFM autolink extension, ported from comrak's `parser/autolink.rs`.
+
+markdown-it-py has no plugin that reproduces comrak's GFM autolinking, and
+`linkify-it-py` cannot match it (its www/bare-domain handling is a single fuzzy
+flag that either over-links `e.g.`/`v2.0` or drops `www.`/email). comrak links
+only three "kinds":
+
+* URL autolinks with a `http://`, `https://` or `ftp://` scheme (lowercase),
+  plus the bare `mailto:`/`xmpp:` schemes, matched through the email path;
+* `www.`-prefixed hosts, rewritten with an implicit `http://`;
+* bare email addresses, rewritten with an implicit `mailto:`.
+
+The delimiter trimming (trailing punctuation, balanced parentheses, trailing
+HTML entities), the domain validation (at least one dot, no underscore in the
+last two labels), the lowercase-scheme requirement and the `[...]`-bracket
+suppression are all reproduced from comrak so the lowered IR matches the frozen
+Rust oracle byte for byte.
+
+The port operates on Python `str` using character offsets; comrak uses byte
+offsets. The two agree for ASCII, which covers realistic URLs/emails; exotic
+multi-byte hosts and the bidi Pop-Directional-Isolate trim are approximated.
+
+Known limitations (declared exclusions, not bugs). comrak autolinks the *raw*
+source, decoding HTML entities only afterwards, whereas markdown-it-py decodes
+entities eagerly into a single plain-text token with no retained raw spelling
+(`.markup` is empty). Where an entity sits adjacent to an autolink the two can
+therefore disagree — e.g. `https://a.com&` (comrak trims `&`; we keep a
+decoded `&`), `https://a.com/&/b` and `https://a.com/a<b`. Recovering the
+raw entity is not possible from markdown-it's AST, and disabling entity decoding
+globally would corrupt the common `&`->`&` text path, so these adjacency
+cases and the bidi PDI (U+2069) trailing trim are left unmatched.
+"""
+from __future__ import annotations
+
+import unicodedata
+
+_ASCII_ALNUM = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789")
+_ASCII_ALPHA = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")
+_EMAIL_OK = set(".+-_")
+_LINK_END_ASSORTMENT = set("?!.,:*_~'\"")
+_WWW_DELIMS = set("*_~([")
+_SCHEMES = ("http", "https", "ftp")
+_SPACE = set(" \t\n\r\x0b\x0c")
+
+
+def _isalnum(c: str) -> bool:
+    return c in _ASCII_ALNUM
+
+
+def _isalpha(c: str) -> bool:
+    return c in _ASCII_ALPHA
+
+
+def _isspace(c: str) -> bool:
+    return c in _SPACE
+
+
+def _is_valid_hostchar(c: str) -> bool:
+    if c.isspace():
+        return False
+    cat = unicodedata.category(c)
+    return not (cat.startswith("P") or cat.startswith("S"))
+
+
+def _check_domain(data: str, allow_short: bool = False) -> int | None:
+    """Return the length of a valid domain at the start of `data`, else None.
+
+    Mirrors comrak's `check_domain`: `.`-separated labels of host characters
+    (plus `-`), rejecting a domain whose last one or two labels contain `_`,
+    and requiring at least one `.` when `allow_short` is false.
+    """
+    np = 0
+    uscore1 = 0
+    uscore2 = 0
+    n = len(data)
+    for i, c in enumerate(data):
+        if c == "\\" and i < n - 1:
+            # Escaped characters are ignored, per cmark-gfm.
+            continue
+        if c == "_":
+            uscore2 += 1
+        elif c == ".":
+            uscore1 = uscore2
+            uscore2 = 0
+            np += 1
+        elif not _is_valid_hostchar(c) and c != "-":
+            if uscore1 == 0 and uscore2 == 0 and (allow_short or np > 0):
+                return i
+            return None
+
+    if (uscore1 > 0 or uscore2 > 0) and np <= 10:
+        return None
+    if allow_short or np > 0:
+        return len(data)
+    return None
+
+
+def _autolink_delim(data: str, link_end: int) -> int:
+    """Trim trailing characters that are not part of the link (comrak's
+    `autolink_delim`): a `<` cuts the link, an assortment of trailing
+    punctuation is stripped, a trailing HTML entity (`&...;`) is removed, and
+    an unbalanced trailing `)` is dropped while balanced ones are kept."""
+    # A `<` terminates the link.
+    cut = data.find("<")
+    if 0 <= cut < link_end:
+        link_end = cut
+
+    while link_end > 0:
+        cclose = data[link_end - 1]
+        copen = "(" if cclose == ")" else None
+
+        if cclose in _LINK_END_ASSORTMENT:
+            link_end -= 1
+        elif cclose == ";":
+            new_end = link_end - 2
+            while new_end > 0 and _isalpha(data[new_end]):
+                new_end -= 1
+            if new_end < link_end - 2 and data[new_end] == "&":
+                link_end = new_end
+            else:
+                link_end -= 1
+        elif copen is not None:
+            opening = 0
+            closing = 0
+            for b in data[:link_end]:
+                if b == copen:
+                    opening += 1
+                elif b == cclose:
+                    closing += 1
+            if closing <= opening:
+                break
+            link_end -= 1
+        else:
+            break
+
+    return link_end
+
+
+def _validate_protocol(protocol: str, contents: str, cursor: int) -> bool:
+    """True when the alphabetic run ending at `cursor` (a `:`) equals
+    `protocol` exactly (comrak's `validate_protocol`)."""
+    rewind = 0
+    while rewind < cursor and _isalpha(contents[cursor - rewind - 1]):
+        rewind += 1
+    return contents[cursor - rewind : cursor] == protocol
+
+
+def _email_match(contents: str, i: int) -> tuple[int, int, str] | None:
+    """Match a bare email (or `mailto:`/`xmpp:` URL) around the `@` at `i`.
+
+    Returns `(start, end, url)` in character offsets, or None. Ported from
+    comrak's `email_match`.
+    """
+    size = len(contents)
+    auto_mailto = True
+    is_xmpp = False
+    rewind = 0
+
+    while rewind < i:
+        c = contents[i - rewind - 1]
+        if _isalnum(c) or c in _EMAIL_OK:
+            rewind += 1
+            continue
+        if c == ":":
+            if _validate_protocol("mailto", contents, i - rewind - 1):
+                auto_mailto = False
+                rewind += 1
+                continue
+            if _validate_protocol("xmpp", contents, i - rewind - 1):
+                is_xmpp = True
+                auto_mailto = False
+                rewind += 1
+                continue
+        break
+
+    if rewind == 0:
+        return None
+
+    link_end = 1
+    np = 0
+    while link_end < size - i:
+        c = contents[i + link_end]
+        if _isalnum(c):
+            pass
+        elif c == "@":
+            return None
+        elif c == "." and link_end < size - i - 1 and _isalnum(contents[i + link_end + 1]):
+            np += 1
+        elif c == "/" and is_xmpp:
+            pass
+        elif c != "-" and c != "_":
+            break
+        link_end += 1
+
+    last = contents[i + link_end - 1]
+    if link_end < 2 or np == 0 or (not _isalpha(last) and last != "."):
+        return None
+
+    link_end = _autolink_delim(contents[i:], link_end)
+    if link_end == 0:
+        return None
+
+    text = contents[i - rewind : i + link_end]
+    url = f"mailto:{text}" if auto_mailto else text
+    return (i - rewind, i + link_end, url)
+
+
+def _www_match(contents: str, i: int, prev: str | None = None) -> tuple[int, int, str] | None:
+    """Match a `www.` autolink starting at `i` (comrak's `www_match`).
+
+    `prev` is the raw source character immediately before `i`. Within a text run
+    that is `contents[i - 1]`; at the run's start it is the trailing character of
+    the preceding inline node (or None at the very start of the paragraph), so
+    the preceder rule matches comrak's source-cursor view across node
+    boundaries.
+    """
+    n = len(contents)
+    p = contents[i - 1] if i > 0 else prev
+    if p is not None and not _isspace(p) and p not in _WWW_DELIMS:
+        return None
+    if not contents.startswith("www.", i):
+        return None
+
+    domain = _check_domain(contents[i + 4 :])
+    if domain is None:
+        return None
+    link_end = domain + 4
+
+    while i + link_end < n and not _isspace(contents[i + link_end]):
+        link_end += 1
+
+    link_end = _autolink_delim(contents[i:], link_end)
+    text = contents[i : i + link_end]
+    return (i, i + link_end, f"http://{text}")
+
+
+def _url_match(contents: str, i: int) -> tuple[int, int, str] | None:
+    """Match a scheme URL autolink where `i` is the `:` of `://`
+    (comrak's `url_match`)."""
+    n = len(contents)
+    if n - i < 4 or contents[i + 1] != "/" or contents[i + 2] != "/":
+        return None
+
+    rewind = 0
+    while rewind < i and _isalpha(contents[i - rewind - 1]):
+        rewind += 1
+
+    scheme = contents[i - rewind : i]
+    if scheme not in _SCHEMES:
+        return None
+
+    domain = _check_domain(contents[i + 3 :])
+    if domain is None:
+        return None
+    link_end = domain + 3
+
+    while link_end < n - i and not _isspace(contents[i + link_end]):
+        link_end += 1
+
+    link_end = _autolink_delim(contents[i:], link_end)
+    text = contents[i - rewind : i + link_end]
+    return (i - rewind, i + link_end, text)
+
+
+def _scan_url_www(
+    text: str, within_brackets: bool = False, prev_char: str | None = None
+) -> tuple[list[tuple[str, str] | tuple[str, str, str]], bool]:
+    """First pass: url/www autolinks, suppressed inside `[...]`. Yields
+    `("text", s)` and `("link", display, url)` items left to right, plus the
+    bracket state on exit.
+
+    comrak recognises url/www autolinks during inline parsing, gated by a
+    parser-level `within_brackets` flag that flips true at any `[`/`![` and
+    false at any `]` and therefore spans intervening formatting nodes. This scan
+    reproduces that: `within_brackets` seeds the flag from the preceding nodes
+    and the returned bool carries it to the next node. `prev_char` is the raw
+    source character before this run, used for the `www.` preceder check at
+    offset 0.
+    """
+    out: list = []
+    n = len(text)
+    i = 0
+    seg_start = 0
+    wb = within_brackets
+    while i < n:
+        c = text[i]
+        if c == "[":
+            wb = True
+            i += 1
+            continue
+        if c == "]":
+            wb = False
+            i += 1
+            continue
+        if wb:
+            i += 1
+            continue
+
+        m = None
+        prev = text[i - 1] if i > 0 else prev_char
+        if text.startswith("www.", i):
+            m = _www_match(text, i, prev)
+        if m is None and c == ":":
+            m = _url_match(text, i)
+
+        if m is not None:
+            start, end, url = m
+            if start < seg_start:
+                start = seg_start
+            if start > seg_start:
+                out.append(("text", text[seg_start:start]))
+            out.append(("link", text[start:end], url))
+            i = end
+            seg_start = end
+            continue
+        i += 1
+
+    if seg_start < n:
+        out.append(("text", text[seg_start:]))
+    return out, wb
+
+
+def _scan_email(text: str) -> list[tuple[str, str] | tuple[str, str, str]]:
+    """Second pass: bare-email autolinks over a text run, suppressed inside
+    `[...]` (comrak runs this as a post-process triggered on `@`)."""
+    out: list = []
+    n = len(text)
+    i = 0
+    seg_start = 0
+    depth = 0
+    while i < n:
+        c = text[i]
+        if c == "[":
+            depth += 1
+        elif c == "]":
+            if depth > 0:
+                depth -= 1
+        elif c == "@" and depth == 0:
+            m = _email_match(text, i)
+            if m is not None:
+                start, end, url = m
+                if start < seg_start:
+                    start = seg_start
+                if start > seg_start:
+                    out.append(("text", text[seg_start:start]))
+                out.append(("link", text[start:end], url))
+                i = end
+                seg_start = end
+                continue
+        i += 1
+
+    if seg_start < n:
+        out.append(("text", text[seg_start:]))
+    return out
+
+
+def autolink_text(
+    text: str, within_brackets: bool = False, prev_char: str | None = None
+) -> tuple[list[dict], bool]:
+    """Split a plain-text run into IR text/link inline dicts, applying comrak's
+    GFM autolinking.
+
+    `within_brackets` and `prev_char` carry comrak's cross-node parser state (an
+    open `[` and the preceding source character) so autolinking respects bracket
+    suppression and the `www.` preceder rule across inline-node boundaries. The
+    returned bool is the bracket state after this run, to thread into the next.
+    A run with no autolinks returns a single text dict.
+    """
+    items: list = []
+    pieces, wb = _scan_url_www(text, within_brackets, prev_char)
+    for item in pieces:
+        if item[0] == "link":
+            items.append(item)
+        else:
+            items.extend(_scan_email(item[1]))
+
+    out: list[dict] = []
+    for item in items:
+        if item[0] == "link":
+            _, display, url = item
+            out.append(
+                {
+                    "kind": "link",
+                    "href": url,
+                    "content": [{"kind": "text", "data": display}],
+                }
+            )
+        else:
+            data = item[1]
+            if data:
+                out.append({"kind": "text", "data": data})
+    return out, wb