lexindex 0.1.0__tar.gz

lexindex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: rust (fmt · clippy · test · audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-audit
+      - name: fmt
+        run: cargo fmt --all --check
+      - name: clippy (default = with mph)
+        run: cargo clippy --all-targets -- -D warnings
+      - name: clippy (no-default-features = fst only)
+        run: cargo clippy --no-default-features --all-targets -- -D warnings
+      - name: test (default)
+        run: cargo test
+      - name: test (no-default-features)
+        run: cargo test --no-default-features
+      - name: cargo audit
+        run: cargo audit
+
+  python-build:
+    name: python (ruff · clippy · build)
+    runs-on: ubuntu-latest
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - uses: astral-sh/setup-uv@v5
+      - name: ruff check
+        run: uvx ruff check python/ tests/test_python.py
+      - name: ruff format --check
+        run: uvx ruff format --check python/ tests/test_python.py
+      - name: clippy (python bindings)
+        run: cargo clippy --features python -- -D warnings
+      - name: build abi3 wheel
+        run: uv run --with maturin maturin build --release --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: dist/*.whl
+
+  python-test:
+    name: python (pytest · stubtest · py${{ matrix.python-version }})
+    needs: python-build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheel
+          path: dist
+      # Install-only: the single abi3 wheel must import and pass on every supported interpreter.
+      - name: pytest
+        run: |
+          wheel=$(ls dist/*.whl | head -1)
+          uv run --python ${{ matrix.python-version }} --with pytest --with "$wheel" \
+            pytest tests/test_python.py -q
+      - name: stubtest
+        run: |
+          wheel=$(ls dist/*.whl | head -1)
+          uv run --python ${{ matrix.python-version }} --with mypy --with "$wheel" \
+            python -m mypy.stubtest lexindex

lexindex-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: Release
+
+# Build redistributable wheels for every platform and (on a version tag) publish to PyPI.
+# Publishing uses PyPI Trusted Publishing (OIDC) — add a pending publisher for this repo at
+# https://pypi.org/manage/account/publishing/ (workflow `release.yml`, environment `pypi`) before the
+# first `v*` tag, and create a `pypi` environment in the repo settings.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: wheels ${{ matrix.platform.runner }} ${{ matrix.platform.target }}
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - { runner: ubuntu-latest, target: x86_64 }
+          - { runner: ubuntu-latest, target: aarch64 }
+          # macOS x86_64 is cross-built on the arm64 macos-14 runner: dedicated Intel (macos-13)
+          # runners are scarce/deprecated. abi3 needs no interpreter at build time, so this is sound.
+          - { runner: macos-14, target: x86_64 }
+          - { runner: macos-14, target: aarch64 }
+          - { runner: windows-latest, target: x64 }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          manylinux: auto
+          sccache: "true"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform.runner }}-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    name: 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
+
+  publish:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [wheels, sdist]
+    if: startsWith(github.ref, 'refs/tags/')
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    runs-on: ubuntu-latest
+    needs: [publish]
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write # create the GitHub Release
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract this version's CHANGELOG section
+        run: |
+          ver="${GITHUB_REF_NAME#v}"
+          awk -v v="$ver" '
+            $0 ~ "^## \\[" v "\\]" { f = 1; next }
+            f && /^## \[/ { exit }
+            f { print }
+          ' CHANGELOG.md > release-notes.md
+          echo "----- release notes -----"; cat release-notes.md
+      - uses: softprops/action-gh-release@v2
+        with:
+          name: lexindex ${{ github.ref_name }}
+          body_path: release-notes.md

lexindex-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+/target
+/dist
+/.venv
+__pycache__/
+*.py[cod]
+*.so
+.pytest_cache/
+.ruff_cache/

lexindex-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-06-28
+
+First public release — compact, immutable string<->id indexes for huge catalogs; a standalone Rust +
+Python library that also pairs with `betula-cluster` (map string ids to cluster ids and back).
+
+### Added
+
+- **`StringIndex`** — ordered, FST-backed index: exact `string <-> id`, plus prefix, range, fuzzy
+  (bounded Levenshtein edit distance), and subsequence iteration — all automaton-driven over the FST,
+  never a full scan. Serialises to a flat, relocatable blob (`save` / `load` / `to_bytes` /
+  `from_bytes`) with fully length- and offset-validated parsing (safe on untrusted input).
+- **`PerfectHashIndex`** — minimal-perfect-hash dictionary (`ptr_hash`): verified-membership `id`,
+  a faster `id_unchecked` for closed vocabularies (~1.25× faster than `std::HashMap` on point lookup),
+  reverse lookup, and persistence (`save` / `load`) via `epserde`, keyed on a version-stable hash
+  (FNV-1a + splitmix64) so a serialised MPH reloads and queries identically on any build.
+- **Python bindings** (PyO3 abi3 extension, CPython 3.11+): `pip install lexindex`, zero runtime
+  dependencies, typed (`py.typed` + stubs).
+- **Feature gating** — `mph` (default) provides `PerfectHashIndex` (pulls `ptr_hash` + `epserde`);
+  `--no-default-features` is an `fst`-only build, free of the informational RustSec advisories on the
+  `ptr_hash` dependency tree. `fst`'s `levenshtein` is always on for fuzzy search.
+- **Benchmark** — `cargo run --release --example bench` compares both indexes against
+  `std::HashMap` / `BTreeMap` (build time, lookup latency, serialised size).