Add typed Python package (pyo3 + .pyi/py.typed) behind the python feature, and CI

Mixed maturin layout: compiled difflib_fast._difflib_fast + python/difflib_fast/ with type stubs + py.typed (pyright/mypy see full signatures). abi3-py39 → one wheel per platform for CPython 3.9+. Installable as a git dependency (pip drives maturin; no manual build). GitHub Actions: test+clippy, build wheels (linux/macos/windows) + sdist, and on a vX.Y.Z tag attach them to a GitHub Release + publish to crates.io. No PyPI. Benchmarks excluded from the published crate/sdist.

Author: prostomarkeloff

.github/workflows/CI.yml

@@ -0,0 +1,134 @@
+# Build + test, then on a version tag (`vX.Y.Z`): attach wheels + sdist to a GitHub Release and publish
+# the crate to crates.io. (No PyPI — install the Python package from a release wheel or via
+# `pip install git+https://github.com/prostomarkeloff/difflib-fast`.)
+#
+# Required repository secret for the release:
+#   CARGO_REGISTRY_TOKEN  — a crates.io API token   (the GitHub Release uses the built-in GITHUB_TOKEN)
+#
+# abi3 (pyo3 abi3-py39) → one wheel per platform/arch works on CPython 3.9+, so no per-Python matrix.
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test + clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - run: cargo test --release
+      - run: cargo clippy --release --all-targets --features bench
+
+  linux:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: "true"
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  macos:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  release:
+    name: GitHub release (wheels + sdist)
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [test, linux, macos, windows, sdist]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+      - name: Attach wheels + sdist to the release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+
+  crates:
+    name: publish to crates.io
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo publish --token ${{ secrets.CARGO_REGISTRY_TOKEN }}

.gitignore

@@ -1,6 +1,15 @@
 # Rust build artifacts (this crate's, the bench bin's, and benchmarks/compare's)
 target/
 
+# Python build artifacts (maturin develop drops the compiled module + caches into python-source)
+__pycache__/
+*.py[cod]
+*.so
+*.pyd
+*.dylib
+dist/
+*.egg-info/
+
 # samply / profiling output
 *.json.gz
 flame.svg

Cargo.toml

@@ -8,6 +8,8 @@ edition = "2021"
 license = "MIT"
 repository = "https://github.com/prostomarkeloff/difflib-fast"
 authors = ["prostomarkeloff"]
+# The benchmark suite + corpora (large, derived) are not part of the published crate / Python sdist.
+exclude = ["/benchmarks"]
 
 [lib]
 name = "difflib_fast"
@@ -16,9 +18,9 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 rayon = "1"
-# Optional Python bindings (pip install difflib-fast): build the extension module with maturin
-# and `--features python`. The pure-Rust crate has zero Python dependency.
-pyo3 = { version = "0.28", optional = true, features = ["extension-module"] }
+# Optional Python bindings (the `python` feature, built by maturin). `abi3-py39` → one wheel per
+# platform works on CPython 3.9+. The pure-Rust crate has zero Python dependency by default.
+pyo3 = { version = "0.28", optional = true, features = ["extension-module", "abi3-py39"] }
 # Used ONLY as the bench binary's global allocator (libraries must not set one) — gated so the
 # published library never pulls it in. macOS's default malloc madvise churn cost ~25% once parallel.
 mimalloc = { version = "0.1", default-features = false, optional = true }

README.md

@@ -144,16 +144,30 @@ Levenshtein), not `difflib`'s.
 
 ---
 
-## Python bindings
+## Python package
 
-The pure-Rust crate has **zero** Python dependency. Build with the `python` feature +
-[maturin](https://github.com/PyO3/maturin) for a `pip install`-able extension exposing `ratio`,
-`cluster_canonicals`, and `cluster_canonicals_lsh`:
+A proper, **typed** Python package (`py.typed` + `.pyi` stubs — pyright/mypy see full signatures),
+gated behind the `python` cargo feature so the pure-Rust crate keeps **zero** Python dependency by
+default.
 
 ```bash
-maturin develop --release --features python
+# from source (needs a Rust toolchain; pip drives maturin automatically — no manual build):
+pip install git+https://github.com/prostomarkeloff/difflib-fast
+
+# or grab a prebuilt abi3 wheel (CPython 3.9+) from the GitHub Releases page — no Rust needed.
 ```
 
+```python
+import difflib_fast
+
+difflib_fast.ratio("the quick brown fox", "the quick brown dog")   # 0.8947368421052632 — == difflib
+difflib_fast.cluster_canonicals(["def f(a): ...", "def f(x): ...", "other"], 0.5)
+# → [([0, 1], 0.86…)]
+```
+
+Built with [maturin](https://github.com/PyO3/maturin) (mixed layout: compiled `_difflib_fast` +
+`python/difflib_fast/` package). Build locally into a venv with `maturin develop --release`.
+
 ---
 
 ## How it works

pyproject.toml

@@ -5,11 +5,26 @@ build-backend = "maturin"
 [project]
 name = "difflib-fast"
 description = "Fast, byte-for-byte exact difflib Ratcliff-Obershelp similarity + clustering."
+readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
-classifiers = ["Programming Language :: Rust"]
+authors = [{ name = "prostomarkeloff" }]
+keywords = ["difflib", "similarity", "ratcliff-obershelp", "fuzzy", "diff"]
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Text Processing :: General",
+    "License :: OSI Approved :: MIT License",
+    "Typing :: Typed",
+]
 dynamic = ["version"]
 
