rustfuzz 0.1.6__tar.gz

rustfuzz-0.1.6/.agents/workflows/push-to-main.md

@@ -0,0 +1,65 @@
+---
+description: push to main, monitor GitHub Actions CI, and verify docs deployment on GitHub Pages
+---
+
+# Push to Main and Monitor CI
+
+After pushing commits or tags to `main`, always verify that the GitHub Actions CI pipeline passes before considering the work done.
+
+// turbo-all
+
+1. Push the current branch / tag to GitHub:
+```
+git push origin main
+```
+   If pushing a tag, also run:
+```
+git push origin --tags
+```
+
+2. Wait a few seconds for GitHub to register the new run, then find the latest workflow run ID:
+```
+gh run list --branch main --workflow ci.yml --limit 5
+```
+
+3. Watch the run live in the terminal (replace `<RUN_ID>` with the ID from the previous step — pick the most recent one):
+```
+gh run watch <RUN_ID> --exit-status
+```
+   This streams real-time job/step status and returns a non-zero exit code if the run fails.
+
+4. If the run fails, inspect the failing job logs:
+```
+gh run view <RUN_ID> --log-failed
+```
+   Read the output carefully, identify the root cause, fix the code, commit, and repeat from step 1.
+
+5. Once `gh run watch` exits successfully (exit code 0), the CI is green.
+
+6. Verify the `docs` job succeeded specifically:
+```
+gh run view <RUN_ID> --json jobs --jq '.jobs[] | select(.name | startswith("Deploy docs")) | {name, status, conclusion}'
+```
+   Conclusion must be `success`. If it is `failure`, dump its logs:
+```
+gh run view <RUN_ID> --log-failed
+```
+
+7. Confirm the GitHub Pages site is live and reflects the latest content by fetching the docs URL:
+```
+curl -sI https://bmsuisse.github.io/rustfuzz/ | head -5
+```
+   Expect `HTTP/2 200`. If you get a non-200 or a stale cache, wait ~60 s and retry — Pages deployments can lag slightly behind the CI job completion.
+
+## Key CI jobs to watch
+
+| Job | Trigger | What it does |
+|---|---|---|
+| `test` | every push to `main` | cargo check, maturin build, pytest, pyright |
+| `docs` | push to `main` or tag | builds & deploys MkDocs → https://bmsuisse.github.io/rustfuzz/ |
+| `linux / musllinux / windows / macos` | tags only | builds release wheels |
+| `sdist` | tags only | builds source distribution |
+| `release` | tags only | publishes to PyPI |
+
+> **Note:** For a plain `main` push (no tag) only `test` and `docs` run.  
+> For a tagged release all jobs including `release` (PyPI publish) run.

rustfuzz-0.1.6/.agents/workflows/research-build-test-benchmark.md

