ocr-stringdist 0.0.3__cp39-cp39-win32.whl → 0.0.4__cp39-cp39-win32.whl

ocr_stringdist/__init__.py

@@ -1,13 +1,13 @@
 from typing import Optional
 
 from ._rust_stringdist import *  # noqa: F403
-
 from .default_ocr_distances import ocr_distance_map
-
+from .matching import find_best_candidate
 
 __all__ = [
     "ocr_distance_map",
     "weighted_levenshtein_distance",  # noqa: F405
+    "find_best_candidate",
 ]
 
 
@@ -36,6 +36,6 @@ def weighted_levenshtein_distance(
     """
     if cost_map is None:
         cost_map = ocr_distance_map
-    return _weighted_levenshtein_distance(  # noqa: F405
+    return _weighted_levenshtein_distance(  # type: ignore  # noqa: F405
         s1, s2, cost_map=cost_map, symmetric=symmetric, default_cost=default_cost
     )

ocr_stringdist/matching.py

@@ -0,0 +1,83 @@
+from collections.abc import Callable, Iterable
+from typing import Optional
+
+
+def find_best_candidate(
+    s: str,
+    candidates: Iterable[str],
+    distance_fun: Callable[[str, str], float],
+    *,
+    minimize: bool = True,
+    early_return_value: Optional[float] = None,
+) -> tuple[str, float]:
+    """
+    Finds the best matching string from a collection of candidates based on a distance function.
+
+    Compares a given string against each string in the 'candidates'
+    iterable using the provided 'distance_fun'. It identifies the candidate
+    that yields the minimum (or maximum, if minimize=False) distance.
+
+    :param s: The reference string to compare against.
+    :type s: str
+    :param candidates: An iterable of candidate strings to compare with 's'.
+    :type candidates: Iterable[str]
+    :param distance_fun: A function that takes two strings (s, candidate) and
+                         returns a float representing their distance or similarity.
+    :type distance_fun: Callable[[str, str], float]
+    :param minimize: If True (default), finds the candidate with the minimum
+                     distance. If False, finds the candidate with the maximum
+                     distance (useful for similarity scores).
+    :type minimize: bool
+    :param early_return_value: If provided, the function will return immediately
+                               if a distance is found that is less than or equal
+                               to this value (if minimize=True) or greater than
+                               or equal to this value (if minimize=False).
+                               If None (default), all candidates are checked.
+    :type early_return_value: Optional[float]
+    :raises ValueError: If the 'candidates' iterable is empty.
+    :return: A tuple containing the best matching candidate string and its
+             calculated distance/score.
+    :rtype: tuple[str, float]
+
+    :Example:
+
+    >>> from ocr_stringdist import weighted_levenshtein_distance as distance
+    >>> s = "apple"
+    >>> candidates = ["apply", "apples", "orange", "appIe"]
+    >>> find_best_match(s, candidates, lambda s1, s2: distance(s1, s2, {("l", "I"): 0.1}))
+    ('appIe', 0.1)
+    """
+    if not candidates:
+        raise ValueError("The 'candidates' iterable cannot be empty.")
+
+    best_candidate: str = ""
+
+    if minimize:
+        best_distance = float("inf")
+
+        def is_next_best(current: float, best: float) -> bool:
+            return current < best
+
+        def can_return_early(current: float, threshold: float) -> bool:
+            return current <= threshold
+    else:
+        best_distance = -float("inf")
+
+        def is_next_best(current: float, best: float) -> bool:
+            return current > best
+
+        def can_return_early(current: float, threshold: float) -> bool:
+            return current >= threshold
+
+    for candidate in candidates:
+        current_distance = distance_fun(s, candidate)
+
+        if early_return_value is not None and can_return_early(
+            current_distance, early_return_value
+        ):
+            return candidate, current_distance
+        if is_next_best(current_distance, best_distance):
+            best_distance = current_distance
+            best_candidate = candidate
+
+    return best_candidate, best_distance

{ocr_stringdist-0.0.3.dist-info → ocr_stringdist-0.0.4.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: ocr_stringdist
-Version: 0.0.3
+Version: 0.0.4
 Classifier: Programming Language :: Rust
-Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Python
 Classifier: Operating System :: OS Independent
 License-File: LICENSE
 Summary: String distances considering OCR errors.
@@ -37,9 +37,12 @@ pip install ocr-stringdist
 - **Weighted Levenshtein Distance**: An adaptation of the classic Levenshtein algorithm with custom substitution costs for character pairs that are commonly confused in OCR models.
 - **Pre-defined OCR Distance Map**: A built-in distance map for common OCR confusions (e.g., "0" vs "O", "1" vs "l", "5" vs "S").
 - **Customizable Cost Maps**: Create your own substitution cost maps for specific OCR systems or domains.
+- **Best Match Finder**: Utility function find_best_candidate to efficiently find the best matching string from a collection of candidates using any specified distance function (including the library's OCR-aware ones). Supports early stopping for performance optimization.
 
 ## Usage
 
+### Weighted Levenshtein Distance
+
 ```python
 import ocr_stringdist as osd
 
@@ -58,6 +61,22 @@ distance = osd.weighted_levenshtein_distance(
 print(f"Distance with custom map: {distance}")
 ```
 
+### Finding the Best Candidate
+
+```python
+import ocr_stringdist as osd
+
+s = "apple"
+candidates = ["apply", "apples", "orange", "appIe"]  # 'appIe' has an OCR-like error
+
+def ocr_aware_distance(s1: str, s2: str) -> float:
+    return osd.weighted_levenshtein_distance(s1, s2, cost_map={("l", "I"): 0.1})
+
+best_candidate, best_dist = osd.find_best_candidate(s, candidates, ocr_aware_distance)
+print(f"Best candidate for '{s}' is '{best_candidate}' with distance {best_dist}")
+# Output: Best candidate for 'apple' is 'appIe' with distance 0.1
+```
+
 ## Acknowledgements
 
 This project is inspired by [jellyfish](https://github.com/jamesturk/jellyfish), providing the base implementations of the algorithms used here.

ocr_stringdist-0.0.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+ocr_stringdist-0.0.4.dist-info/METADATA,sha256=1lSh8HZ9TrBv0BWdBbMZk-_0qbE1tEEUd25xfAFnd7s,3320
+ocr_stringdist-0.0.4.dist-info/WHEEL,sha256=0Nk1AmIV1z6U4gJsrIxrgrzvCxDT7puUGM_j24me7T0,90
+ocr_stringdist-0.0.4.dist-info/licenses/LICENSE,sha256=3cNRiJag5vI0KMMDNf0oiaY4vg43rLxRszbMJs1GBoU,1092
+ocr_stringdist/default_ocr_distances.py,sha256=STNRMGWEYOCHo11uP51JUQfvNrSZleMCxt6wsPkctfg,925
+ocr_stringdist/matching.py,sha256=KEzYBBEHZhfLA9eD3MxDaehKiD9lUb0RQq74u5qWpVw,3376
+ocr_stringdist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ocr_stringdist/__init__.py,sha256=Z6ZeTSfpKRaUM15FPW00MfLBKVDUCP21Xh5VLtnC4Tk,1471
+ocr_stringdist/_rust_stringdist.cp39-win32.pyd,sha256=PWbzLvhNtGpBERO5T54Ug7MZGeKOERhBUu2xRxp1Rdg,204800
+ocr_stringdist-0.0.4.dist-info/RECORD,,

ocr_stringdist-0.0.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-ocr_stringdist-0.0.3.dist-info/METADATA,sha256=xoqr4v-Rf9nommTK1eLLOCj2YPuubbCq4aW2FBhDsYc,2475
-ocr_stringdist-0.0.3.dist-info/WHEEL,sha256=0Nk1AmIV1z6U4gJsrIxrgrzvCxDT7puUGM_j24me7T0,90
-ocr_stringdist-0.0.3.dist-info/licenses/LICENSE,sha256=3cNRiJag5vI0KMMDNf0oiaY4vg43rLxRszbMJs1GBoU,1092
-ocr_stringdist/default_ocr_distances.py,sha256=STNRMGWEYOCHo11uP51JUQfvNrSZleMCxt6wsPkctfg,925
-ocr_stringdist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ocr_stringdist/__init__.py,sha256=9u9MIGHrywSF0aC0ZW9RJiJJEB-EVbl74O9eGvzlELQ,1388
-ocr_stringdist/_rust_stringdist.cp39-win32.pyd,sha256=jLq3GpQGiFDUOYnwN0Gwmo_dYyf8Wh_brHbgtPf73Gw,204800
-ocr_stringdist-0.0.3.dist-info/RECORD,,