Fuzzylookup 0.0.1__tar.gz

fuzzylookup-0.0.1/Fuzzylookup.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: Fuzzylookup
+Version: 0.0.1
+Summary: A package for Fuzzy Lookup
+Project-URL: Homepage, https://github.com/Moda141/Fuzzylookup
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# FuzzyLookup Documentation
+
+## Overview
+`fuzzylookup` (version 0.1.0) is a Python package designed for fuzzy matching and lookups against CSV or Excel datasets [cite: 1, 2, 3]. It explicitly supports both Arabic and English text [cite: 2, 3]. Under the hood, it leverages `pandas` for data handling and `rapidfuzz` for high-performance string matching [cite: 2, 3].
+
+## Installation
+The package requires Python 3.8 or higher [cite: 3]. 
+Dependencies include:
+* `pandas>=1.3` [cite: 3]
+* `openpyxl>=3.0` (for Excel support) [cite: 3]
+* `rapidfuzz>=3.0` [cite: 3]
+
+## Core Features
+
+### 1. Arabic Text Normalization
+By default, `fuzzylookup` applies normalization to Arabic text (`normalize_arabic=True`) [cite: 2]. This process improves match quality by:
+* Removing *tashkeel* (diacritics) [cite: 2].
+* Normalizing Alef variants (أ, إ, آ, ٱ) to a standard Alef (ا) [cite: 2].
+* Normalizing Teh marbuta (ة) to Heh (ه) [cite: 2].
+* Normalizing Alef maqsura (ى) to Yeh (ي) [cite: 2].
+
+### 2. Positional Name-Aware Scoring
+A standout feature is the `name_aware` scoring algorithm [cite: 2]. Standard fuzzy matching algorithms might score "محمد كمال" and "كمال محمد" similarly, but `fuzzylookup` can punish wrong token orders when `name_aware=True` is enabled [cite: 2]. 
+* It compares names token-by-token in order [cite: 2].
+* The first token accounts for 60% of the score, and the remaining tokens account for 40% [cite: 2].
+* It blends this positional score with `WRatio` to handle both typos and correct word order gracefully [cite: 2].
+* If WRatio exceeds the positional score by more than 15 points, it indicates token reordering is inflating the score, triggering a penalty [cite: 2].
+
+## API Reference
+
+### `FuzzyLookup` Class
+The primary entry point is the `FuzzyLookup` class [cite: 1, 2].
+
+**Parameters:**
+* `source` (str, Path, or pd.DataFrame): Path to the CSV/Excel file or an existing DataFrame [cite: 2].
+* `column` (str): The column name to match against [cite: 2].
+* `scorer` (str): Matching algorithm to use (`ratio`, `partial`, `token_sort`, `token_set`, `wratio`). Defaults to `wratio` [cite: 2].
+* `normalize_arabic` (bool): Whether to strip diacritics and normalize characters. Defaults to `True` [cite: 2].
+* `name_aware` (bool): Enables positional name scoring. Recommended for full person names. Defaults to `False` [cite: 2].
+* `encoding` (str): File encoding for CSVs. Defaults to `utf-8` [cite: 2].
+
+### Methods
+
+* `lookup(query: str, top_n: int = 5, min_score: float = 0.0, columns: list = None)`: Returns the top `N` best matches for the search string [cite: 2]. Returns a list of dictionaries with row data, the calculated `score`, and `_index` [cite: 2].
+* `lookup_best(query: str, min_score: float = 0.0, columns: list = None)`: Returns only the single best match, or `None` if no match meets the minimum score [cite: 2].
+* `lookup_many(queries: list, top_n: int = 1, min_score: float = 0.0, columns: list = None)`: Batch lookup for multiple queries. Returns a dictionary mapping each query to its list of results [cite: 2].
+
+### Properties
+* `columns`: Returns a list of the columns available in the loaded dataframe [cite: 2].
+* `shape`: Returns a tuple representing the shape of the underlying dataframe [cite: 2].
+
+## Workflow Example
+
+Below is a typical workflow demonstrating how to instantiate the lookup object and perform queries [cite: 2]:
+
+```python
+from fuzzylookup import FuzzyLookup
+
+# 1. Initialize the lookup instance with a dataset
+fl = FuzzyLookup("names.csv", column="name", name_aware=True)
+
+# 2. Perform a standard lookup for the top 3 matches
+results = fl.lookup("محمد كمال", top_n=3)
+
+# 3. Perform a strict lookup requiring a high match score
+best_match = fl.lookup_best("كمال محمد", min_score=85.0)
+
+# 4. Batch processing multiple names
+batch_results = fl.lookup_many(["أحمد علي", "محمود حسن"], top_n=1)
+```

