ocr-stringdist 0.1.0__tar.gz → 0.2.0__tar.gz

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-08-31
+
+### Added
+
+- `WeightedLevenshtein` class for reusable configuration.
+- Explanation of edit operations via `WeightedLevenshtein.explain` and `explain_weighted_levenshtein`.
+
 ## [0.1.0] - 2025-04-26
 
 ### Added

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/Cargo.lock

@@ -74,7 +74,7 @@ dependencies = [
 
 [[package]]
 name = "ocr_stringdist"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "pyo3",
  "rayon",

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ocr_stringdist"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 description = "String distances considering OCR errors."
 authors = ["Niklas von Moers <niklasvmoers@protonmail.com>"]

ocr_stringdist-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,69 @@
+# OCR-StringDist
+
+A Python library for fast 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
+
+Standard string distances (like Levenshtein) treat all character substitutions equally. This is suboptimal for text read from images via OCR, where errors like `O` vs `0` are far more common than, say, `O` vs `X`.
+
+OCR-StringDist uses a **weighted Levenshtein distance**, assigning lower costs to common OCR errors.
+
+**Example:** Matching against the correct word `CODE`:
+
+* **Standard Levenshtein:**
+    * $d(\text{"CODE"}, \text{"C0DE"}) = 1$ (O → 0)
+    * $d(\text{"CODE"}, \text{"CXDE"}) = 1$ (O → X)
+    * Result: Both appear equally likely/distant.
+
+* **OCR-StringDist (Weighted):**
+    * $d(\text{"CODE"}, \text{"C0DE"}) \approx 0.1$ (common error, low cost)
+    * $d(\text{"CODE"}, \text{"CXDE"}) = 1.0$ (unlikely error, high cost)
+    * Result: Correctly identifies `C0DE` as a much closer match.
+
+This makes it ideal for matching potentially incorrect OCR output against known values (e.g., product codes, database entries).
+
+> **Note:** This project is in early development. APIs may change in future releases.
+
+## Installation
+
+```bash
+pip install ocr-stringdist
+```
+
+## Features
+
+- **Weighted Levenshtein Distance**: Calculates Levenshtein distance with customizable costs for substitutions, insertions, and deletions. Includes an efficient batch version (`batch_weighted_levenshtein_distance`) for comparing one string against many candidates.
+- **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").
+- **Unicode Support**: Works with arbitrary Unicode strings.
+- **Best Match Finder**: Includes a utility function `find_best_candidate` to efficiently find the best match from a list based on _any_ distance function.
+
+## 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
+substitution_costs = {("In", "h"): 0.5}
+distance = osd.weighted_levenshtein_distance(
+    "hi", "Ini",
+    substitution_costs=substitution_costs,
+    symmetric_substitution=True,
+)
+print(f"Distance with custom map: {distance}")
+```
+
+## Acknowledgements
+
+This project is inspired by [jellyfish](https://github.com/jamesturk/jellyfish), providing the base implementations of the algorithms used here.

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/docs/source/api/index.rst

@@ -3,10 +3,12 @@
 API Reference
 =============
 
-.. automodule:: ocr_stringdist.levenshtein
+.. autoclass:: ocr_stringdist.WeightedLevenshtein
    :members:
-   :undoc-members:
-   :show-inheritance:
+
+.. autofunction:: ocr_stringdist.weighted_levenshtein_distance
+.. autofunction:: ocr_stringdist.batch_weighted_levenshtein_distance
+.. autofunction:: ocr_stringdist.explain_weighted_levenshtein
 
 .. automodule:: ocr_stringdist.matching
    :members:

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/docs/source/conf.py

@@ -30,6 +30,7 @@ extensions: list[str] = [
     "sphinx.ext.intersphinx",  # Link to other projects' documentation
     "sphinx.ext.viewcode",  # Add links to source code
     "sphinx_mdinclude",  # Include Markdown
+    "sphinx_copybutton",  # Add "copy" button to code blocks
 ]
 
 templates_path = ["_templates"]

ocr_stringdist-0.2.0/docs/source/examples.rst

@@ -0,0 +1,98 @@
+================
+ Usage Examples
+================
+
+Basic Distance Calculation
+==========================
+
+Using the default pre-defined map for common OCR errors:
+
+.. code-block:: python
+
+    import ocr_stringdist as osd
+
+    # Compare "OCR5" and "OCRS"
+    # The default ocr_distance_map gives 'S' <-> '5' a cost of 0.3
+    distance = osd.weighted_levenshtein_distance("OCR5", "OCRS")
+    print(f"Distance between 'OCR5' and 'OCRS' (default map): {distance}")
+    # Output: Distance between 'OCR5' and 'OCRS' (default map): 0.3
+
+Using Custom Costs
+==================
+
+Define your own substitution costs:
+
+.. code-block:: python
+
+    from ocr_stringdist import WeightedLevenshtein
+
+    # Define a custom cost for substituting "rn" with "m"
+    wl = WeightedLevenshtein(substitution_costs={("rn", "m"): 0.5})
+
+    distance = wl.distance("Churn Bucket", "Chum Bucket")
+    print(f"Distance using custom map: {distance}") # 0.5
+
+
+Matching OCR Output Against Candidates
+======================================
+
+This is a primary use case: finding the best match for an OCR string from a list of known possibilities.
+
+.. code-block:: python
+
+    import ocr_stringdist as osd
+
+    ocr_output = "Harnburg"  # OCR potentially misread 'm' as 'rn'
+    possible_cities = ["Harburg", "Hamburg", "Hannover", "Berlin"]
+
+    # Define costs relevant to the potential error
+    wl = osd.WeightedLevenshtein(substitution_costs={("rn", "m"): 0.2})
+
+    # Method 1: Using find_best_candidate
+    best_match_finder, min_distance_finder = osd.find_best_candidate(
+        ocr_output,
+        possible_cities,
+        distance_fun=wl.distance,
+    )
+    print(
+        f"(find_best_candidate) Best match for '{ocr_output}': '{best_match_finder}' "
+        f"(Distance: {min_distance_finder:.2f})"
+    )
+    # Output: (find_best_candidate) Best match for 'Harnburg': 'Hamburg' (Distance: 0.20)
+
+
+    # Method 2: Using WeightedLevenshtein.batch_distance
+    # Generally more efficient when comparing against many candidates.
+    distances = wl.batch_distance(ocr_output, possible_cities)
+
+    min_dist_batch = min(distances)
+    best_candidate_batch = possible_cities[distances.index(min_dist_batch)]
+
+    print(
+        f"(Batch) Best match for '{ocr_output}': '{best_candidate_batch}' "
+        f"(Distance: {min_dist_batch:.2f})"
+    )
+    # Output: (Batch) Best match for 'Harnburg': 'Hamburg' (Distance: 0.20)
+
+Explaining Edit Operations
+==========================
+
+You can get a detailed list of edit operations needed to transform one string into another.
+
+.. code-block:: python
+
+    from ocr_stringdist import WeightedLevenshtein
+
+    wl = WeightedLevenshtein(substitution_costs={("日月", "明"): 0.4, ("末", "未"): 0.3})
+
+    s1 = "末日月"  # mò rì yuè
+    s2 = "未明"  # wèi míng
+
+    operations = wl.explain(s1, s2)
+    print(operations)
+
+    # Output:
+    # [
+    #   EditOperation(op_type='substitute', source_token='末', target_token='未', cost=0.3),
+    #   EditOperation(op_type='substitute', source_token='日月', target_token='明', cost=0.4)
+    # ]

ocr_stringdist-0.2.0/docs/source/getting-started.rst

@@ -0,0 +1,27 @@
+=================
+ Getting Started
+=================
+
+Installation
+============
+
+.. code-block:: console
+
+    pip install ocr-stringdist
+
+Quick Example
+=============
+
+After installation, you can quickly calculate an OCR-aware string distance:
+
+.. code-block:: python
+
+    import ocr_stringdist as osd
+
+    # Calculate distance using the default OCR error costs
+    # ("O" vs "0" has a low cost)
+    distance = osd.weighted_levenshtein_distance("HELLO", "HELL0")
+
+    print(f"The OCR-aware distance is: {distance}")
+
+This uses the built-in :data:`ocr_distance_map` which assigns lower costs to common OCR character confusions. See the :doc:`examples` and :doc:`api/index` for more details and customization options.

ocr_stringdist-0.2.0/docs/source/index.rst

@@ -0,0 +1,57 @@
+================
+ OCR-StringDist
+================
+
+A Python library for fast string distance calculations that account for common OCR (optical character recognition) errors.
+
+:Repository: https://niklasvonm.github.io/ocr-stringdist/
+:Current version: |release|
+
+.. image:: https://img.shields.io/badge/PyPI-Package-blue
+   :target: https://pypi.org/project/ocr-stringdist/
+   :alt: PyPI
+
+.. image:: https://img.shields.io/badge/License-MIT-green
+   :target: LICENSE
+   :alt: License
+
+Motivation
+==========
+
+Standard string distances (like Levenshtein) treat all character substitutions equally. This is suboptimal for text read from images via OCR, where errors like `O` vs `0` are far more common than, say, `O` vs `X`.
+
+OCR-StringDist uses a **weighted Levenshtein distance**, assigning lower costs to common OCR errors.
+
+**Example:** Matching against the correct word `CODE`:
+
+* **Standard Levenshtein:**
+    * :math:`d(\text{"C0DE"}, \text{"CODE"}) = 1` (0 → O)
+    * :math:`d(\text{"CXDE"}, \text{"CODE"}) = 1` (X → O)
+    * Result: Both appear equally likely/distant.
+
+* **OCR-StringDist (Weighted):**
+    * :math:`d(\text{"C0DE"}, \text{"CODE"}) \approx 0.1` (common error, low cost)
+    * :math:`d(\text{"CXDE"}, \text{"CODE"}) = 1.0` (unlikely error, high cost)
+    * Result: Correctly identifies `C0DE` as a much closer match.
+
+This makes it ideal for matching potentially incorrect OCR output against known values (e.g., product codes, database entries).
+
+Features
+========
+
+- **Weighted Levenshtein Distance**: Calculates Levenshtein distance with customizable costs for substitutions, insertions, and deletions. Includes an efficient batch version (`batch_weighted_levenshtein_distance`) for comparing one string against many candidates.
+- **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").
+- **Unicode Support**: Works with arbitrary Unicode strings.
+- **Best Match Finder**: Includes a utility function `find_best_candidate` to efficiently find the best match from a list based on _any_ distance function.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   getting-started
+   examples
+   api/index
+   changelog

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/examples/batch_processing.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Example demonstrating the usage of the batch processing functions from ocr_stringdist.
+Example demonstrating the usage of the batch processing functions.
 """
 
 import time
@@ -28,9 +28,11 @@ def compare_methods() -> None:
     print("\nSingle string against multiple candidates:")
     print("-" * 50)
 
+    weighted_levenshtein = osd.WeightedLevenshtein()
+
     # Standard loop approach
     _, time_loop = benchmark(
-        lambda: [osd.weighted_levenshtein_distance(source, cand) for cand in candidates]
+        lambda: [weighted_levenshtein.distance(source, cand) for cand in candidates]
     )
     print(
         f"Loop of single calls: {time_loop:.6f} seconds "
@@ -38,7 +40,7 @@ def compare_methods() -> None:
     )
 
     # Batch approach
-    _, time_batch = benchmark(osd.batch_weighted_levenshtein_distance, source, candidates)
+    _, time_batch = benchmark(weighted_levenshtein.batch_distance, source, candidates)
     print(
         f"Batch function: {time_batch:.6f} seconds "
         f"({1000 * time_batch / len(candidates):.6f}ms each)"
@@ -47,7 +49,6 @@ def compare_methods() -> None:
 
 
 def main() -> None:
-    """Main function."""
     print("Demonstrating batch processing functions from ocr_stringdist\n")
 
     # Run the benchmarks

ocr_stringdist-0.2.0/examples/explain_distance.py

@@ -0,0 +1,23 @@
+from ocr_stringdist import explain_weighted_levenshtein
+
+print(
+    explain_weighted_levenshtein(
+        "Churn Buckets",
+        "Chum Bucket",
+        substitution_costs={("rn", "m"): 0.5},
+    )
+)
+# [
+#   EditOperation(
+#       op_type='substitute',
+#       source_token='rn',
+#       target_token='m',
+#       cost=0.5
+#   ),
+#   EditOperation(
+#       op_type='delete',
+#       source_token='s',
+#       target_token=None,
+#       cost=1.0
+#   ),
+# ]

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/pyproject.toml

@@ -33,6 +33,7 @@ dev = [
 ]
 docs = [
     "sphinx>=7.4.7",
+    "sphinx-copybutton>=0.5.2",
     "sphinx-mdinclude>=0.6.2",
     "sphinx-rtd-theme>=3.0.2",
 ]

{ocr_stringdist-0.1.0 → ocr_stringdist-0.2.0}/python/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-0.2.0/python/ocr_stringdist/levenshtein.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+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,
+    /,
+    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,
+) -> float:
+    """
+    Levenshtein distance with custom substitution, insertion and deletion costs.
+
+    See also :meth:`WeightedLevenshtein.distance`.
+
+    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 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],
+    /,
+    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[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 (interpreted as the string read via OCR)
+    :param candidates: List of candidate strings to compare against
+    :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: A list of distances corresponding to each candidate
+    """
+    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.1.0 → ocr_stringdist-0.2.0}/ruff.toml

@@ -51,7 +51,9 @@ select = [
     # refurb
     "FURB",
 ]
-ignore = []
+ignore = [
+    "UP007", # Allow Option[T] for older Python versions.
+]
 
 # Allow fix for all enabled rules (when `--fix`) is provided.
 fixable = ["ALL"]