+[project.urls]
+Repository = "https://github.com/prostomarkeloff/difflib-fast"
+
 [tool.maturin]
 features = ["python"]
-module-name = "difflib_fast"
+# mixed layout: the compiled extension is `difflib_fast._difflib_fast`; the Python package under
+# `python/difflib_fast/` re-exports it and ships the type stubs (`.pyi`) + `py.typed`.
+module-name = "difflib_fast._difflib_fast"
+python-source = "python"

python/difflib_fast/__init__.py

@@ -0,0 +1,9 @@
+"""difflib-fast — fast, byte-for-byte exact difflib Ratcliff-Obershelp similarity + clustering.
+
+A drop-in for ``difflib.SequenceMatcher(None, a, b, autojunk=False).ratio()``, computed with a suffix
+automaton (Rust), plus exact single-linkage clustering of a corpus.
+"""
+
+from ._difflib_fast import cluster_canonicals, cluster_canonicals_lsh, ratio
+
+__all__ = ["ratio", "cluster_canonicals", "cluster_canonicals_lsh"]

python/difflib_fast/__init__.pyi

@@ -0,0 +1,29 @@
+"""Type stubs for difflib-fast — exact difflib Ratcliff-Obershelp similarity + clustering."""
+
+def ratio(a: str, b: str) -> float:
+    """Exact ``difflib.SequenceMatcher(None, a, b, autojunk=False).ratio()`` — byte-for-byte.
+
+    The Ratcliff-Obershelp similarity ``2*M / (len(a) + len(b))``, identical to Python's ``difflib``
+    (including its argument-order asymmetry), computed via a suffix automaton so it stays linear on
+    long, repetitive inputs where ``difflib`` degrades.
+    """
+
+def cluster_canonicals(canonicals: list[str], threshold: float) -> list[tuple[list[int], float]]:
+    """Exact single-linkage clustering of ``canonicals`` by RO similarity.
+
+    Two strings join a cluster when their exact ratio is ``>= threshold``. Returns one
+    ``(member_indices, min_pairwise_ratio)`` per cluster of >= 2 members; ``member_indices`` index
+    into ``canonicals`` (sorted), ``min_pairwise_ratio`` is the cluster's exact minimum pairwise ratio.
+    """
+
+def cluster_canonicals_lsh(
+    canonicals: list[str], threshold: float, num_perm: int, band_rows: int
+) -> list[tuple[list[int], float]]:
+    """Scalable MinHash-LSH variant of :func:`cluster_canonicals` for very large corpora.
+
+    Generates candidate pairs via MinHash-LSH (``num_perm`` permutations, ``band_rows`` rows per band),
+    then verifies each candidate with the exact ratio. Clusters match the exact path modulo LSH recall
+    (tuned via ``band_rows``); use :func:`cluster_canonicals` when exact recall is required.
+    """
+
+__all__: list[str]

python/difflib_fast/py.typed

@@ -698,8 +698,9 @@ mod python {
         super::cluster_canonicals_lsh(&canonicals, threshold, num_perm, band_rows)
     }
 
+    /// Compiled core of the `difflib_fast` Python package (re-exported by `difflib_fast/__init__.py`).
     #[pymodule]
-    fn difflib_fast(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    fn _difflib_fast(m: &Bound<'_, PyModule>) -> PyResult<()> {
         m.add_function(wrap_pyfunction!(ratio, m)?)?;
         m.add_function(wrap_pyfunction!(cluster_canonicals, m)?)?;
         m.add_function(wrap_pyfunction!(cluster_canonicals_lsh, m)?)?;