fuzzylookup-0.0.1/Fuzzylookup.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+Fuzzylookup.egg-info/PKG-INFO
+Fuzzylookup.egg-info/SOURCES.txt
+Fuzzylookup.egg-info/dependency_links.txt
+Fuzzylookup.egg-info/top_level.txt
+fuzzylookup/__init__.py
+fuzzylookup/core.py
+fuzzylookup/setup.py

fuzzylookup-0.0.1/Fuzzylookup.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fuzzylookup-0.0.1/Fuzzylookup.egg-info/top_level.txt

@@ -0,0 +1 @@
+fuzzylookup

fuzzylookup-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed kamal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fuzzylookup-0.0.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: Fuzzylookup
+Version: 0.0.1
+Summary: A package for Fuzzy Lookup
+Project-URL: Homepage, https://github.com/Moda141/Fuzzylookup
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# FuzzyLookup Documentation
+
+## Overview
+`fuzzylookup` (version 0.1.0) is a Python package designed for fuzzy matching and lookups against CSV or Excel datasets [cite: 1, 2, 3]. It explicitly supports both Arabic and English text [cite: 2, 3]. Under the hood, it leverages `pandas` for data handling and `rapidfuzz` for high-performance string matching [cite: 2, 3].
+
+## Installation
+The package requires Python 3.8 or higher [cite: 3]. 
+Dependencies include:
+* `pandas>=1.3` [cite: 3]
+* `openpyxl>=3.0` (for Excel support) [cite: 3]
+* `rapidfuzz>=3.0` [cite: 3]
+
+## Core Features
+
+### 1. Arabic Text Normalization
+By default, `fuzzylookup` applies normalization to Arabic text (`normalize_arabic=True`) [cite: 2]. This process improves match quality by:
+* Removing *tashkeel* (diacritics) [cite: 2].
+* Normalizing Alef variants (أ, إ, آ, ٱ) to a standard Alef (ا) [cite: 2].
+* Normalizing Teh marbuta (ة) to Heh (ه) [cite: 2].
+* Normalizing Alef maqsura (ى) to Yeh (ي) [cite: 2].
+
+### 2. Positional Name-Aware Scoring
+A standout feature is the `name_aware` scoring algorithm [cite: 2]. Standard fuzzy matching algorithms might score "محمد كمال" and "كمال محمد" similarly, but `fuzzylookup` can punish wrong token orders when `name_aware=True` is enabled [cite: 2]. 
+* It compares names token-by-token in order [cite: 2].
+* The first token accounts for 60% of the score, and the remaining tokens account for 40% [cite: 2].
+* It blends this positional score with `WRatio` to handle both typos and correct word order gracefully [cite: 2].
+* If WRatio exceeds the positional score by more than 15 points, it indicates token reordering is inflating the score, triggering a penalty [cite: 2].
+
+## API Reference
+
+### `FuzzyLookup` Class
+The primary entry point is the `FuzzyLookup` class [cite: 1, 2].
+
+**Parameters:**
+* `source` (str, Path, or pd.DataFrame): Path to the CSV/Excel file or an existing DataFrame [cite: 2].
+* `column` (str): The column name to match against [cite: 2].
+* `scorer` (str): Matching algorithm to use (`ratio`, `partial`, `token_sort`, `token_set`, `wratio`). Defaults to `wratio` [cite: 2].
+* `normalize_arabic` (bool): Whether to strip diacritics and normalize characters. Defaults to `True` [cite: 2].
+* `name_aware` (bool): Enables positional name scoring. Recommended for full person names. Defaults to `False` [cite: 2].
+* `encoding` (str): File encoding for CSVs. Defaults to `utf-8` [cite: 2].
+
+### Methods
+
+* `lookup(query: str, top_n: int = 5, min_score: float = 0.0, columns: list = None)`: Returns the top `N` best matches for the search string [cite: 2]. Returns a list of dictionaries with row data, the calculated `score`, and `_index` [cite: 2].
+* `lookup_best(query: str, min_score: float = 0.0, columns: list = None)`: Returns only the single best match, or `None` if no match meets the minimum score [cite: 2].
+* `lookup_many(queries: list, top_n: int = 1, min_score: float = 0.0, columns: list = None)`: Batch lookup for multiple queries. Returns a dictionary mapping each query to its list of results [cite: 2].
+
+### Properties
+* `columns`: Returns a list of the columns available in the loaded dataframe [cite: 2].
+* `shape`: Returns a tuple representing the shape of the underlying dataframe [cite: 2].
+
+## Workflow Example
+
+Below is a typical workflow demonstrating how to instantiate the lookup object and perform queries [cite: 2]:
+
+```python
+from fuzzylookup import FuzzyLookup
+
+# 1. Initialize the lookup instance with a dataset
+fl = FuzzyLookup("names.csv", column="name", name_aware=True)
+
+# 2. Perform a standard lookup for the top 3 matches
+results = fl.lookup("محمد كمال", top_n=3)
+
+# 3. Perform a strict lookup requiring a high match score
+best_match = fl.lookup_best("كمال محمد", min_score=85.0)
+
+# 4. Batch processing multiple names
+batch_results = fl.lookup_many(["أحمد علي", "محمود حسن"], top_n=1)
+```

