Repository navigation
Python bindings: cross-platform wheel matrix + PyPI publishing (+ cp314t) #132
Description
Follow-up to #59 / #131. The native Python bindings (crates/mds-python, to be published as markdown-script — ADR-012 selected this name; mdscript on PyPI is third-party owned and cannot be shared) landed in #131 as a dev/test-only crate — the extension builds and the pytest suite runs in CI, but no wheels are published. This issue tracks turning that into a real PyPI distribution as part of the single coordinated release.
Note: v0.4.0 shipped 2026-09-02 with no Python build or publish job in release.yml. This work is now active. PyPI name registration is tracked separately in #292; only a first upload claims the markdown-script name (the pending publisher filed 2026-08-25 reserves nothing and expires unused).
Scope
- Cross-platform wheel matrix. Build
cp311-abi3wheels for the release
target platforms (mirror the napi 7-target set where a Python ABI exists):
manylinux/musllinuxx86_64 + aarch64, macOS x86_64 + arm64, Windows x86_64.
Usematurin build --release(viamaturin-actionor the pinnedmaturin) with an
sdist. - PyPI publishing via OIDC trusted publisher for
release.yml(preferred; no
long-lived token), mirroring the npm provenance setup. Publish wheels + sdist. - Wire into the coordinated release. Extend:
release.yml— abuild-pythonmatrix +publish-pythonjob, gated on the
version check, ordered with the crates.io/npm publishes.scripts/verify-versions.mjs— assert themarkdown-scriptwheel version equals the
workspace version (it currently checks crates + npm only;markdown-scriptgets its
version from the Cargo workspace via maturindynamic, so this is an added
assertion, not a new source of truth).scripts/bump-version.mjs— no manifest edit needed (version is dynamic), but
confirm the CHANGELOG/coordination covers the Python package.
-
cp314tfree-threaded wheels. The extension is already free-threading ready
(frozen result classes,#[pymodule(gil_used = false)], GIL released per compile);
thecp314tABI is a separate build. Add it once the toolchain/runner support is
stable and soaked. - Post-publish smoke:
pip install markdown-scripton a clean machine + provenance
attestation check.
Notes
- Platform wheels can only be validated in CI (like the napi platform packages) — a
localmaturin buildcovers only the host platform. - Pin bumps to soak:
pyo30.29 /maturin1.14 once past the ~30-day soak window;
revisit at the same time as this work. - PyPI name registration: see Rename Python distribution to
markdown-script(importmarkdown_script) + register on PyPI #292.
Activity
fix(deps): bump pyo3/pythonize to 0.29.0 (RUSTSEC-2026-0176/-0177)
docs(python): retarget deferral to #132; fix CHANGELOG; split perf CI
docs(python): clarify PyPI availability (#132); soften scaling claim
dean0x commentedon Aug 9, 2026
Milestoned v0.4.0 for one sub-item only (2026-08-09 sweep)
To be explicit about scope, because the bulk of this issue is not pre-tag:
Pre-tag (v0.4.0):
PyPI \mdscript` name registration— the one-time maintainer action. Rationale:crates/mds-python/README.mdand the repo docs already advertisepip install mdscript`, but the name is unregistered on PyPI. That is a squatting window that opens wider the moment v0.4.0 is announced. Registration costs minutes and does not require the wheel matrix, the release-workflow changes, or OIDC to exist yet.Not pre-tag (post-v0.4.0): everything else here — the cross-platform wheel matrix,
release.ymlbuild-python/publish-pythonjobs,verify-versions.mjsassertion, OIDC trusted publishing, andcp314t. Nothing Python ships in the v0.4.0 release and the docs are honest about that (crates/mds-pythonis dev/test-only; CI builds and tests it but publishes nothing).If it is preferable to track these separately, split the name-registration bullet into its own issue and bump this one back off the milestone.
dean0x commentedon Aug 18, 2026
Name decision blocking this issue: see #292
#292 has been re-scoped and now carries the Python package name decision that this
issue's PyPI publishing work depends on. Summary of what changed:
mdscripton PyPI is not available — it is a genuine project (5 releases, April2021, real code, dormant ~5 years) in the same problem space, and PEP 541 offers no
route to it because the owner is reachable.
top_level.txtis exactlymdscript, so keepingimport mdscriptunder adifferent distribution name would silently clobber
site-packagesfor whicheverpackage installs second. Both names must change.
markdown-scriptwithimport name
markdown_script.Impact on the scope in this issue
The scope items above that say
mdscriptneed to readmarkdown-script/markdown_script:mdscript")scripts/verify-versions.mjs— assert themarkdown-scriptwheel version equalsthe workspace version
pip install markdown-script, thenimport markdown_scriptmarkdown-script(importmarkdown_script) + register on PyPI #292 a "pre-tag prerequisite" is obsolete: Rename Python distribution tomarkdown-script(importmarkdown_script) + register on PyPI #292 is not a v0.4.0blocker and has been moved to the v0.5.0 milestone
The rename itself is tracked in #292 and should land before the publishing job here goes
live.
Verified PyPI Trusted Publisher values for the
publish-pythonjobdean0xmdscriptrelease.ymlIf this issue's implementation adds
environment: pypito the publish job, thetrusted-publisher record on PyPI must be updated to match the environment name, or the
OIDC exchange will be rejected.
docs: fix spec/README defects blocking v0.4.0 tag (resolve-b4-spec-re…
dean0x commentedon Aug 20, 2026
Deferred from v0.4.0 code review
Finding: python-04 from wave-v0.4.0-wave1 review (2026-08-19_1216)
File:Line: crates/mds-python/tests/test_parity.py:349
Issue: Byte-level differentials across 3 helpers × 4 surfaces; nothing Python ships in v0.4.0.
Reason for deferral: This belongs with the cross-platform wheel matrix and PyPI publishing decision in this issue.
Related: PR #308 (wave/v0.4.0-wave1), issue #292
dean0x commentedon Sep 1, 2026
Note for the aarch64-musl wheel leg: maturin 1.13.3 (the version pinned in CLAUDE.md/CI) bundles cargo-zigbuild 0.22.2, which does not filter -Wl,--fix-cortex-a53-843419 (rust-lang/rust#155453, emitted by rustc >= 1.98.0 for both aarch64 linux targets); zig cc rejects the flag. maturin 1.14.1 bundles cargo-zigbuild 0.23.0 which filters it (cargo-zigbuild#452). Any zig-based aarch64-musl wheel build needs maturin >= 1.14.1. Publisher matching rules verified on 2026-09-02: workflow is the bare filename release.yml (reusable/called workflows do not match); a blank publisher environment means the environment claim is not checked, so adding environment: to the job later needs no publisher change; the publish job needs job-level permissions: id-token: write with pypa/gh-action-pypi-publish; the PyPI user who created the pending publisher becomes the project owner on first upload. See also the expiry note on #292.
feat(ci): Python wheel matrix + PyPI publishing (markdown-script, #132)…