ocr-stringdist 0.0.7__cp311-cp311-musllinux_1_1_aarch64.whl → 0.2.0__cp311-cp311-musllinux_1_1_aarch64.whl

ocr_stringdist/__init__.py

@@ -1,10 +1,17 @@
 from .default_ocr_distances import ocr_distance_map
-from .levenshtein import batch_weighted_levenshtein_distance, weighted_levenshtein_distance
+from .levenshtein import (
+    WeightedLevenshtein,
+    batch_weighted_levenshtein_distance,
+    explain_weighted_levenshtein,
+    weighted_levenshtein_distance,
+)
 from .matching import find_best_candidate
 
 __all__ = [
     "ocr_distance_map",
+    "WeightedLevenshtein",
     "weighted_levenshtein_distance",
     "batch_weighted_levenshtein_distance",
+    "explain_weighted_levenshtein",
     "find_best_candidate",
 ]

ocr_stringdist/levenshtein.py

@@ -1,71 +1,242 @@
-from typing import Optional
+from __future__ import annotations
 
-from ._rust_stringdist import *  # noqa: F403
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from ._rust_stringdist import (
+    _batch_weighted_levenshtein_distance,
+    _explain_weighted_levenshtein_distance,
+    _weighted_levenshtein_distance,
+)
 from .default_ocr_distances import ocr_distance_map
 
+OperationType = Literal["substitute", "insert", "delete"]
+
+
+@dataclass(frozen=True)
+class EditOperation:
+    """
+    Represents a single edit operation (substitution, insertion, or deletion).
+    """
+
+    op_type: OperationType
+    source_token: Optional[str]
+    target_token: Optional[str]
+    cost: float
+
+
+class WeightedLevenshtein:
+    """
+    Calculates Levenshtein distance with custom, configurable costs.
+
+    This class is initialized with cost dictionaries and settings that define
+    how the distance is measured. Once created, its methods can be used to
+    efficiently compute distances and explain the edit operations.
+
+    :param substitution_costs: Maps (char, char) tuples to their substitution cost.
+                               Defaults to costs based on common OCR errors.
+    :param insertion_costs: Maps a character to its insertion cost.
+    :param deletion_costs: Maps a character to its deletion cost.
+    :param symmetric_substitution: If True, substitution costs are bidirectional.
+    :param default_substitution_cost: Default cost for substitutions not in the map.
+    :param default_insertion_cost: Default cost for insertions not in the map.
+    :param default_deletion_cost: Default cost for deletions not in the map.
+    """
+
+    substitution_costs: dict[tuple[str, str], float]
+    insertion_costs: dict[str, float]
+    deletion_costs: dict[str, float]
+    symmetric_substitution: bool
+    default_substitution_cost: float
+    default_insertion_cost: float
+    default_deletion_cost: float
+
+    def __init__(
+        self,
+        substitution_costs: Optional[dict[tuple[str, str], float]] = None,
+        insertion_costs: Optional[dict[str, float]] = None,
+        deletion_costs: Optional[dict[str, float]] = None,
+        *,
+        symmetric_substitution: bool = True,
+        default_substitution_cost: float = 1.0,
+        default_insertion_cost: float = 1.0,
+        default_deletion_cost: float = 1.0,
+    ) -> None:
+        self.substitution_costs = (
+            ocr_distance_map if substitution_costs is None else substitution_costs
+        )
+        self.insertion_costs = {} if insertion_costs is None else insertion_costs
+        self.deletion_costs = {} if deletion_costs is None else deletion_costs
+        self.symmetric_substitution = symmetric_substitution
+        self.default_substitution_cost = default_substitution_cost
+        self.default_insertion_cost = default_insertion_cost
+        self.default_deletion_cost = default_deletion_cost
+
+    @classmethod
+    def unweighted(cls) -> WeightedLevenshtein:
+        """Creates an instance with all operations having equal cost of 1.0."""
+        return cls(substitution_costs={}, insertion_costs={}, deletion_costs={})
+
+    def distance(self, s1: str, s2: str) -> float:
+        """Calculates the weighted Levenshtein distance between two strings."""
+        return _weighted_levenshtein_distance(s1, s2, **self.__dict__)  # type: ignore[no-any-return]
+
+    def explain(self, s1: str, s2: str) -> list[EditOperation]:
+        """Returns the list of edit operations to transform s1 into s2."""
+        raw_path = _explain_weighted_levenshtein_distance(s1, s2, **self.__dict__)
+        return [EditOperation(*op) for op in raw_path]
+
+    def batch_distance(self, s: str, candidates: list[str]) -> list[float]:
+        """Calculates distances between a string and a list of candidates."""
+        return _batch_weighted_levenshtein_distance(s, candidates, **self.__dict__)  # type: ignore[no-any-return]
+
 
 def weighted_levenshtein_distance(
     s1: str,
     s2: str,
     /,
-    cost_map: Optional[dict[tuple[str, str], float]] = None,
+    substitution_costs: Optional[dict[tuple[str, str], float]] = None,
+    insertion_costs: Optional[dict[str, float]] = None,
+    deletion_costs: Optional[dict[str, float]] = None,
     *,
-    symmetric: bool = True,
-    default_cost: float = 1.0,
+    symmetric_substitution: bool = True,
+    default_substitution_cost: float = 1.0,
+    default_insertion_cost: float = 1.0,
+    default_deletion_cost: float = 1.0,
 ) -> float:
     """
-    Levenshtein distance with custom substitution costs.
-    Insertion/deletion costs are 1.
+    Levenshtein distance with custom substitution, insertion and deletion costs.
+
+    See also :meth:`WeightedLevenshtein.distance`.
 
-    The default `cost_map` considers common OCR errors, see
+    The default `substitution_costs` considers common OCR errors, see
     :py:data:`ocr_stringdist.default_ocr_distances.ocr_distance_map`.
 
-    :param s1: First string
+    :param s1: First string (interpreted as the string read via OCR)
     :param s2: Second string
-    :param cost_map: Dictionary mapping tuples of strings ("substitution tokens") to their
-                     substitution costs.
-                     Only one direction needs to be configured unless `symmetric` is False.
+    :param substitution_costs: Dictionary mapping tuples of strings ("substitution tokens") to their
+                     substitution costs. Only one direction needs to be configured unless
+                     `symmetric_substitution` is False.
                      Note that the runtime scales in the length of the longest substitution token.
                      Defaults to `ocr_stringdist.ocr_distance_map`.
-    :param symmetric: Should the keys of `cost_map` be considered to be symmetric? Defaults to True.
-    :param default_cost: The default substitution cost for character pairs not found in `cost_map`.
+    :param insertion_costs: Dictionary mapping strings to their insertion costs.
+    :param deletion_costs: Dictionary mapping strings to their deletion costs.
+    :param symmetric_substitution: Should the keys of `substitution_costs` be considered to be
+                                   symmetric? Defaults to True.
+    :param default_substitution_cost: The default substitution cost for character pairs not found
+                                      in `substitution_costs`.
+    :param default_insertion_cost: The default insertion cost for characters not found in
+                                   `insertion_costs`.
+    :param default_deletion_cost: The default deletion cost for characters not found in
+                                  `deletion_costs`.
     """