fuzzylookup-0.0.1/README.md

@@ -0,0 +1,70 @@
+# FuzzyLookup Documentation
+
+## Overview
+`fuzzylookup` (version 0.1.0) is a Python package designed for fuzzy matching and lookups against CSV or Excel datasets [cite: 1, 2, 3]. It explicitly supports both Arabic and English text [cite: 2, 3]. Under the hood, it leverages `pandas` for data handling and `rapidfuzz` for high-performance string matching [cite: 2, 3].
+
+## Installation
+The package requires Python 3.8 or higher [cite: 3]. 
+Dependencies include:
+* `pandas>=1.3` [cite: 3]
+* `openpyxl>=3.0` (for Excel support) [cite: 3]
+* `rapidfuzz>=3.0` [cite: 3]
+
+## Core Features
+
+### 1. Arabic Text Normalization
+By default, `fuzzylookup` applies normalization to Arabic text (`normalize_arabic=True`) [cite: 2]. This process improves match quality by:
+* Removing *tashkeel* (diacritics) [cite: 2].
+* Normalizing Alef variants (أ, إ, آ, ٱ) to a standard Alef (ا) [cite: 2].
+* Normalizing Teh marbuta (ة) to Heh (ه) [cite: 2].
+* Normalizing Alef maqsura (ى) to Yeh (ي) [cite: 2].
+
+### 2. Positional Name-Aware Scoring
+A standout feature is the `name_aware` scoring algorithm [cite: 2]. Standard fuzzy matching algorithms might score "محمد كمال" and "كمال محمد" similarly, but `fuzzylookup` can punish wrong token orders when `name_aware=True` is enabled [cite: 2]. 
+* It compares names token-by-token in order [cite: 2].
+* The first token accounts for 60% of the score, and the remaining tokens account for 40% [cite: 2].
+* It blends this positional score with `WRatio` to handle both typos and correct word order gracefully [cite: 2].
+* If WRatio exceeds the positional score by more than 15 points, it indicates token reordering is inflating the score, triggering a penalty [cite: 2].
+
+## API Reference
+
+### `FuzzyLookup` Class
+The primary entry point is the `FuzzyLookup` class [cite: 1, 2].
+
+**Parameters:**
+* `source` (str, Path, or pd.DataFrame): Path to the CSV/Excel file or an existing DataFrame [cite: 2].
+* `column` (str): The column name to match against [cite: 2].
+* `scorer` (str): Matching algorithm to use (`ratio`, `partial`, `token_sort`, `token_set`, `wratio`). Defaults to `wratio` [cite: 2].
+* `normalize_arabic` (bool): Whether to strip diacritics and normalize characters. Defaults to `True` [cite: 2].
+* `name_aware` (bool): Enables positional name scoring. Recommended for full person names. Defaults to `False` [cite: 2].
+* `encoding` (str): File encoding for CSVs. Defaults to `utf-8` [cite: 2].
+
+### Methods
+
+* `lookup(query: str, top_n: int = 5, min_score: float = 0.0, columns: list = None)`: Returns the top `N` best matches for the search string [cite: 2]. Returns a list of dictionaries with row data, the calculated `score`, and `_index` [cite: 2].
+* `lookup_best(query: str, min_score: float = 0.0, columns: list = None)`: Returns only the single best match, or `None` if no match meets the minimum score [cite: 2].
+* `lookup_many(queries: list, top_n: int = 1, min_score: float = 0.0, columns: list = None)`: Batch lookup for multiple queries. Returns a dictionary mapping each query to its list of results [cite: 2].
+
+### Properties
+* `columns`: Returns a list of the columns available in the loaded dataframe [cite: 2].
+* `shape`: Returns a tuple representing the shape of the underlying dataframe [cite: 2].
+
+## Workflow Example
+
+Below is a typical workflow demonstrating how to instantiate the lookup object and perform queries [cite: 2]:
+
+```python
+from fuzzylookup import FuzzyLookup
+
+# 1. Initialize the lookup instance with a dataset
+fl = FuzzyLookup("names.csv", column="name", name_aware=True)
+
+# 2. Perform a standard lookup for the top 3 matches
+results = fl.lookup("محمد كمال", top_n=3)
+
+# 3. Perform a strict lookup requiring a high match score
+best_match = fl.lookup_best("كمال محمد", min_score=85.0)
+
+# 4. Batch processing multiple names
+batch_results = fl.lookup_many(["أحمد علي", "محمود حسن"], top_n=1)
+```