@@ -0,0 +1,124 @@
+---
+description: Research → Build → Test → Benchmark → Repeat — the core optimisation loop for beating RapidFuzz
+---
+
+# Research → Build → Test → Benchmark → Repeat
+
+This is the core AI-driven optimisation loop for rustfuzz.
+Each iteration identifies a bottleneck, implements a Rust fix, validates correctness, and measures the gain against RapidFuzz.
+
+> **Rule:** never skip the Test step. A faster but broken library is worthless.
+
+---
+
+## 🔍 Step 1 — Research
+
+Profile the current hottest path and identify what to improve next.
+
+Run a quick benchmark first to get a baseline and see where time is spent:
+```
+uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-sort=mean 2>&1 | head -60
+```
+
+If you need function-level profiling, use `py-spy` on a benchmark call:
+```
+uv run py-spy record -o profile.svg -- python -c "
+import rustfuzz.process as p
+import rapidfuzz.process as rf
+choices = ['New York','Newark','New Orleans','Los Angeles'] * 5000
+p.extract('new york', choices, limit=5)
+"
+```
+
+Identify the specific Rust function or Python↔Rust boundary causing overhead.
+Document the hypothesis: _"the bottleneck is X because Y"_.
+
+---
+
+## 🦀 Step 2 — Build
+
+Implement the fix in Rust and rebuild the extension module.
+
+Make your Rust changes in `src/`, then build in dev mode:
+// turbo
+```
+uv run maturin develop --release
+```
+
+Check that the Rust code compiles cleanly with no warnings:
+// turbo
+```
+cargo check 2>&1
+```
+
+---
+
+## ✅ Step 3 — Test
+
+**All tests must pass before proceeding.** No exceptions.
+
+// turbo
+```
+uv run pytest tests/ -x -q
+```
+
+If any test fails, go back to Step 2 and fix the regression before moving on.
+
+Also run pyright to catch any type errors introduced in Python stubs or wrappers:
+// turbo
+```
+uv run pyright
+```
+
+---
+
+## 📊 Step 4 — Benchmark
+
+Run the full benchmark suite and compare against RapidFuzz.
+
+```
+uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-compare --benchmark-sort=mean
+```
+
+Key metrics to record for each function (`ratio`, `partial_ratio`, `token_sort_ratio`, `process.extract`, `process.extractOne`):
+
+| Metric | Target |
+|--------|--------|
+| Mean time | ≤ RapidFuzz mean |
+| Min time | competitive |
+| Throughput | ≥ RapidFuzz |
+
+Save the results for comparison in the next iteration:
+```
+uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-save=iteration_N
+```
+
+Interpret the results:
+- **Better** → document the gain, pick the next bottleneck → Step 5.
+- **Worse / no change** → revisit the approach in Step 1.
+
+---
+
+## 🔁 Step 5 — Repeat
+
+Pick the next biggest gap from the benchmark output and go back to Step 1.
+
+Useful questions to guide the next Research phase:
+- Which function is still slowest relative to RapidFuzz?
+- Is the bottleneck in the algorithm itself, the Python↔Rust boundary, or string allocation?
+- Can batch operations (`cdist`, `extract`) be parallelised with Rayon?
+- Are we paying for UTF-8 re-encoding on every call?
+
+---
+
+## Quick-reference commands
+
+| Command | Purpose |
+|---------|---------|
+| `uv run maturin develop --release` | Rebuild Rust extension (optimised) |
+| `cargo check` | Fast compile check without linking |
+| `uv run pytest tests/ -x -q` | Full test suite, stop on first failure |
+| `uv run pyright` | Type-check Python stubs |
+| `uv run pytest tests/benchmarks/ -v --benchmark-only` | Full benchmark run |
+| `uv run pytest tests/benchmarks/ -k ratio --benchmark-only` | Benchmark a single function |
+| `uv run pytest tests/benchmarks/ --benchmark-compare` | Compare vs saved baseline |

rustfuzz-0.1.6/.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustflags = ["-C", "target-cpu=native"]

rustfuzz-0.1.6/.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly

rustfuzz-0.1.6/.github/workflows/ci.yml

@@ -0,0 +1,227 @@
+# Based on httpxr reference CI
+name: CI
+
+on:
+  push:
+    tags:
+      - '*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: py${{ matrix.python-version }}
+
+      - name: Cargo check
+        run: cargo check --all-targets
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build & install (maturin develop)
+        run: uv run maturin develop --release
+
+      - name: Run pytest
+        run: uv run pytest tests/ -q -x
+
+      - name: Run basedpyright
+        run: uv run basedpyright rustfuzz/
+
+      - name: Run ruff
+        run: |
+          uv run ruff check
+          uv run ruff format --check
+
+  linux:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test]
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-24.04
+            target: x86_64
+          - runner: ubuntu-24.04-arm
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: true
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test]
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+    strategy:
+      matrix:
+        platform:
+          - runner: ubuntu-24.04
+            target: x86_64
+          - runner: ubuntu-24.04-arm
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: true
+          manylinux: musllinux_1_2
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-musllinux-${{ matrix.platform.target }}
+          path: dist
+
+  windows:
+    runs-on: windows-latest
+    needs: [test]
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --out dist --find-interpreter
+          sccache: true
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-windows-x64
+          path: dist
+
+  macos:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test]
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+    strategy:
+      matrix:
+        platform:
+          - runner: macos-14
+            target: aarch64
+          - runner: macos-15-intel
+            target: x86_64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: true
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-macos-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    needs: [test]
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-sdist
+          path: dist
+
+  release:
+    name: Release to PyPI
+    runs-on: ubuntu-latest
+    if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    needs: [linux, musllinux, windows, macos, sdist]
+    environment: pypi-release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  docs:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    needs: [test]
+    if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build --clean
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+      - uses: actions/deploy-pages@v4
+        id: deployment

rustfuzz-0.1.6/.gitignore

