skimmatch 0.1.0__tar.gz

skimmatch-0.1.0/.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+target-dir = "C:/Users/steve/.cargo-target/skimmatch"

skimmatch-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# =========================================================
+# Rust / Cargo
+# =========================================================
+# This is the main build directory where all compiled artifacts are stored.
+# It's the most important entry for any Rust project.
+/target/
+
+# =========================================================
+# Python
+# =========================================================
+# Bytecode and compiled files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Virtual environments - add others if you use different names
+venv/
+.venv/
+env/
+.env/
+
+# Packaging and testing artifacts
+.eggs/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.tox/
+wheels/
+
+# =========================================================
+# IDEs and Editors
+# =========================================================
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# =========================================================
+# Operating System Files
+# =========================================================
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db

skimmatch-0.1.0/Cargo.lock

@@ -0,0 +1,158 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "fuzzy-matcher"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54614a3312934d066701a80f20f15fa3b56d67ac7722b39eea5b4c9dd1d66c94"
+dependencies = [
+ "thread_local",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91fd8e38a3b50ed1167fb981cd6fd60147e091784c427b8f7183a7ee32c31c12"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e368e7ddfdeb98c9bca7f8383be1648fd84ab466bf2bc015e94008db6d35611e"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f29e10af80b1f7ccaf7f69eace800a03ecd13e883acfacc1e5d0988605f651e"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df6e520eff47c45997d2fc7dd8214b25dd1310918bbb2642156ef66a67f29813"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.28.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4cdc218d835738f81c2338f822078af45b4afdf8b2e33cbb5916f108b813acb"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "skimmatch"
+version = "0.1.0"
+dependencies = [
+ "fuzzy-matcher",
+ "pyo3",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "thread_local"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"

skimmatch-0.1.0/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "skimmatch"
+version = "0.1.0"
+edition = "2021"
+readme = "README.md"
+
+[lib]
+name = "_skimmatch"
+crate-type = ["cdylib"]
+
+[dependencies]
+fuzzy-matcher = "0.3"
+pyo3 = { version = "0.28", features = ["extension-module"] }

skimmatch-0.1.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: skimmatch
+Version: 0.1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Summary: In-process fzf/skim-style fuzzy finder for Python, implemented in Rust.
+Author: TELOS
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# skimmatch
+
+`skimmatch` is an in-process fzf/skim-style fuzzy finder for Python,
+implemented in Rust.
+
+It is designed for ranked abbreviation matching over a fixed list of candidate
+strings. You give it strings such as filenames, references, titles, symbols, or
+command labels; users type short abbreviation-style queries; `skimmatch`
+returns the best candidates, scores, and optional highlight positions.
+
+```python
+from skimmatch import Matcher
+
+candidates = [
+    "Follmer and Schied, Stochastic Finance, 2011",
+    "Mildenhall and Major, Pricing Insurance Risk",
+    "Wang distortion risk measures",
+    "Archive reference catalogue",
+]
+
+matcher = Matcher(candidates)
+
+for result in matcher.search("wang distortion", limit=3):
+    print(result)
+```
+
+Example result:
+
+```python
+{
+    "index": 2,
+    "score": 260,
+    "text": "Wang distortion risk measures",
+    "matches": [0, 1, 2, 3, 5, 6, 7, 8, 9, 10],
+}
+```
+
+Scores are backend scores where higher is better. The exact numeric value should
+be treated as ranking information, not as a stable cross-version metric.
+
+## What This Is
+
+`skimmatch` solves the same broad problem as interactive fuzzy finders such as
+`fzf` and `skim`: finding good abbreviation matches quickly.
+
+For example, a query like:
+
+```text
+fs sf 2011
+```
+
+can match:
+
+```text
+Follmer and Schied, Stochastic Finance, 2011
+```
+
+because the query characters and tokens appear in useful positions and in the
+right order.
+
+This is different from edit-distance fuzzy matching. Libraries such as
+RapidFuzz, Levenshtein, or token-ratio matchers are excellent for typo
+correction, deduplication, OCR cleanup, and record linkage. `skimmatch` is aimed
+at fast candidate selection, interactive search, and highlightable abbreviation
+matching.
+
+## Features
+
+- In-process Python extension: no external `fzf` executable required.
+- Rust matching core using `SkimMatcherV2` from the `fuzzy-matcher` crate.
+- Preloaded candidate lists for fast repeated queries.
+- Single-token and multi-token search modes.
+- Optional highlight indices for UI rendering.
+- Legacy tuple-returning APIs for compatibility with the earlier `rustfuzz`
+  shape.
+- Structured `Matcher.search(...)` API for new code.
+- Backend argument already present, so future backends can be added without
+  changing the public matcher classes.
+
+## Installation
+
+When published on PyPI:
+
+```bash
+pip install skimmatch
+```
+
+From a local checkout:
+
+```bash
+uv pip install -e .
+```
+
+or build with maturin:
+
+```bash
+uv run maturin develop
+```
+
+The current package metadata targets Python 3.13 or newer.
+
+## Quick Start
+
+Use `Matcher` for new code.
+
+```python
+from skimmatch import Matcher
+
+candidates = [
+    "Buhlmann, Mathematical Methods in Risk Theory",
+    "Cramer, Collective Risk Theory",
+    "Mildenhall and Major, Pricing Insurance Risk",
+    "Kaas, Goovaerts, Dhaene, and Denuit, Modern Actuarial Risk Theory",
+]
+
+matcher = Matcher(candidates)
+results = matcher.search("risk theory", limit=5)
+
+for result in results:
+    print(result["index"], result["score"], result["text"])
+```
+
+By default, `search`:
+
+- splits the query on whitespace;
+- requires every query token to match;
+- returns up to 20 results;
+- includes candidate text;
+- includes highlight positions.
+
+## Structured API
+
+```python
+matcher = Matcher(candidates, backend="skim")
+results = matcher.search(
+    query,
+    limit=20,
+    highlights=True,
+    include_text=True,
+    multi=True,
+)
+```
+
+Each result is a dictionary containing:
+
+```python
+{
+    "index": 0,          # original candidate index
+    "score": 123,       # backend score, higher is better
+    "text": "...",      # included when include_text=True
+    "matches": [0, 3],  # included when highlights=True
+}
+```
+
+### Parameters
+
+`query`
+
+The search string. In multi-token mode, whitespace-separated tokens are matched
+independently and every token must match the candidate.
+
+`limit`
+
+The maximum number of results to return. `limit=0` returns an empty list.
+
+`highlights`
+
+When true, results include `matches`, a sorted and deduplicated list of matched
+positions. Turn this off when you only need ranking; score-only matching does
+less work.
+
+`include_text`
+
+When true, each result includes the original candidate string. Turn this off if
+you already have the candidate list and want smaller result objects.
+
+`multi`
+
+When true, the query is split on whitespace and all tokens are required. When
+false, the whole query is sent to the matcher as one pattern.
+
+## Legacy APIs
+
+The package also exports compatibility classes with tuple return shapes:
+
+```python
+from skimmatch import FuzzyMatcher, FuzzyMatcherMulti, FuzzyMatcherMultiHi
+```
+
+### `FuzzyMatcher`
+
+Treats the whole query as one pattern.
+
+```python
+matcher = FuzzyMatcher(candidates)
+indices, scores = matcher.query("sf", top_k=10)
+```
+
+### `FuzzyMatcherMulti`
+
+Splits the query on whitespace. Every token must match.
+
+```python
+matcher = FuzzyMatcherMulti(candidates)
+indices, scores = matcher.query("pricing insurance", top_k=10)
+```
+
+### `FuzzyMatcherMultiHi`
+
+Like `FuzzyMatcherMulti`, but also returns highlight positions.
+
+```python
+matcher = FuzzyMatcherMultiHi(candidates)
+indices, scores, highlights = matcher.query("pricing insurance", top_k=10)
+```
+
+## Matching Behavior
+
+The current backend is:
+
+```python
+backend="skim"
+```
+
+It uses `SkimMatcherV2` from the Rust `fuzzy-matcher` crate.
+
+Good matches tend to reward:
+
+- characters appearing in order;
+- compact alignments;
+- word-boundary matches;
+- punctuation-separated and camel-case transitions;
+- early matches;
+- consecutive query-character matches;
+- candidates that match every query token in multi-token mode.
+
+`skimmatch` returns candidates sorted by descending score. Ties are ordered by
+the original candidate index for deterministic output.
+
+## When To Use It
+
+`skimmatch` is a good fit for:
+
+- command palettes;
+- file pickers;
+- bibliography and reference search;
+- symbol search;
+- autocomplete over known labels;
+- terminal or web UI candidate selection;
+- fast repeated queries over a preloaded list.
+
+It is probably not the right tool for:
+
+- typo correction;
+- deduplication;
+- record linkage;
+- token-sort similarity;
+- OCR cleanup;
+- semantic search;
+- embedding-based retrieval.
+
+Those are useful problems, but they are different from fzf/skim-style
+abbreviation matching.
+
+## Performance Notes
+
+Candidate strings are copied into Rust once when the matcher is constructed.
+Repeated calls to `query` or `search` scan that Rust-owned list and return only
+the final top results to Python.
+
+For best performance:
+
+- construct one matcher and reuse it across queries;
+- set `highlights=False` when you only need indices and scores;
+- set `include_text=False` when you already have the candidate strings;
+- use `limit` to keep returned result objects small.
+
+## Development
+
+This project is a Python package with a Rust extension built by maturin.
+
+Run the tests:
+
+```bash
+uv run pytest tests/test_skimmatch.py -q
+```
+
+Check Rust formatting:
+
+```bash
+cargo fmt --check
+```
+
+Important files:
+
+- `src/lib.rs`: Rust/PyO3 extension implementation.
+- `python/skimmatch/__init__.py`: Python re-exports.
+- `tests/test_skimmatch.py`: API and behavior tests.
+- `pyproject.toml`: Python packaging and maturin configuration.
+- `Cargo.toml`: Rust crate configuration.
+
+## Backend Roadmap
+
+The public API already accepts a `backend` argument. Today only `"skim"` is
+implemented. Future candidates include:
+
+- `backend="nucleo"` for a modern fzf-like matcher;
+- `backend="frizbee"` for an experimental fast and typo-tolerant matcher.
+
+Unknown backend names currently raise `ValueError`.
+
+## License
+
+MIT.
+