-    if cost_map is None:
-        cost_map = ocr_distance_map
-    # _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
-    )
+    return WeightedLevenshtein(
+        substitution_costs=substitution_costs,
+        insertion_costs=insertion_costs,
+        deletion_costs=deletion_costs,
+        symmetric_substitution=symmetric_substitution,
+        default_substitution_cost=default_substitution_cost,
+        default_insertion_cost=default_insertion_cost,
+        default_deletion_cost=default_deletion_cost,
+    ).distance(s1, s2)
 
 
 def batch_weighted_levenshtein_distance(
     s: str,
     candidates: list[str],
     /,
-    cost_map: Optional[dict[tuple[str, str], float]] = None,
+    substitution_costs: Optional[dict[tuple[str, str], float]] = None,
+    insertion_costs: Optional[dict[str, float]] = None,
+    deletion_costs: Optional[dict[str, float]] = None,
     *,
-    symmetric: bool = True,
-    default_cost: float = 1.0,
+    symmetric_substitution: bool = True,
+    default_substitution_cost: float = 1.0,
+    default_insertion_cost: float = 1.0,
+    default_deletion_cost: float = 1.0,
 ) -> list[float]:
     """
     Calculate weighted Levenshtein distances between a string and multiple candidates.
 
+    See also :meth:`WeightedLevenshtein.batch_distance`.
+
     This is more efficient than calling :func:`weighted_levenshtein_distance` multiple times.
 
-    :param s: The string to compare
+    :param s: The string to compare (interpreted as the string read via OCR)
     :param candidates: List of candidate strings to compare against
-    :param cost_map: Dictionary mapping tuples of strings ("substitution tokens") to their
-                     substitution costs.
-                     Only one direction needs to be configured unless `symmetric` is False.
+    :param substitution_costs: Dictionary mapping tuples of strings ("substitution tokens") to their
+                     substitution costs. Only one direction needs to be configured unless
+                     `symmetric_substitution` is False.
                      Note that the runtime scales in the length of the longest substitution token.
                      Defaults to `ocr_stringdist.ocr_distance_map`.
-    :param symmetric: Should the keys of `cost_map` be considered to be symmetric? Defaults to True.
-    :param default_cost: The default substitution cost for character pairs not found in `cost_map`.
+    :param insertion_costs: Dictionary mapping strings to their insertion costs.
+    :param deletion_costs: Dictionary mapping strings to their deletion costs.
+    :param symmetric_substitution: Should the keys of `substitution_costs` be considered to be
+                                   symmetric? Defaults to True.
+    :param default_substitution_cost: The default substitution cost for character pairs not found
+                                      in `substitution_costs`.
+    :param default_insertion_cost: The default insertion cost for characters not found in
+                                   `insertion_costs`.
+    :param default_deletion_cost: The default deletion cost for characters not found in
+                                  `deletion_costs`.
     :return: A list of distances corresponding to each candidate
     """
