ocr-stringdist 0.0.3__cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl → 0.0.5__cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.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,7 @@ def weighted_levenshtein_distance(
     """
     if cost_map is None:
         cost_map = ocr_distance_map
-    return _weighted_levenshtein_distance(  # noqa: F405
+    # _weighted_levenshtein_distance is written in Rust, see src/rust_stringdist.rs.
+    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.5.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: ocr_stringdist
-Version: 0.0.3
+Version: 0.0.5
 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.
@@ -17,6 +17,8 @@ Project-URL: repository, https://github.com/NiklasvonM/ocr-stringdist
 
 A Python library for string distance calculations that account for common OCR (optical character recognition) errors.
 
+Documentation: https://niklasvonm.github.io/ocr-stringdist/
+
 [![PyPI](https://img.shields.io/badge/PyPI-Package-blue)](https://pypi.org/project/ocr-stringdist/)
 [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
 
@@ -35,11 +37,16 @@ pip install ocr-stringdist
 ## Features
 
 - **Weighted Levenshtein Distance**: An adaptation of the classic Levenshtein algorithm with custom substitution costs for character pairs that are commonly confused in OCR models.
+- **Unicode Support**: Arbitrary unicode strings can be compared.
+- **Substitution of Multiple Characters**: Not just character pairs, but string pairs may be substituted, for example the Korean syllable "이" for the two letters "OI".
 - **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).
 
 ## Usage
 
+### Weighted Levenshtein Distance
+
 ```python
 import ocr_stringdist as osd
 
@@ -48,16 +55,32 @@ distance = osd.weighted_levenshtein_distance("OCR5", "OCRS")
 print(f"Distance between 'OCR5' and 'OCRS': {distance}")  # Will be less than 1.0
 
 # Custom cost map
-custom_map = {("f", "t"): 0.2, ("m", "n"): 0.1}
+custom_map = {("In", "h"): 0.5}
 distance = osd.weighted_levenshtein_distance(
-    "first", "tirst",
+    "hi", "Ini",
     cost_map=custom_map,
     symmetric=True,
-    default_cost=1.0
+    default_cost=1.0,
 )
 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.5.dist-info/RECORD

@@ -0,0 +1,9 @@
+ocr_stringdist-0.0.5.dist-info/METADATA,sha256=vX4O04CresnzPoQnQSnejENFPcgSK5XWqRewrBvl9BU,3478
+ocr_stringdist-0.0.5.dist-info/WHEEL,sha256=txrf3mWfYT8fuidWcn4w4bCG5e7tCVvnYzYyHWO_WFg,129
+ocr_stringdist-0.0.5.dist-info/licenses/LICENSE,sha256=5BPRcjlnbl2t4TidSgpfGrtC_birSf8JlZfA-qmVoQE,1072
+ocr_stringdist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ocr_stringdist/__init__.py,sha256=zL-0Bmo6jCas2QlDCGxL2vPbjoNrdpLQ9kPfsAjC0QI,1515
+ocr_stringdist/default_ocr_distances.py,sha256=8jmR5aLrEfrm5Fj2-nEqdTCKEmoEcm8DxBWv7IQd5_k,887
+ocr_stringdist/matching.py,sha256=rr8R63Ttu2hTf5Mni7_P8aGBbjWs6t2QPV3wxKXspAs,3293
+ocr_stringdist/_rust_stringdist.cpython-310-arm-linux-gnueabihf.so,sha256=64cHzzTkkCjYrJpATtOb726gEygPdlGopd47mqiDxkc,581768
+ocr_stringdist-0.0.5.dist-info/RECORD,,

ocr_stringdist-0.0.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-ocr_stringdist-0.0.3.dist-info/METADATA,sha256=8zNTXdk7LHrW3hhpozRJoxUX_lFfUAwi04c3HajrDQ0,2427
-ocr_stringdist-0.0.3.dist-info/WHEEL,sha256=txrf3mWfYT8fuidWcn4w4bCG5e7tCVvnYzYyHWO_WFg,129
-ocr_stringdist-0.0.3.dist-info/licenses/LICENSE,sha256=5BPRcjlnbl2t4TidSgpfGrtC_birSf8JlZfA-qmVoQE,1072
-ocr_stringdist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ocr_stringdist/__init__.py,sha256=80efQ2jxe_BjTFQHbsPXYfpk5Cu6R9sOxrEY7tI8sGk,1347
-ocr_stringdist/default_ocr_distances.py,sha256=8jmR5aLrEfrm5Fj2-nEqdTCKEmoEcm8DxBWv7IQd5_k,887
-ocr_stringdist/_rust_stringdist.cpython-310-arm-linux-gnueabihf.so,sha256=1iq3f9YfiZzUkpqhaf8DWUXP0QXt4jYC9oEUNeLkveI,577264
-ocr_stringdist-0.0.3.dist-info/RECORD,,