@@ -0,0 +1,35 @@
+.vscode/
+__pycache__/
+.idea/
+.venv/
+build/
+_skbuild/
+rapidfuzz.egg-info/
+dist/
+*.data
+*.so
+*.o
+*.out
+test.py
+src/*.html
+.coverage
+coverage.xml
+sde/
+
+# Sphinx documentation
+site/
+
+# benchmark results
+bench_results/
+
+# Hypothesis results
+.hypothesis/
+
+# Cython generated files
+*.cxx
+
+# temp files from benchmarks
+bench/temp/
+
+# Rust build artifacts
+target/

rustfuzz-0.1.6/.pre-commit-config.yaml

@@ -0,0 +1,82 @@
+# To use:
+#
+#     pre-commit run -a
+#
+# Or:
+#
+#     pre-commit install  # (runs every time you commit in git)
+#
+# To update this file:
+#
+#     pre-commit autoupdate
+#
+# See https://github.com/pre-commit/pre-commit
+
+repos:
+# Standard hooks
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: "v5.0.0"
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-docstring-first
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-toml
+  - id: check-yaml
+  - id: debug-statements
+  - id: end-of-file-fixer
+  - id: mixed-line-ending
+  - id: requirements-txt-fixer
+  - id: trailing-whitespace
+
+
+
+# Changes tabs to spaces
+- repo: https://github.com/Lucas-C/pre-commit-hooks
+  rev: "v1.5.5"
+  hooks:
+  - id: remove-tabs
+
+- repo: https://github.com/sirosen/texthooks
+  rev: "0.6.8"
+  hooks:
+  - id: fix-ligatures
+  - id: fix-smartquotes
+
+# Checking for common mistakes
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: "v1.10.0"
+  hooks:
+  - id: rst-backticks
+  - id: rst-directive-colons
+  - id: rst-inline-touching-normal
+
+- repo: https://github.com/charliermarsh/ruff-pre-commit
+  rev: v0.11.5
+  hooks:
+  - id: ruff
+    args: ["--fix", "--show-fixes"]
+  - id: ruff-format
+
+# Check for spelling
+- repo: https://github.com/codespell-project/codespell
+  rev: "v2.4.1"
+  hooks:
+  - id: codespell
+    exclude: ".*/test_.*.py"
+
+# Check for common shell mistakes
+- repo: https://github.com/shellcheck-py/shellcheck-py
+  rev: "v0.10.0.1"
+  hooks:
+  - id: shellcheck
+
+# Disallow some common capitalization mistakes
+- repo: local
+  hooks:
+  - id: disallow-caps
+    name: Disallow improper capitalization
+    language: pygrep
+    entry: PyBind|Numpy|Cmake|CCache|PyTest
+    exclude: ^\.pre-commit-config.yaml$

rustfuzz-0.1.6/AGENTS.md