-    if cost_map is None:
-        cost_map = ocr_distance_map
-    # _batch_weighted_levenshtein_distance is written in Rust, see src/rust_stringdist.rs.
-    return _batch_weighted_levenshtein_distance(  # type: ignore  # noqa: F405
-        s, candidates, cost_map=cost_map, symmetric=symmetric, default_cost=default_cost
-    )
+    return WeightedLevenshtein(
+        substitution_costs=substitution_costs,
+        insertion_costs=insertion_costs,
+        deletion_costs=deletion_costs,
+        symmetric_substitution=symmetric_substitution,
+        default_substitution_cost=default_substitution_cost,
+        default_insertion_cost=default_insertion_cost,
+        default_deletion_cost=default_deletion_cost,
+    ).batch_distance(s, candidates)
+
+
+def explain_weighted_levenshtein(
+    s1: str,
+    s2: str,
+    /,
+    substitution_costs: Optional[dict[tuple[str, str], float]] = None,
+    insertion_costs: Optional[dict[str, float]] = None,
+    deletion_costs: Optional[dict[str, float]] = None,
+    *,
+    symmetric_substitution: bool = True,
+    default_substitution_cost: float = 1.0,
+    default_insertion_cost: float = 1.0,
+    default_deletion_cost: float = 1.0,
+) -> list[EditOperation]:
+    """
+    Computes the path of operations associated with the custom Levenshtein distance.
+
+    See also :meth:`WeightedLevenshtein.explain`.
+
+    The default `substitution_costs` considers common OCR errors, see
+    :py:data:`ocr_stringdist.default_ocr_distances.ocr_distance_map`.
+
+    :param s1: First string (interpreted as the string read via OCR)
+    :param s2: Second string
+    :param substitution_costs: Dictionary mapping tuples of strings ("substitution tokens") to their
+                     substitution costs. Only one direction needs to be configured unless
+                     `symmetric_substitution` is False.
+                     Note that the runtime scales in the length of the longest substitution token.
+                     Defaults to `ocr_stringdist.ocr_distance_map`.
+    :param insertion_costs: Dictionary mapping strings to their insertion costs.
+    :param deletion_costs: Dictionary mapping strings to their deletion costs.
+    :param symmetric_substitution: Should the keys of `substitution_costs` be considered to be
+                                   symmetric? Defaults to True.
+    :param default_substitution_cost: The default substitution cost for character pairs not found
+                                      in `substitution_costs`.
+    :param default_insertion_cost: The default insertion cost for characters not found in
+                                   `insertion_costs`.
+    :param default_deletion_cost: The default deletion cost for characters not found in
+                                  `deletion_costs`.
+    :return: List of :class:`EditOperation` instances.
+    """
+    return WeightedLevenshtein(
+        substitution_costs=substitution_costs,
+        insertion_costs=insertion_costs,
+        deletion_costs=deletion_costs,
+        symmetric_substitution=symmetric_substitution,
+        default_substitution_cost=default_substitution_cost,
+        default_insertion_cost=default_insertion_cost,
+        default_deletion_cost=default_deletion_cost,
+    ).explain(s1, s2)

ocr_stringdist-0.2.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: ocr_stringdist
+Version: 0.2.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Requires-Python: >=3.9
+Project-URL: repository, https://github.com/NiklasvonM/ocr-stringdist

