Add Python bindings and publish them to PyPi

.github/workflows/python-ci.yml

@@ -0,0 +1,33 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
+        with:
+          install_args: rust
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+      - run: pip install maturin pytest typst
+      - run: maturin build --out dist
+      - run: pip install dist/*.whl
+      - run: pytest bindings/python/tests

.github/workflows/python-release.yml

@@ -0,0 +1,134 @@
+name: Python Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    name: Wheels (linux-${{ matrix.platform.target }})
+    runs-on: ${{ matrix.platform.runner || 'ubuntu-latest' }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - target: x86_64
+          - target: aarch64
+            runner: ubuntu-24.04-arm
+          - target: armv7
+          - target: s390x
+          - target: ppc64le
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+      - name: Build wheels
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          manylinux: auto
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+          if-no-files-found: error
+
+  macos:
+    name: Wheels (macos-${{ matrix.target }})
+    runs-on: macos-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
+        with:
+          install_args: rust
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+      - name: Build wheels
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+          if-no-files-found: error
+
+  windows:
+    name: Wheels (windows-${{ matrix.target }})
+    runs-on: windows-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x64]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
+        with:
+          install_args: rust
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          architecture: ${{ matrix.target }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: wheels-windows-${{ matrix.target }}
+          path: dist
+          if-no-files-found: error
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Build sdist
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: wheels-sdist
+          path: dist
+          if-no-files-found: error
+
+  release:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [linux, macos, windows, sdist]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist
+          skip-existing: true

.gitignore

@@ -13,6 +13,15 @@ target
 # Contains mutation testing data
 **/mutants.out*/
 
+# Python bindings build artifacts
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+.venv/
+*.so
+*.pyd
+
 # RustRover
 #  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore

Cargo.toml

@@ -1,11 +1,19 @@
+[workspace]
+members = ["bindings/python"]
+
+[workspace.package]
+version = "0.1.2"
+edition = "2024"
+license = "Apache-2.0"
+
 [package]
 name = "typdiff"
-version = "0.1.2"
+version.workspace = true
 authors = ["@sou1118"]
-edition = "2024"
+edition.workspace = true
 description = "A diff tool for Typst documents, similar to latexdiff"
 repository = "https://github.com/sou1118/typdiff"
-license = "Apache-2.0"
+license.workspace = true
 readme = "README.md"
 
 [[bin]]

README.md

@@ -98,6 +98,38 @@ typdiff old.typ new.typ -o diff.typ
 typdiff old.typ new.typ -o diff.typ && typst compile diff.typ
 ```
 
+## Python
+
+`typdiff` is also available as a Python package.
+
+### Installation
+
+```sh
+pip install typdiff
+```
+
+### Usage
+
+```python
+import typdiff
+
+diff = typdiff.diff(old_bytes, new_bytes)  # from bytes
+diff = typdiff.diff_files("old.typ", "new.typ")  # from file paths (str or Path)
+```
+
+`diff()` takes and returns `bytes`, matching how [`typst`](https://pypi.org/project/typst/)'s `compile()` treats `bytes` as inline source (a plain `str` argument is instead treated as a path to read) — so `typdiff`'s output can be passed straight into `compile()`. `diff_files()` still takes file paths as `str`/`Path`, since those are paths rather than document content.
+
+### Producing a PDF
+
+Combine `typdiff` with `typst` (Python bindings for the Typst compiler, `pip install typst`) to go straight from two Typst files to a diff PDF, without shelling out to either CLI:
+
+```python
+import typdiff
+import typst
+
+pdf_bytes = typst.compile(typdiff.diff_files("old.typ", "new.typ"))
+```
+
 ## Features
 
 - **Block-level diffing** — Detects structural changes in headings, paragraphs, list items, enum items, and term list items

bindings/python/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "typdiff-python"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+name = "_typdiff"
+crate-type = ["cdylib"]
+
+[dependencies]
+typdiff = { path = "../.." }
+pyo3 = { version = "0.29", features = ["extension-module", "abi3-py38"] }

bindings/python/python/typdiff/__init__.py

@@ -0,0 +1,3 @@
+from ._typdiff import diff, diff_files
+
+__all__ = ["diff", "diff_files"]

bindings/python/python/typdiff/__init__.pyi

@@ -0,0 +1,7 @@
+import os
+
+def diff(old: bytes, new: bytes) -> bytes:
+    """Diff two Typst documents given as source bytes, returning diff markup as bytes."""
+
+def diff_files(old_path: str | os.PathLike[str], new_path: str | os.PathLike[str]) -> bytes:
+    """Diff two Typst documents given as file paths, returning diff markup as bytes."""