natocr 2.0.0__tar.gz → 2.1.0__tar.gz

{natocr-2.0.0 → natocr-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natocr
-Version: 2.0.0
+Version: 2.1.0
 Summary: Native OCR library using platform-specific frameworks (macOS Vision, Windows Runtime OCR)
 Author-email: alfredchiesa <alfred.personal@icloud.com>
 Maintainer-email: alfredchiesa <alfred.personal@icloud.com>
@@ -58,6 +58,14 @@ than third-party alternatives like Tesseract. **natocr** makes reaching for them
 painless via one clean Python API instead of wrangling with Objective-C bridges 
 or WinRT async plumbing.
 
+## Notable Updates
+
+- **v2.0.0** (2026-06-25) - batch & async support: [`recognize_many()`](#batch-and-async) plus awaitable [`arecognize()`](#batch-and-async) / [`arecognize_many()`](#batch-and-async) for concurrent, non-blocking OCR
+- **v1.6.1** (2026-06-04) - animated PNG and multi-image HEIF support
+- **v1.6.0** (2026-06-04) - multi-page documents and DjVu support
+- **v1.5.0** (2026-06-04) - JPEG 2000, JPEG XL, and JPEG XR / HD Photo support
+- **v1.4.0** (2026-06-04) - HEIC / HEIF (iPhone photo) support
+
 ## Install
 
 ```bash
@@ -71,6 +79,9 @@ The right native backend (Vision on macOS, Windows Runtime OCR on Windows) is
 pulled in automatically for your platform - no OS-specific install command to
 pick.
 
+natocr ships a `py.typed` marker, so the public API is fully typed - mypy,
+pyright, and your editor pick up the hints with no stubs needed.
+
 ## Quick start
 
 ```python
@@ -122,6 +133,32 @@ page.lines      # ['Acme Coffee', 'Latte $4.50']  - elements grouped into lines
 page.words      # list of TextElement with non-empty text
 ```
 
+Want the confidence and bounds for each line (not just the text)? `text_lines`
+gives you the same grouping as [`TextLine`](https://alfredchiesa.github.io/natocr/api/#natocr.TextLine)
+objects, and `paragraphs` merges lines into blocks by their vertical gaps - both
+aggregate confidence across their elements:
+
+```python
+for line in page.text_lines:
+    print(line.text, line.confidence, line.bounds.bounds)
+
+for para in page.paragraphs:   # lines joined by newlines, confidence averaged
+    print(para.confidence, para.text)
+```
+
+### Filtering by Confidence
+
+Drop the low-confidence noise with `filter()` - it hands back a new `OCRResult`
+keeping only detections at or above the threshold:
+
+```python
+clean = page.filter(0.8)       # only elements >= 0.8 confidence
+print(clean.text)
+```
+
+Elements without a confidence score (Windows OCR doesn't report one) are kept by
+default since they can't be judged - pass `drop_unknown=True` to drop them too.
+
 ### Detection Language
 
 Pick a different recognition language, and inspect what the current platform

{natocr-2.0.0 → natocr-2.1.0}/README.md

@@ -9,6 +9,14 @@ than third-party alternatives like Tesseract. **natocr** makes reaching for them
 painless via one clean Python API instead of wrangling with Objective-C bridges 
 or WinRT async plumbing.
 
+## Notable Updates
+
+- **v2.0.0** (2026-06-25) - batch & async support: [`recognize_many()`](#batch-and-async) plus awaitable [`arecognize()`](#batch-and-async) / [`arecognize_many()`](#batch-and-async) for concurrent, non-blocking OCR
+- **v1.6.1** (2026-06-04) - animated PNG and multi-image HEIF support
+- **v1.6.0** (2026-06-04) - multi-page documents and DjVu support
+- **v1.5.0** (2026-06-04) - JPEG 2000, JPEG XL, and JPEG XR / HD Photo support
+- **v1.4.0** (2026-06-04) - HEIC / HEIF (iPhone photo) support
+
 ## Install
 
 ```bash
@@ -22,6 +30,9 @@ The right native backend (Vision on macOS, Windows Runtime OCR on Windows) is
 pulled in automatically for your platform - no OS-specific install command to
 pick.
 
+natocr ships a `py.typed` marker, so the public API is fully typed - mypy,
+pyright, and your editor pick up the hints with no stubs needed.
+
 ## Quick start
 
 ```python
@@ -73,6 +84,32 @@ page.lines      # ['Acme Coffee', 'Latte $4.50']  - elements grouped into lines
 page.words      # list of TextElement with non-empty text
 ```
 
+Want the confidence and bounds for each line (not just the text)? `text_lines`
+gives you the same grouping as [`TextLine`](https://alfredchiesa.github.io/natocr/api/#natocr.TextLine)
+objects, and `paragraphs` merges lines into blocks by their vertical gaps - both
+aggregate confidence across their elements:
+
+```python
+for line in page.text_lines:
+    print(line.text, line.confidence, line.bounds.bounds)
+
+for para in page.paragraphs:   # lines joined by newlines, confidence averaged
+    print(para.confidence, para.text)
+```
+
+### Filtering by Confidence
+
+Drop the low-confidence noise with `filter()` - it hands back a new `OCRResult`
+keeping only detections at or above the threshold:
+
+```python
+clean = page.filter(0.8)       # only elements >= 0.8 confidence
+print(clean.text)
+```
+
+Elements without a confidence score (Windows OCR doesn't report one) are kept by
+default since they can't be judged - pass `drop_unknown=True` to drop them too.
+
 ### Detection Language
 
 Pick a different recognition language, and inspect what the current platform

{natocr-2.0.0 → natocr-2.1.0}/natocr/__init__.py

@@ -7,9 +7,9 @@ this package provides ocr functionality using native frameworks:
 """
 
 from .core import OCR
-from .models import BoundingBox, OCRResult, TextElement
+from .models import BoundingBox, OCRResult, TextElement, TextLine
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 __author__ = "alfredchiesa"
 __email__ = "alfred.personal@icloud.com"
 
@@ -17,5 +17,6 @@ __all__ = [
     "OCR",
     "OCRResult",
     "TextElement",
+    "TextLine",
     "BoundingBox",
 ]

natocr-2.1.0/natocr/models.py

@@ -0,0 +1,230 @@
+"""
+data models for ocr results
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+@dataclass
+class BoundingBox:
+    """Pixel-space bounding box for a piece of detected text.
+
+    The origin is the top-left of the image, with ``y`` growing downward.
+
+    Attributes:
+        x: left edge, in pixels.
+        y: top edge, in pixels.
+        width: box width, in pixels.
+        height: box height, in pixels.
+    """
+
+    x: float
+    y: float
+    width: float
+    height: float
+
+    @property
+    def bounds(self) -> Tuple[float, float, float, float]:
+        """The box as an ``(x, y, width, height)`` tuple."""
+        return (self.x, self.y, self.width, self.height)
+
+
+@dataclass
+class TextElement:
+    """A single detected piece of text with its location.
+
+    Attributes:
+        text: the recognized string.
+        bounds: where it was found in the image.
+        confidence: recognition confidence in ``0.0..1.0``, or ``None`` when the
+            backend doesn't report one (Windows OCR doesn't).
+    """
+
+    text: str
+    bounds: BoundingBox
+    confidence: Optional[float] = None
+
+
+@dataclass
+class TextLine:
+    """A run of detected text grouped into one line.
+
+    The structured cousin of [`OCRResult.lines`][natocr.OCRResult.lines] - same
+    grouping, but each line keeps its elements, an aggregated confidence, and
+    the box that wraps them. Also the shape
+    [`OCRResult.paragraphs`][natocr.OCRResult.paragraphs] returns.
+
+    Attributes:
+        text: the line's text, its elements joined left-to-right.
+        elements: the detections that make up the line.
+        confidence: mean confidence across the elements that report one, or
+            ``None`` when none do (Windows OCR doesn't).
+        bounds: the box enclosing every element in the line.
+    """
+
+    text: str
+    elements: List[TextElement]
+    confidence: Optional[float]
+    bounds: BoundingBox
+
+
+def _mean_confidence(elements: List[TextElement]) -> Optional[float]:
+    """average of the confidences that exist, or none if there aren't any"""
+    scores = [e.confidence for e in elements if e.confidence is not None]
+    return sum(scores) / len(scores) if scores else None
+
+
+def _union_bounds(elements: List[TextElement]) -> BoundingBox:
+    """smallest box that wraps every element"""
+    left = min(e.bounds.x for e in elements)
+    top = min(e.bounds.y for e in elements)
+    right = max(e.bounds.x + e.bounds.width for e in elements)
+    bottom = max(e.bounds.y + e.bounds.height for e in elements)
+    return BoundingBox(x=left, y=top, width=right - left, height=bottom - top)
+
+
+@dataclass
+class OCRResult:
+    """Everything an OCR pass found in one image.
+
+    Attributes:
+        text: all detected text joined into a single string.
+        confidence: average confidence across detections, or ``None`` if the
+            backend doesn't report confidence.
+        elements: per-detection breakdown with text, bounds, and confidence.
+    """
+
+    text: str
+    confidence: Optional[float] = None
+    elements: List[TextElement] = None
+
+    def __post_init__(self):
+        # default the mutable elements list when none was passed
+        if self.elements is None:
+            self.elements = []
+
+    @property
+    def words(self) -> List[TextElement]:
+        """The elements that contain non-whitespace text."""
+        return [elem for elem in self.elements if elem.text.strip()]
+
+    def _group_lines(self) -> List[List[TextElement]]:
+        """group elements into lines by vertical proximity, in reading order"""
+        groups = []
+        current_line = []
+        current_y = None
+
+        for elem in sorted(self.elements, key=lambda e: (e.bounds.y, e.bounds.x)):
+            if (
+                current_y is None
+                or abs(elem.bounds.y - current_y) < elem.bounds.height * 0.5
+            ):
+                current_line.append(elem)
+                current_y = elem.bounds.y
+            else:
+                if current_line:
+                    groups.append(current_line)
+                current_line = [elem]
+                current_y = elem.bounds.y
+
+        if current_line:
+            groups.append(current_line)
+
+        return groups
+
+    @property
+    def lines(self) -> List[str]:
+        """Detected text grouped into lines by vertical position.
+
+        Elements whose ``y`` are close together are treated as one line and
+        joined left-to-right. Falls back to ``[text]`` (or ``[]``) when there
+        are no elements.
+        """
+        if not self.elements:
+            return [self.text] if self.text else []
+        return [" ".join(e.text for e in group) for group in self._group_lines()]
+
+    @property
+    def text_lines(self) -> List[TextLine]:
+        """Detected lines as [TextLine][natocr.TextLine] objects.
+
+        Same grouping as [lines][natocr.OCRResult.lines], but each line carries
+        its elements, an aggregated confidence (mean over the elements that
+        report one), and the box that wraps them. Empty when there are no
+        positioned elements.
+        """
+        return [
+            TextLine(
+                text=" ".join(e.text for e in group),
+                elements=group,
+                confidence=_mean_confidence(group),
+                bounds=_union_bounds(group),
+            )
+            for group in self._group_lines()
+        ]
+
+    @property
+    def paragraphs(self) -> List[TextLine]:
+        """Lines merged into paragraphs by the vertical gaps between them.
+
+        Walks the lines top-to-bottom and starts a new paragraph whenever the
+        gap to the next line is more than ~1.5x the line's height. Each
+        paragraph comes back in the same [TextLine][natocr.TextLine] shape - its
+        ``text`` is the member lines joined by newlines, with ``confidence`` and
+        ``bounds`` aggregated across all of their elements.
+        """
+        lines = self.text_lines
+        if not lines:
+            return []
+
+        # break on a big vertical gap, otherwise keep stacking lines
+        groups = [[lines[0]]]
+        for prev, line in zip(lines, lines[1:]):
+            gap = line.bounds.y - (prev.bounds.y + prev.bounds.height)
+            if gap > prev.bounds.height * 1.5:
+                groups.append([line])
+            else:
+                groups[-1].append(line)
+
+        paragraphs = []
+        for group in groups:
+            elements = [e for line in group for e in line.elements]
+            paragraphs.append(
+                TextLine(
+                    text="\n".join(line.text for line in group),
+                    elements=elements,
+                    confidence=_mean_confidence(elements),
+                    bounds=_union_bounds(elements),
+                )
+            )
+        return paragraphs
+
+    def filter(
+        self, min_confidence: float, *, drop_unknown: bool = False
+    ) -> "OCRResult":
+        """A copy keeping only elements at or above ``min_confidence``.
+
+        Args:
+            min_confidence: lowest confidence to keep, in ``0.0..1.0``.
+            drop_unknown: what to do with elements that have no confidence
+                (Windows OCR never reports one). ``False`` (the default) keeps
+                them, since they can't be judged; ``True`` drops them.
+
+        Returns:
+            A new [OCRResult][natocr.OCRResult] holding the surviving elements,
+            with ``text`` and ``confidence`` recomputed from them.
+        """
+        kept = []
+        for elem in self.elements:
+            if elem.confidence is None:
+                if not drop_unknown:
+                    kept.append(elem)
+            elif elem.confidence >= min_confidence:
+                kept.append(elem)
+
+        return OCRResult(
+            text=" ".join(e.text for e in kept),
+            confidence=_mean_confidence(kept),
+            elements=kept,
+        )

{natocr-2.0.0 → natocr-2.1.0}/natocr/windows.py

@@ -123,14 +123,13 @@ class WindowsOCR:
         """process windows ocr result into ocr result"""
         elements = []
         full_text_parts = []
-        total_confidence = 0.0
-        valid_lines = 0
 
         for line in result.lines:
             line_text = line.text
             if line_text.strip():
-                # get line bounding box
-                bbox = line.words[0].bounding_rect if line.words else line.bounding_rect
+                # word rect when we have one, else the line rect
+                source = line.words[0] if line.words else line
+                bbox = source.bounding_rect
 
                 # convert to pixel coordinates
                 x = bbox.x
@@ -138,21 +137,30 @@ class WindowsOCR:
                 width = bbox.width
                 height = bbox.height
 
+                # winrt ocr doesn't expose confidence today, so this is None in
+                # practice - but grab it best-effort in case a build ever does
+                confidence = getattr(source, "confidence", None)
+
                 # create bounding box and text element
                 bounds = BoundingBox(x=x, y=y, width=width, height=height)
-                element = TextElement(text=line_text, bounds=bounds, confidence=None)
+                element = TextElement(
+                    text=line_text, bounds=bounds, confidence=confidence
+                )
                 elements.append(element)
 
                 # accumulate text
                 full_text_parts.append(line_text)
-                valid_lines += 1
 
         # join text parts
         full_text = " ".join(full_text_parts)
 
+        # mean of whatever confidences exist (none today), mirroring macos
+        scores = [e.confidence for e in elements if e.confidence is not None]
+        avg_confidence = sum(scores) / len(scores) if scores else None
+
         return OCRResult(
             text=full_text,
-            confidence=None,  # windows ocr doesn't provide confidence scores
+            confidence=avg_confidence,
             elements=elements,
         )
 

{natocr-2.0.0 → natocr-2.1.0}/natocr.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natocr
-Version: 2.0.0
+Version: 2.1.0
 Summary: Native OCR library using platform-specific frameworks (macOS Vision, Windows Runtime OCR)
 Author-email: alfredchiesa <alfred.personal@icloud.com>
 Maintainer-email: alfredchiesa <alfred.personal@icloud.com>
@@ -58,6 +58,14 @@ than third-party alternatives like Tesseract. **natocr** makes reaching for them
 painless via one clean Python API instead of wrangling with Objective-C bridges 
 or WinRT async plumbing.
 
+## Notable Updates
+
+- **v2.0.0** (2026-06-25) - batch & async support: [`recognize_many()`](#batch-and-async) plus awaitable [`arecognize()`](#batch-and-async) / [`arecognize_many()`](#batch-and-async) for concurrent, non-blocking OCR
+- **v1.6.1** (2026-06-04) - animated PNG and multi-image HEIF support
+- **v1.6.0** (2026-06-04) - multi-page documents and DjVu support
+- **v1.5.0** (2026-06-04) - JPEG 2000, JPEG XL, and JPEG XR / HD Photo support
+- **v1.4.0** (2026-06-04) - HEIC / HEIF (iPhone photo) support
+
 ## Install
 
 ```bash
@@ -71,6 +79,9 @@ The right native backend (Vision on macOS, Windows Runtime OCR on Windows) is
 pulled in automatically for your platform - no OS-specific install command to
 pick.
 
+natocr ships a `py.typed` marker, so the public API is fully typed - mypy,
+pyright, and your editor pick up the hints with no stubs needed.
+
 ## Quick start
 
 ```python
@@ -122,6 +133,32 @@ page.lines      # ['Acme Coffee', 'Latte $4.50']  - elements grouped into lines
 page.words      # list of TextElement with non-empty text
 ```
 
+Want the confidence and bounds for each line (not just the text)? `text_lines`
+gives you the same grouping as [`TextLine`](https://alfredchiesa.github.io/natocr/api/#natocr.TextLine)
+objects, and `paragraphs` merges lines into blocks by their vertical gaps - both
+aggregate confidence across their elements:
+
+```python
+for line in page.text_lines:
+    print(line.text, line.confidence, line.bounds.bounds)
+
+for para in page.paragraphs:   # lines joined by newlines, confidence averaged
+    print(para.confidence, para.text)
+```
+
+### Filtering by Confidence
+
+Drop the low-confidence noise with `filter()` - it hands back a new `OCRResult`
+keeping only detections at or above the threshold:
+
+```python
+clean = page.filter(0.8)       # only elements >= 0.8 confidence
+print(clean.text)
+```
+
+Elements without a confidence score (Windows OCR doesn't report one) are kept by
+default since they can't be judged - pass `drop_unknown=True` to drop them too.
+
 ### Detection Language
 
 Pick a different recognition language, and inspect what the current platform

{natocr-2.0.0 → natocr-2.1.0}/natocr.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ natocr/__init__.py
 natocr/core.py
 natocr/macos.py
 natocr/models.py
+natocr/py.typed
 natocr/windows.py
 natocr.egg-info/PKG-INFO
 natocr.egg-info/SOURCES.txt

{natocr-2.0.0 → natocr-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "natocr"
-version = "2.0.0"
+version = "2.1.0"
 description = "Native OCR library using platform-specific frameworks (macOS Vision, Windows Runtime OCR)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -64,6 +64,10 @@ Changelog = "https://github.com/alfredchiesa/natocr/blob/main/CHANGELOG.md"
 where = ["."]
 include = ["natocr*"]
 
+[tool.setuptools.package-data]
+# ship the pep 561 marker so downstream mypy/editors pick up our type hints
+natocr = ["py.typed"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]

natocr-2.1.0/tests/test_models.py

@@ -0,0 +1,141 @@
+"""tests for the data models"""
+
+import pytest
+
+from natocr.models import BoundingBox, OCRResult, TextElement, TextLine
+
+
+class TestBoundingBox:
+    def test_bounds_returns_tuple(self):
+        box = BoundingBox(x=1.0, y=2.0, width=3.0, height=4.0)
+        assert box.bounds == (1.0, 2.0, 3.0, 4.0)
+
+
+class TestTextElement:
+    def test_defaults_confidence_to_none(self):
+        elem = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1))
+        assert elem.confidence is None
+
+    def test_stores_confidence(self):
+        elem = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1), confidence=0.9)
+        assert elem.confidence == 0.9
+
+
+class TestOCRResult:
+    def test_post_init_defaults_elements_to_empty_list(self):
+        result = OCRResult(text="hi")
+        assert result.elements == []
+
+    def test_post_init_keeps_provided_elements(self):
+        elem = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1))
+        result = OCRResult(text="hi", elements=[elem])
+        assert result.elements == [elem]
+
+    def test_words_filters_whitespace_only(self):
+        good = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1))
+        blank = TextElement(text="   ", bounds=BoundingBox(0, 0, 1, 1))
+        result = OCRResult(text="hi", elements=[good, blank])
+        assert result.words == [good]
+
+    def test_lines_no_elements_with_text(self):
+        result = OCRResult(text="just text")
+        assert result.lines == ["just text"]
+
+    def test_lines_no_elements_no_text(self):
+        result = OCRResult(text="")
+        assert result.lines == []
+
+    def test_lines_groups_close_y_into_single_line(self):
+        a = TextElement(text="hello", bounds=BoundingBox(x=0, y=0, width=10, height=10))
+        b = TextElement(text="world", bounds=BoundingBox(x=20, y=1, width=10, height=10))
+        result = OCRResult(text="ignored", elements=[a, b])
+        assert result.lines == ["hello world"]
+
+    def test_lines_splits_distant_y_into_multiple_lines(self):
+        top = TextElement(text="top", bounds=BoundingBox(x=0, y=0, width=10, height=10))
+        bottom = TextElement(
+            text="bottom", bounds=BoundingBox(x=0, y=100, width=10, height=10)
+        )
+        # pass out of order to also exercise the (y, x) sort
+        result = OCRResult(text="ignored", elements=[bottom, top])
+        assert result.lines == ["top", "bottom"]
+
+
+class TestTextLines:
+    def test_aggregates_text_confidence_and_bounds_per_line(self):
+        a = TextElement(
+            text="hello", bounds=BoundingBox(0, 0, 10, 10), confidence=0.8
+        )
+        b = TextElement(
+            text="world", bounds=BoundingBox(20, 1, 10, 10), confidence=0.6
+        )
+        result = OCRResult(text="ignored", elements=[a, b])
+        lines = result.text_lines
+        assert len(lines) == 1
+        line = lines[0]
+        assert isinstance(line, TextLine)
+        assert line.text == "hello world"
+        assert line.confidence == pytest.approx(0.7)  # mean of 0.8 and 0.6
+        # union box wraps both elements
+        assert line.bounds.bounds == (0, 0, 30, 11)
+        assert line.elements == [a, b]
+
+    def test_confidence_ignores_missing_scores(self):
+        scored = TextElement(text="a", bounds=BoundingBox(0, 0, 10, 10), confidence=0.9)
+        unscored = TextElement(text="b", bounds=BoundingBox(12, 0, 10, 10))
+        result = OCRResult(text="ignored", elements=[scored, unscored])
+        # only the scored element counts toward the mean
+        assert result.text_lines[0].confidence == pytest.approx(0.9)
+
+    def test_confidence_none_when_no_scores(self):
+        elem = TextElement(text="a", bounds=BoundingBox(0, 0, 10, 10))
+        result = OCRResult(text="ignored", elements=[elem])
+        assert result.text_lines[0].confidence is None
+
+    def test_empty_without_elements(self):
+        assert OCRResult(text="just text").text_lines == []
+
+
+class TestParagraphs:
+    def test_groups_lines_by_vertical_gap(self):
+        # two stacked lines, then a big gap, then a third line
+        l1 = TextElement(text="one", bounds=BoundingBox(0, 0, 10, 10), confidence=0.9)
+        l2 = TextElement(text="two", bounds=BoundingBox(0, 12, 10, 10), confidence=0.7)
+        l3 = TextElement(text="far", bounds=BoundingBox(0, 100, 10, 10), confidence=0.5)
+        result = OCRResult(text="ignored", elements=[l1, l2, l3])
+        paras = result.paragraphs
+        assert len(paras) == 2
+        # first paragraph stacks the two close lines, newline-joined
+        assert paras[0].text == "one\ntwo"
+        assert paras[0].confidence == pytest.approx(0.8)  # mean of 0.9 and 0.7
+        assert paras[1].text == "far"
+
+    def test_empty_without_elements(self):
+        assert OCRResult(text="just text").paragraphs == []
+
+
+class TestFilter:
+    def _result(self):
+        high = TextElement(text="hi", bounds=BoundingBox(0, 0, 10, 10), confidence=0.9)
+        low = TextElement(text="lo", bounds=BoundingBox(0, 20, 10, 10), confidence=0.4)
+        unknown = TextElement(text="??", bounds=BoundingBox(0, 40, 10, 10))
+        return OCRResult(text="ignored", elements=[high, low, unknown]), high, unknown
+
+    def test_drops_below_threshold_keeps_unknown_by_default(self):
+        result, high, unknown = self._result()
+        out = result.filter(0.5)
+        # low (0.4) drops; high (0.9) and the unscored one stay
+        assert out.elements == [high, unknown]
+        assert out.text == "hi ??"
+        assert out.confidence == pytest.approx(0.9)  # unknown ignored in the mean
+
+    def test_drop_unknown_removes_unscored_elements(self):
+        result, high, _ = self._result()
+        out = result.filter(0.5, drop_unknown=True)
+        assert out.elements == [high]
+
+    def test_returns_new_result_without_mutating(self):
+        result, _, _ = self._result()
+        out = result.filter(0.5)
+        assert out is not result
+        assert len(result.elements) == 3  # original untouched

{natocr-2.0.0 → natocr-2.1.0}/tests/test_package.py

@@ -1,5 +1,6 @@
 """tests for the package's public surface"""
 
+import os
 import re
 
 import natocr
@@ -12,5 +13,11 @@ def test_version_exposed():
 
 
 def test_public_exports():
-    for name in ("OCR", "OCRResult", "TextElement", "BoundingBox"):
+    for name in ("OCR", "OCRResult", "TextElement", "TextLine", "BoundingBox"):
         assert hasattr(natocr, name)
+
+
+def test_ships_py_typed_marker():
+    # pep 561 marker so downstream type checkers trust our hints
+    marker = os.path.join(os.path.dirname(natocr.__file__), "py.typed")
+    assert os.path.isfile(marker)

natocr-2.0.0/natocr/models.py

@@ -1,108 +0,0 @@
-"""
-data models for ocr results
-"""
-
-from dataclasses import dataclass
-from typing import List, Optional, Tuple
-
-
-@dataclass
-class BoundingBox:
-    """Pixel-space bounding box for a piece of detected text.
-
-    The origin is the top-left of the image, with ``y`` growing downward.
-
-    Attributes:
-        x: left edge, in pixels.
-        y: top edge, in pixels.
-        width: box width, in pixels.
-        height: box height, in pixels.
-    """
-
-    x: float
-    y: float
-    width: float
-    height: float
-
-    @property
-    def bounds(self) -> Tuple[float, float, float, float]:
-        """The box as an ``(x, y, width, height)`` tuple."""
-        return (self.x, self.y, self.width, self.height)
-
-
-@dataclass
-class TextElement:
-    """A single detected piece of text with its location.
-
-    Attributes:
-        text: the recognized string.
-        bounds: where it was found in the image.
-        confidence: recognition confidence in ``0.0..1.0``, or ``None`` when the
-            backend doesn't report one (Windows OCR doesn't).
-    """
-
-    text: str
-    bounds: BoundingBox
-    confidence: Optional[float] = None
-
-
-@dataclass
-class OCRResult:
-    """Everything an OCR pass found in one image.
-
-    Attributes:
-        text: all detected text joined into a single string.
-        confidence: average confidence across detections, or ``None`` if the
-            backend doesn't report confidence.
-        elements: per-detection breakdown with text, bounds, and confidence.
-    """
-
-    text: str
-    confidence: Optional[float] = None
-    elements: List[TextElement] = None
-
-    def __post_init__(self):
-        # default the mutable elements list when none was passed
-        if self.elements is None:
-            self.elements = []
-
-    @property
-    def words(self) -> List[TextElement]:
-        """The elements that contain non-whitespace text."""
-        return [elem for elem in self.elements if elem.text.strip()]
-
-    @property
-    def lines(self) -> List[str]:
-        """Detected text grouped into lines by vertical position.
-
-        Elements whose ``y`` are close together are treated as one line and
-        joined left-to-right. Falls back to ``[text]`` (or ``[]``) when there
-        are no elements.
-        """
-        if not self.elements:
-            return [self.text] if self.text else []
-
-        # group elements by approximate y-coordinate for line detection
-        lines = []
-        current_line = []
-        current_y = None
-
-        for elem in sorted(self.elements, key=lambda e: (e.bounds.y, e.bounds.x)):
-            if (
-                current_y is None
-                or abs(elem.bounds.y - current_y) < elem.bounds.height * 0.5
-            ):
-                current_line.append(elem)
-                current_y = elem.bounds.y
-            else:
-                if current_line:
-                    line_text = " ".join(elem.text for elem in current_line)
-                    lines.append(line_text)
-                current_line = [elem]
-                current_y = elem.bounds.y
-
-        if current_line:
-            line_text = " ".join(elem.text for elem in current_line)
-            lines.append(line_text)
-
-        return lines

natocr-2.0.0/tests/test_models.py

@@ -1,59 +0,0 @@
-"""tests for the data models"""
-
-from natocr.models import BoundingBox, OCRResult, TextElement
-
-
-class TestBoundingBox:
-    def test_bounds_returns_tuple(self):
-        box = BoundingBox(x=1.0, y=2.0, width=3.0, height=4.0)
-        assert box.bounds == (1.0, 2.0, 3.0, 4.0)
-
-
-class TestTextElement:
-    def test_defaults_confidence_to_none(self):
-        elem = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1))
-        assert elem.confidence is None
-
-    def test_stores_confidence(self):
-        elem = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1), confidence=0.9)
-        assert elem.confidence == 0.9
-
-
-class TestOCRResult:
-    def test_post_init_defaults_elements_to_empty_list(self):
-        result = OCRResult(text="hi")
-        assert result.elements == []
-
-    def test_post_init_keeps_provided_elements(self):
-        elem = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1))
-        result = OCRResult(text="hi", elements=[elem])
-        assert result.elements == [elem]
-
-    def test_words_filters_whitespace_only(self):
-        good = TextElement(text="hi", bounds=BoundingBox(0, 0, 1, 1))
-        blank = TextElement(text="   ", bounds=BoundingBox(0, 0, 1, 1))
-        result = OCRResult(text="hi", elements=[good, blank])
-        assert result.words == [good]
-
-    def test_lines_no_elements_with_text(self):
-        result = OCRResult(text="just text")
-        assert result.lines == ["just text"]
-
-    def test_lines_no_elements_no_text(self):
-        result = OCRResult(text="")
-        assert result.lines == []
-
-    def test_lines_groups_close_y_into_single_line(self):
-        a = TextElement(text="hello", bounds=BoundingBox(x=0, y=0, width=10, height=10))
-        b = TextElement(text="world", bounds=BoundingBox(x=20, y=1, width=10, height=10))
-        result = OCRResult(text="ignored", elements=[a, b])
-        assert result.lines == ["hello world"]
-
-    def test_lines_splits_distant_y_into_multiple_lines(self):
-        top = TextElement(text="top", bounds=BoundingBox(x=0, y=0, width=10, height=10))
-        bottom = TextElement(
-            text="bottom", bounds=BoundingBox(x=0, y=100, width=10, height=10)
-        )
-        # pass out of order to also exercise the (y, x) sort
-        result = OCRResult(text="ignored", elements=[bottom, top])
-        assert result.lines == ["top", "bottom"]