ocr_stringdist-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ocr_stringdist-0.2.0.dist-info/METADATA,sha256=OVF3jUKVM038ogWfwZIHmpu3eUXdeuS1Cy-t96G8Tgo,304
+ocr_stringdist-0.2.0.dist-info/WHEEL,sha256=YZ-7NO8DvWz9hvgmCkZeUq1zdF91KUkb-9x6mgD1Qlg,108
+ocr_stringdist-0.2.0.dist-info/licenses/LICENSE,sha256=5BPRcjlnbl2t4TidSgpfGrtC_birSf8JlZfA-qmVoQE,1072
+ocr_stringdist.libs/libgcc_s-e52197c3.so.1,sha256=vkPW1Auw6CH9Bjk7frmX3hry_1H9c0tRI0Ncyg71WUI,724137
+ocr_stringdist/__init__.py,sha256=ApxqraLRcWAkzXhGJXSf3EqGEVFbxghrYrfJ9dmQjQU,467
+ocr_stringdist/_rust_stringdist.cpython-311-aarch64-linux-musl.so,sha256=IQyxOxiF8SXAyxpLrbtWSPNjKTyQ4r3KmlthYLqXnwU,920193
+ocr_stringdist/default_ocr_distances.py,sha256=oSu-TpHjPA4jxKpLAfmap8z0ZsC99jsOjnRVHW7Hj_Y,1033
+ocr_stringdist/levenshtein.py,sha256=Jypg31BQyULipJ_Yh3dcBQDKNnbvEIlmf28tDr_gySw,11243
+ocr_stringdist/matching.py,sha256=rr8R63Ttu2hTf5Mni7_P8aGBbjWs6t2QPV3wxKXspAs,3293
+ocr_stringdist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ocr_stringdist-0.2.0.dist-info/RECORD,,

{ocr_stringdist-0.0.7.dist-info → ocr_stringdist-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.8.3)
+Generator: maturin (1.9.4)
 Root-Is-Purelib: false
 Tag: cp311-cp311-musllinux_1_1_aarch64

ocr_stringdist-0.0.7.dist-info/METADATA

@@ -1,86 +0,0 @@
-Metadata-Version: 2.4
-Name: ocr_stringdist
-Version: 0.0.7
-Classifier: Programming Language :: Rust
-Classifier: Programming Language :: Python
-Classifier: Operating System :: OS Independent
-License-File: LICENSE
-Summary: String distances considering OCR errors.
-Author: Niklas von Moers <niklasvmoers@protonmail.com>
-Author-email: Niklas von Moers <niklasvmoers@protonmail.com>
-License: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: repository, https://github.com/NiklasvonM/ocr-stringdist
-
-# 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)
-
-## Overview
-
-OCR-StringDist provides specialized string distance algorithms that accommodate for optical character recognition (OCR) errors. Unlike traditional string comparison algorithms, OCR-StringDist considers common OCR confusions (like "0" vs "O", "6" vs "G", etc.) when calculating distances between strings.
-
-> **Note:** This project is in early development. APIs may change in future releases.
-
-## Installation
-
-```bash
-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, including efficient batch processing.
-- **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
-
-# Using default OCR distance map
-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 = {("In", "h"): 0.5}
-distance = osd.weighted_levenshtein_distance(
-    "hi", "Ini",
-    cost_map=custom_map,
-    symmetric=True,
-)
-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.7.dist-info/RECORD

@@ -1,11 +0,0 @@
-ocr_stringdist-0.0.7.dist-info/METADATA,sha256=Rx1RtodaH76hveE0246t_Lo-lID1h6rI_j47joUb6Ak,3494
-ocr_stringdist-0.0.7.dist-info/WHEEL,sha256=_6kdhUAwdXFNoVDlhgbbljfv0z-zRN2adeNGPnKJZD8,108
-ocr_stringdist-0.0.7.dist-info/licenses/LICENSE,sha256=5BPRcjlnbl2t4TidSgpfGrtC_birSf8JlZfA-qmVoQE,1072
-ocr_stringdist.libs/libgcc_s-e52197c3.so.1,sha256=vkPW1Auw6CH9Bjk7frmX3hry_1H9c0tRI0Ncyg71WUI,724137
-ocr_stringdist/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ocr_stringdist/__init__.py,sha256=haj_CNOovN9O6j1ixmku6BNTV4U3NQ5JEN2dC_4TmXc,332
-ocr_stringdist/default_ocr_distances.py,sha256=oSu-TpHjPA4jxKpLAfmap8z0ZsC99jsOjnRVHW7Hj_Y,1033
-ocr_stringdist/matching.py,sha256=rr8R63Ttu2hTf5Mni7_P8aGBbjWs6t2QPV3wxKXspAs,3293
-ocr_stringdist/levenshtein.py,sha256=kJBJM5sG_g4MBXizbYVsGMQPWHk2vXWOvMspCYnthCA,3053
-ocr_stringdist/_rust_stringdist.cpython-311-aarch64-linux-musl.so,sha256=5lSxG3u28KJNdAU-apGJXOuSeASuUYqb5tQBe4g_rHA,854657
-ocr_stringdist-0.0.7.dist-info/RECORD,,