Skip to main content

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-fork is a snapshot of upstream harfrust v0.13.3 (which tracks HarfBuzz v14.3.1), vendored as a workspace member. The only additions are an optional ShapeOptions::trace callback, a lookup_map_t.feature_tag field (which upstream HarfBuzz already has), and src/hb/trace.rs. With no callback the fork behaves exactly like upstream.
  • crates/hr-trace is 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/pyharfrust2 is the PyO3 Python binding exposing this as pyharfrust2.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)

Table of built distributions (wheels) for pyharfrust2 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Release 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 log

Security 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.

Select from 3 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

3 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page