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

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

@@ -5,6 +5,18 @@ 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.2] - 2025-09-01
+
+### Changed
+
+- Improve documentation.
+
+## [0.2.1] - 2025-08-31
+
+### Fixed
+
+- Documentation for PyPI
+
 ## [0.2.0] - 2025-08-31
 
 ### Added

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

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

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

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

{ocr_stringdist-0.2.0 → ocr_stringdist-0.2.2}/Justfile

@@ -1,7 +1,7 @@
 venv:
     rm -rf .venv
     uv venv
-    uv sync
+    uv sync --all-groups
 
 pytest:
     uv run maturin develop

ocr_stringdist-0.2.2/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: ocr-stringdist
+Version: 0.2.2
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: repository, https://github.com/NiklasvonM/ocr-stringdist
+Project-URL: documentation, https://niklasvonm.github.io/ocr-stringdist/
+
+# 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).
+
+## Installation
+
+```bash
+pip install ocr-stringdist
+```
+
+## Features
+
+- **High Performance**: The core logic is implemented in Rust with speed in mind.
+- **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.
+- **Explainable Edit Path**: Returns the optimal sequence of edit operations (substitutions, insertions, and deletions) used to transform one string into another.
+- **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
+
+### Basic usage
+
+```python
+from ocr_stringdist import WeightedLevenshtein
+
+# Default substitution costs are ocr_stringdist.ocr_distance_map.
+wl = WeightedLevenshtein()
+
+print(wl.distance("CXDE", "CODE")) # == 1
+print(wl.distance("C0DE", "CODE")) # < 1
+```
+
+### Explain the Edit Path
+
+```python
+edit_path = wl.explain("C0DE", "CODE")
+print(edit_path)
+# EditOperation(op_type='substitute', source_token='0', target_token='O', cost=0.1)]
+```
+
+### Fast Batch Calculations
+
+Quickly compare a string to a list of candidates.
+
+```python
+distances: list[float] = wl.batch_distance("CODE", ["CXDE", "C0DE"])
+# [1.0, 0.1]
+```
+
+### Multi-character Substitutions
+
+```python
+# Custom costs with multi-character substitution
+wl = WeightedLevenshtein(substitution_costs={("In", "h"): 0.5})
+
+print(wl.distance("hi", "Ini")) # 0.5
+```
+
+
+## Acknowledgements
+
+This project is inspired by [jellyfish](https://github.com/jamesturk/jellyfish), providing the base implementations of the algorithms used here.
+

{ocr_stringdist-0.2.0 → ocr_stringdist-0.2.2}/README.md

@@ -27,8 +27,6 @@ OCR-StringDist uses a **weighted Levenshtein distance**, assigning lower costs t
 
 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
@@ -37,7 +35,9 @@ pip install ocr-stringdist
 
 ## Features
 
+- **High Performance**: The core logic is implemented in Rust with speed in mind.
 - **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.
+- **Explainable Edit Path**: Returns the optimal sequence of edit operations (substitutions, insertions, and deletions) used to transform one string into another.
 - **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.
@@ -45,25 +45,45 @@ pip install ocr-stringdist
 
 ## Usage
 
-### Weighted Levenshtein Distance
+### Basic usage
+
+```python
+from ocr_stringdist import WeightedLevenshtein
+
+# Default substitution costs are ocr_stringdist.ocr_distance_map.
+wl = WeightedLevenshtein()
+
+print(wl.distance("CXDE", "CODE")) # == 1
+print(wl.distance("C0DE", "CODE")) # < 1
+```
+
+### Explain the Edit Path
+
+```python
+edit_path = wl.explain("C0DE", "CODE")
+print(edit_path)
+# EditOperation(op_type='substitute', source_token='0', target_token='O', cost=0.1)]
+```
+
+### Fast Batch Calculations
+
+Quickly compare a string to a list of candidates.
 
 ```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}")
+distances: list[float] = wl.batch_distance("CODE", ["CXDE", "C0DE"])
+# [1.0, 0.1]
 ```
 
+### Multi-character Substitutions
+
+```python
+# Custom costs with multi-character substitution
+wl = WeightedLevenshtein(substitution_costs={("In", "h"): 0.5})
+
+print(wl.distance("hi", "Ini")) # 0.5
+```
+
+
 ## Acknowledgements
 
 This project is inspired by [jellyfish](https://github.com/jamesturk/jellyfish), providing the base implementations of the algorithms used here.

{ocr_stringdist-0.2.0 → ocr_stringdist-0.2.2}/docs/source/examples.rst

@@ -9,11 +9,11 @@ Using the default pre-defined map for common OCR errors:
 
 .. code-block:: python
 
-    import ocr_stringdist as osd
+    from ocr_stringdist import WeightedLevenshtein
 
     # Compare "OCR5" and "OCRS"
     # The default ocr_distance_map gives 'S' <-> '5' a cost of 0.3
-    distance = osd.weighted_levenshtein_distance("OCR5", "OCRS")
+    distance: float = WeightedLevenshtein().distance("OCR5", "OCRS")
     print(f"Distance between 'OCR5' and 'OCRS' (default map): {distance}")
     # Output: Distance between 'OCR5' and 'OCRS' (default map): 0.3
 
@@ -63,7 +63,7 @@ This is a primary use case: finding the best match for an OCR string from a list
 
     # Method 2: Using WeightedLevenshtein.batch_distance
     # Generally more efficient when comparing against many candidates.
-    distances = wl.batch_distance(ocr_output, possible_cities)
+    distances: list[float] = wl.batch_distance(ocr_output, possible_cities)
 
     min_dist_batch = min(distances)
     best_candidate_batch = possible_cities[distances.index(min_dist_batch)]

{ocr_stringdist-0.2.0 → ocr_stringdist-0.2.2}/docs/source/getting-started.rst

@@ -16,11 +16,11 @@ After installation, you can quickly calculate an OCR-aware string distance:
 
 .. code-block:: python
 
-    import ocr_stringdist as osd
+    from ocr_stringdist import WeightedLevenshtein
 
     # Calculate distance using the default OCR error costs
     # ("O" vs "0" has a low cost)
-    distance = osd.weighted_levenshtein_distance("HELLO", "HELL0")
+    distance = WeightedLevenshtein().distance("HELLO", "HELL0")
 
     print(f"The OCR-aware distance is: {distance}")
 

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

@@ -39,7 +39,9 @@ This makes it ideal for matching potentially incorrect OCR output against known
 Features
 ========
 
+- **High Performance**: The core logic is implemented in Rust with speed in mind.
 - **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.
+- **Explainable Edit Path**: Returns the optimal sequence of edit operations (substitutions, insertions, and deletions) used to transform one string into another.
 - **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.

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

@@ -3,8 +3,9 @@ requires = ["maturin>=0.14,<2"]
 build-backend = "maturin"
 
 [project]
-name = "ocr_stringdist"
+name = "ocr-stringdist"
 dynamic = ["version"]
+readme = "README.md"
 requires-python = ">=3.9"
 classifiers = [
   "Programming Language :: Rust",
@@ -14,6 +15,7 @@ classifiers = [
 
 [project.urls]
 repository = "https://github.com/NiklasvonM/ocr-stringdist"
+documentation = "https://niklasvonm.github.io/ocr-stringdist/"
 
 
 [tool.maturin]
@@ -37,3 +39,4 @@ docs = [
     "sphinx-mdinclude>=0.6.2",
     "sphinx-rtd-theme>=3.0.2",
 ]
+temp = []

ocr_stringdist-0.2.0/PKG-INFO

@@ -1,9 +0,0 @@
-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