pyharfrust2 — HarfRust Trace Binding
Step-by-step (per-lookup / per-stage) shaping trace for HarfRust — the HarfBuzz Rust port — exposed through a Python (PyO3) binding.
The trace output is aligned with HarfBuzz's buffer message output (as produced by uharfbuzz), so consumers that already render HarfBuzz traces (e.g. BabelMap's OpenType Test timeline) can render it without changes.
Relationship to HarfRust
This repository is built on top of harfrust — HarfBuzz's official pure-Rust port — and does not reimplement any shaping. All glyph substitution and positioning comes straight from HarfRust:
crates/harfrust-forkis a snapshot of upstream harfrust v0.13.3 (which tracks HarfBuzz v14.3.1), vendored as a workspace member. The only additions are an optionalShapeOptions::tracecallback, alookup_map_t.feature_tagfield (which upstream HarfBuzz already has), andsrc/hb/trace.rs. With no callback the fork behaves exactly like upstream.crates/hr-traceis our thin layer: it runs HarfRust shaping with the trace callback installed and collects the per-step event sequence (TraceStep { event, glyphs }).crates/pyharfrust2+python/pyharfrust2is the PyO3 Python binding exposing this aspyharfrust2.shape_trace.
Keeping the fork small and isolated means it can be refreshed from upstream and
the trace patch re-applied, or dropped entirely once upstream gains its own
trace support — hr-trace/pyharfrust2 would then simply point at the
harfrust crate instead.
Layout
Cargo.toml # workspace
crates/
harfrust-fork/ # upstream harfrust v0.13.3 + minimal trace hooks
hr-trace/ # thin wrapper: shape_trace() -> event sequence
pyharfrust2/ # PyO3 cdylib: Python binding
python/pyharfrust2/ # Python package (maturin layout)
tests/ # Python tests + test font generator
pyproject.toml # maturin backend
The fork adds an optional trace callback to three shaping sites
(ot_shape.rs, ot_layout.rs, ot_shape_normalize.rs) plus a
lookup_map_t.feature_tag field (matching upstream HarfBuzz) and a
ShapeOptions::trace option. With no callback the behaviour is identical to
upstream and there is no overhead.
Python API
import pyharfrust2
stages = pyharfrust2.shape_trace(
font_bytes, # bytes of a TTF/OTF font
"ffi", # text to shape
direction="auto", # auto | ltr | rtl | ttb | btt
script="", # ISO 15924, e.g. "Arab"
language="",
features=None, # "+kern,-liga" (hb-shape syntax)
variations=None, # "wght=400" (comma separated)
face_index=0,
)
for stage in stages:
print(stage["m"], stage["glyphs"])
Each stage:
{
"m": "start lookup 5 feature 'liga'",
"glyphs": [
{"g": gid, "cl": cluster, "dx": dx, "dy": dy, "ax": ax, "ay": ay, "flags": flags},
...,
],
"depth": 0,
"effective": True,
}
Build & test
uv venv .venv --python 3.13
uv pip install --python .venv maturin uharfbuzz pytest
.venv/Scripts/maturin build --release # produces a wheel
uv pip install --python .venv <wheel path>
.venv/Scripts/python -m pytest tests/
Rust side:
cargo test -p harfrust-fork --lib # upstream tests still pass (no-trace unchanged)
cargo test -p hr-trace # trace event model tests
cargo run -p hr-trace --example dump_trace -- ffi
Platforms
Pure Rust with no system libraries. The Python wheel is built with
abi3-py311 (cp311-abi3), so a single wheel per OS covers Python 3.11+.
CI builds and tests on Windows, Linux and macOS, and publishes a macOS
universal2 (x86_64 + arm64) wheel. The harfrust-fork crate also compiles
without std:
cargo check -p harfrust-fork --no-default-features --features libm
Quality gates
The same checks run in CI (.github/workflows/build.yml, lint job):
.venv/Scripts/ruff check . && .venv/Scripts/ruff format --check . # Python lint/format
npx pyright@latest # Pylance type check
cargo fmt --check # Rust format
cargo clippy --workspace --all-targets -- -D warnings # Rust lint
cargo test --workspace # Rust tests
.venv/Scripts/python -m pytest tests/ # Python tests
Generate the test font
python tests/generate_test_font.py # -> tests/data/test_liga.ttf
License
MIT. The harfrust-fork crate is upstream harfrust (MIT) with a small,
upstreamable trace patch.
Metadata
Release files for pyharfrust2 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyharfrust2-0.1.0-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for pyharfrust2-0.1.0-cp311-abi3-win_amd64.whl |
| pyharfrust2-0.1.0-cp311-abi3-manylinux_2_34_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.34+ x86-64 | Details for pyharfrust2-0.1.0-cp311-abi3-manylinux_2_34_x86_64.whl |
| pyharfrust2-0.1.0-cp311-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64, macOS 10.12+ x86-64, macOS 10.12+ universal2 (ARM64, x86-64) | Details for pyharfrust2-0.1.0-cp311-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
Total release size: 2.5 MB
Release files / pyharfrust2-0.1.0-cp311-abi3-win_amd64.whl
| Download URL | pyharfrust2-0.1.0-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 512.1 kB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
76f298af62ec63bd2f0b458e0db90027858bd71a77c67eda258150882ff80d31
|
|
BLAKE2b-256 checksum How to use checksums |
9fe556801fe0d5b0fea441e6d178bcf11988488204378caea227b0c283c36529
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / pyharfrust2-0.1.0-cp311-abi3-manylinux_2_34_x86_64.whl
| Download URL | pyharfrust2-0.1.0-cp311-abi3-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 694.5 kB |
| Tags | CPython 3.11 Linux glibc 2.34+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
937f8c7f97a156ab3715c58ecae07efb0daa890bb0346d68fd6e7ccabf3e8844
|
|
BLAKE2b-256 checksum How to use checksums |
676d61960c680f07681f3fc0b45bc069ae7c70d778df58873b4ce63b1044d787
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / pyharfrust2-0.1.0-cp311-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | pyharfrust2-0.1.0-cp311-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.11 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
2c033c46fafb41d2193e802f5cc8b14acd37d0d9aabbaf49443eb01eabed02b7
|
|
BLAKE2b-256 checksum How to use checksums |
049bdeb6173d52c468381bfe51a5d3a9cc7c0d91d15e3357d9be5353fa0f4d12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logSecurity for pyharfrust2 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 3 files in this release have been uploaded with provenance metadata.
Attestation for pyharfrust2-0.1.0-cp311-abi3-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.