@@ -0,0 +1,123 @@
+# rustfuzz Agent Guidelines
+
+## Project Overview
+
+rustfuzz is a high-performance fuzzy string matching library implemented entirely in Rust, published as `rustfuzz` on PyPI. It uses:
+- **Rust** (via PyO3 + maturin) for all core fuzzy-matching algorithms
+- **Python** (3.10+) for the public API surface — thin wrappers that re-export Rust symbols
+- **uv** for Python package management
+
+## Architecture
+
+```
+src/                    ← Rust source (compiled as rustfuzz._rustfuzz)
+  lib.rs                ← PyO3 module root — fn _rustfuzz
+  algorithms.rs         ← Core algorithm implementations (Myers, LCS, Jaro, etc.)
+  fuzz.rs               ← ratio, partial_ratio, token_*, WRatio, QRatio
+  utils.rs              ← default_process
+  types.rs              ← Seq type + Python object extraction helpers
+  distance/
+    mod.rs
+    initialize.rs       ← Editop, Editops, Opcode, Opcodes, MatchingBlock, ScoreAlignment
+    metrics.rs          ← All distance/similarity pyfunction wrappers
+rustfuzz/               ← Python package (thin wrappers, imports from ._rustfuzz)
+Cargo.toml              ← lib name = "_rustfuzz"
+pyproject.toml          ← module-name = "rustfuzz._rustfuzz"
+```
+
+## Public API Surface
+
+### `rustfuzz.fuzz`
+`ratio`, `partial_ratio`, `partial_ratio_alignment`, `token_sort_ratio`, `token_set_ratio`,
+`token_ratio`, `partial_token_sort_ratio`, `partial_token_set_ratio`, `partial_token_ratio`,
+`WRatio`, `QRatio`
+
+### `rustfuzz.process`
+`extract`, `extractOne`, `extract_iter`, `cdist`
+
+### `rustfuzz.utils`
+`default_process`
+
+### `rustfuzz.distance`
+**Data types:** `Editop`, `Editops`, `Opcode`, `Opcodes`, `MatchingBlock`, `ScoreAlignment`
+
+**Per-metric (all modules):** `distance`, `similarity`, `normalized_distance`,
+`normalized_similarity`, `editops` (where applicable), `opcodes` (where applicable)
+
+**Modules:** `Levenshtein`, `Hamming`, `Indel`, `Jaro`, `JaroWinkler`, `LCSseq`,
+`OSA`, `DamerauLevenshtein`, `Prefix`, `Postfix`
+
+## Critical Rules
+
+### Always Use `uv`
+- **All Python commands MUST use `uv run`** — never use `.venv/bin/python` or bare `python`
+- Tests: `uv run pytest tests/ -x -q`
+- Benchmarks: `uv run pytest tests/test_benchmarks.py --benchmark-save=baseline`
+- Benchmark regression: `uv run pytest tests/test_benchmarks.py --benchmark-compare=baseline --benchmark-compare-fail=mean:10%`
+- Type checking: `uv run pyright`
+- Smoke test: `uv run python -c "import rustfuzz; print(rustfuzz.__version__)"`
+
+### Build Workflow
+1. `cargo check` — fast compilation check
+2. `uv run maturin develop --release` — build optimised `.so`
+
+### Pre-Commit Checklist
+1. `cargo check` — no Rust errors
+2. `uv run maturin develop --release`
+3. `uv run pytest tests/ -x -q` — all tests must pass
+4. `uv run pytest tests/test_benchmarks.py --benchmark-compare=baseline --benchmark-compare-fail=mean:10%` — no regressions
+5. `uv run pyright` — type checking passes
+
+### File Size Limit
+- No file should exceed 1000 lines of code
+
+### Testing
+- Always run the **full** original test suite before committing
+- Run e2e tests after implementing new features
+- Create a branch for each feature/algorithm group
+
+### Implementation Strategy
+- Each metric module (`Levenshtein`, `Hamming`, etc.) must agree with the reference algorithms
+- `process.cdist` consumes any scorer callable accepting `(str, str, **kwargs) -> float`
+- Benchmarks baseline is saved in `.benchmarks/` — commit it so CI can compare
+
+## Releasing a New Version
+
+The CI automatically builds wheels for all platforms, generates a changelog, and publishes
+to PyPI when a **git tag** is pushed.
+
+### Steps
+1. **Bump version** in `Cargo.toml` (the `version` field under `[package]`)
+2. **Commit** the version bump: `git commit -am "release: v0.X.Y"`
+3. **Tag** the commit: `git tag v0.X.Y`
+4. **Push** the tag: `git push origin main && git push origin v0.X.Y`
+5. CI will:
+   - Run tests on all Python versions
+   - Build wheels (linux, musllinux, macos, windows)
+   - Generate changelog from conventional commits (via `git-cliff`)
+   - Publish to PyPI
+   - Create GitHub Release with changelog and wheel assets
+
+### Commit Convention
+Use [Conventional Commits](https://www.conventionalcommits.org/) for automatic changelog
+categorization:
+
+| Prefix | Category | Example |
+|--------|----------|---------| 
+| `feat:` | 🚀 Features | `feat: implement Jaro-Winkler in Rust` |
+| `fix:` | 🐛 Bug Fixes | `fix: handle empty string in partial_ratio` |
+| `perf:` | ⚡ Performance | `perf: use SIMD in Levenshtein` |
+| `refactor:` | 🔧 Refactoring | `refactor: split distance module` |
+| `docs:` | 📖 Documentation | `docs: update README` |
+| `ci:` | 🔄 CI/CD | `ci: add Python 3.13 to matrix` |
+| `chore:` | 📦 Miscellaneous | `chore: update deps` |
+| `release:` | _(skipped)_ | `release: v3.15.0` |
+
+### Verify Before Releasing
+```bash
+cargo check
+uv run maturin develop --release
+uv run pytest tests/ -x -q
+uv run pytest tests/test_benchmarks.py --benchmark-compare=baseline --benchmark-compare-fail=mean:10%
+uv run pyright
+```