fuzzylookup-0.0.1/fuzzylookup/__init__.py

@@ -0,0 +1,4 @@
+from .core import FuzzyLookup
+
+__all__ = ["FuzzyLookup"]
+__version__ = "0.1.0"

fuzzylookup-0.0.1/fuzzylookup/core.py

@@ -0,0 +1,306 @@
+"""
+fuzzylookup - Fuzzy matching lookup for CSV/Excel datasets
+Supports Arabic and English text, with positional name-aware scoring.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+from typing import Any, Optional, Union
+
+try:
+    import pandas as pd
+except ImportError:
+    raise ImportError("pandas is required: pip install pandas openpyxl")
+
+try:
+    from rapidfuzz import fuzz, process
+except ImportError:
+    raise ImportError("rapidfuzz is required: pip install rapidfuzz")
+
+
+# ---------------------------------------------------------------------------
+# Text normalization
+# ---------------------------------------------------------------------------
+
+def _normalize_arabic(text: str) -> str:
+    """Normalize Arabic text for better matching."""
+    if not isinstance(text, str):
+        return str(text)
+    text = unicodedata.normalize("NFC", text)
+    # Remove tashkeel (diacritics)
+    text = re.sub(r"[\u0610-\u061A\u064B-\u065F\u0670\u06D6-\u06DC\u06DF-\u06E4\u06E7\u06E8\u06EA-\u06ED]", "", text)
+    text = re.sub(r"[أإآٱ]", "ا", text)   # Alef variants
+    text = re.sub(r"ة", "ه", text)          # Teh marbuta
+    text = re.sub(r"ى", "ي", text)          # Alef maqsura
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def _normalize(text: str, arabic: bool = True) -> str:
+    if not isinstance(text, str):
+        text = str(text)
+    text = text.strip().lower()
+    if arabic:
+        text = _normalize_arabic(text)
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Scorer aliases
+# ---------------------------------------------------------------------------
+
+SCORERS = {
+    "ratio":      fuzz.ratio,
+    "partial":    fuzz.partial_ratio,
+    "token_sort": fuzz.token_sort_ratio,
+    "token_set":  fuzz.token_set_ratio,
+    "wratio":     fuzz.WRatio,
+}
+
+
+# ---------------------------------------------------------------------------
+# Positional Name Scoring
+# ---------------------------------------------------------------------------
+
+def _tokenize(name: str) -> list[str]:
+    tokens = name.strip().split()
+    return tokens if tokens else [""]
+
+
+def _positional_name_score(
+    query: str,
+    candidate: str,
+    first_weight: float = 0.6,
+    rest_weight: float = 0.4,
+) -> float:
+    """
+    Compare names token-by-token in order.
+
+    - First token vs first token  → 60% of score
+    - Remaining tokens joined     → 40% of score
+
+    Example:
+        "محمد كمال" vs "محمد كمال"  → ~100
+        "محمد كمال" vs "كمال محمد"  → ~50  (first tokens مختلفين)
+        "محمد كمال" vs "محمد علي"   → ~65  (first token متطابق، الباقي مختلف)
+    """
+    q_tokens = _tokenize(query)
+    c_tokens = _tokenize(candidate)
+
+    # Single token on either side → plain ratio
+    if len(q_tokens) == 1 or len(c_tokens) == 1:
+        return fuzz.ratio(query, candidate)
+
+    # First token score
+    first_score = fuzz.ratio(q_tokens[0], c_tokens[0])
+
+    # Rest tokens (join and compare)
+    q_rest = " ".join(q_tokens[1:])
+    c_rest = " ".join(c_tokens[1:])
+    rest_score = fuzz.token_sort_ratio(q_rest, c_rest)
+
+    return (first_score * first_weight) + (rest_score * rest_weight)
+
+
+def _smart_name_score(query: str, candidate: str) -> float:
+    """
+    Blend positional + WRatio for best of both worlds:
+    - Positional punishes wrong token order  (محمد كمال ≠ كمال محمد)
+    - WRatio handles typos and partial names
+
+    If WRatio >> positional by >15 pts → token reordering is inflating WRatio
+    → apply penalty so swapped names don't score the same as correct order.
+    """
+    positional = _positional_name_score(query, candidate)
+    wratio = fuzz.WRatio(query, candidate)
+
+    diff = wratio - positional
+    if diff > 15:
+        # WRatio is inflating because of token reordering — penalize
+        return (positional * 0.7) + (wratio * 0.3)
+    else:
+        return (positional * 0.5) + (wratio * 0.5)
+
+
+# ---------------------------------------------------------------------------
+# FuzzyLookup
+# ---------------------------------------------------------------------------
+
+class FuzzyLookup:
+    """
+    Fuzzy lookup over a CSV or Excel dataset.
+
+    Parameters
+    ----------
+    source : str | Path | pd.DataFrame
+        Path to CSV/Excel file, or an already-loaded DataFrame.
+    column : str
+        The column to match against.
+    scorer : str
+        Matching algorithm: ratio, partial, token_sort, token_set, wratio (default).
+    normalize_arabic : bool
+        Strip diacritics & normalize Arabic characters (default True).
+    name_aware : bool
+        Enable positional name scoring so that "محمد كمال" and "كمال محمد"
+        score differently. First token is weighted higher than the rest.
+        Recommended when the column contains full person names (default False).
+    encoding : str
+        File encoding for CSV (default 'utf-8').
+
+    Examples
+    --------
+    >>> fl = FuzzyLookup("names.csv", column="name", name_aware=True)
+    >>> fl.lookup("محمد كمال", top_n=3)
+    """
+
+    def __init__(
+        self,
+        source: Union[str, Path, "pd.DataFrame"],
+        column: str,
+        scorer: str = "wratio",
+        normalize_arabic: bool = True,
+        name_aware: bool = False,
+        encoding: str = "utf-8",
+    ):
+        self.column = column
+        self.scorer = SCORERS.get(scorer, fuzz.WRatio)
+        self.normalize_arabic = normalize_arabic
+        self.name_aware = name_aware
+
+        # Load data
+        if isinstance(source, (str, Path)):
+            path = Path(source)
+            if path.suffix.lower() in {".xlsx", ".xls"}:
+                self._df = pd.read_excel(path)
+            else:
+                self._df = pd.read_csv(path, encoding=encoding)
+        elif isinstance(source, pd.DataFrame):
+            self._df = source.copy()
+        else:
+            raise TypeError("source must be a file path or a pandas DataFrame")
+
+        if column not in self._df.columns:
+            raise ValueError(
+                f"Column '{column}' not found. Available: {list(self._df.columns)}"
+            )
+
+        self._choices: list[str] = (
+            self._df[column].fillna("").astype(str).tolist()
+        )
+        self._normalized_choices: list[str] = [
+            _normalize(c, arabic=self.normalize_arabic) for c in self._choices
+        ]
+
+    # ------------------------------------------------------------------
+    # Internal scoring
+    # ------------------------------------------------------------------
+
+    def _score(self, query: str, candidate: str) -> float:
+        """Score a query against a candidate string."""
+        if self.name_aware:
+            return _smart_name_score(query, candidate)
+        return self.scorer(query, candidate)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def lookup(
+        self,
+        query: str,
+        top_n: int = 5,
+        min_score: float = 0.0,
+        columns: Optional[list[str]] = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Return the top-N best matches for *query*.
+
+        Parameters
+        ----------
+        query : str       — search string
+        top_n : int       — max results (default 5)
+        min_score : float — minimum score 0–100 (default 0)
+        columns : list    — which columns to return (default: all)
+        """
+        norm_query = _normalize(query, arabic=self.normalize_arabic)
+        cols = columns or list(self._df.columns)
+
+        if self.name_aware:
+            # Manual scoring loop (rapidfuzz process doesn't support custom scorers easily)
+            scored = [
+                (i, self._score(norm_query, cand))
+                for i, cand in enumerate(self._normalized_choices)
+            ]
+            scored = [(i, s) for i, s in scored if s >= min_score]
+            scored.sort(key=lambda x: x[1], reverse=True)
+            scored = scored[:top_n]
+
+            results = []
+            for idx, score in scored:
+                row = self._df.iloc[idx][cols].to_dict()
+                row["score"] = round(score, 2)
+                row["_index"] = int(idx)
+                results.append(row)
+        else:
+            matches = process.extract(
+                norm_query,
+                self._normalized_choices,
+                scorer=self.scorer,
+                limit=top_n,
+                score_cutoff=min_score,
+            )
+            results = []
+            for _matched_str, score, idx in matches:
+                row = self._df.iloc[idx][cols].to_dict()
+                row["score"] = round(score, 2)
+                row["_index"] = int(idx)
+                results.append(row)
+            results.sort(key=lambda r: r["score"], reverse=True)
+
+        return results
+
+    def lookup_best(
+        self,
+        query: str,
+        min_score: float = 0.0,
+        columns: Optional[list[str]] = None,
+    ) -> Optional[dict[str, Any]]:
+        """Return only the single best match, or None if below min_score."""
+        results = self.lookup(query, top_n=1, min_score=min_score, columns=columns)
+        return results[0] if results else None
+
+    def lookup_many(
+        self,
+        queries: list[str],
+        top_n: int = 1,
+        min_score: float = 0.0,
+        columns: Optional[list[str]] = None,
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Batch lookup for multiple queries."""
+        return {
+            q: self.lookup(q, top_n=top_n, min_score=min_score, columns=columns)
+            for q in queries
+        }
+
+    # ------------------------------------------------------------------
+    # Convenience
+    # ------------------------------------------------------------------
+
+    @property
+    def columns(self) -> list[str]:
+        return list(self._df.columns)
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return self._df.shape
+
+    def __repr__(self) -> str:
+        mode = "name_aware" if self.name_aware else self.scorer.__name__
+        return (
+            f"FuzzyLookup(column='{self.column}', "
+            f"rows={self._df.shape[0]}, "
+            f"mode='{mode}')"
+        )

fuzzylookup-0.0.1/fuzzylookup/setup.py

@@ -0,0 +1,15 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="fuzzylookup",
+    version="0.1.0",
+    description="Fuzzy matching lookup for CSV/Excel datasets (Arabic + English)",
+    license="MIT",  
+    packages=find_packages(),
+    python_requires=">=3.8",
+    install_requires=[
+        "pandas>=1.3",
+        "openpyxl>=3.0",
+        "rapidfuzz>=3.0",
+    ],
+)

fuzzylookup-0.0.1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "Fuzzylookup"
+version = "0.0.1"
+description = "A package for Fuzzy Lookup"
+readme = "README.md"
+requires-python = ">=3.7"
+# إذا كان لديك مكتبات خارجية في ملف requirements.txt
+# ضعها هنا مثال: dependencies = ["pandas", "numpy"] 
+
+[project.urls]
+Homepage = "https://github.com/Moda141/Fuzzylookup"

fuzzylookup-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+