pdfdancer-client-python 3.0.1__tar.gz → 3.0.2__tar.gz

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 3.0.1
+Version: 3.0.2
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ Dynamic: license-file
 
 # PDFDancer Python Client
 
-This README documents `pdfdancer-client-python` version `3.0.0`.
+This README documents `pdfdancer-client-python` version `3.0.2`.
 
 ![PDFDancer logo](media/logo-silver-60h.webp)
 
@@ -69,7 +69,7 @@ pixel-perfect control from Python. The same API is also available for TypeScript
 ## Installation
 
 ```bash
-pip install pdfdancer-client-python==3.0.0
+pip install pdfdancer-client-python==3.0.2
 
 # Editable install for local development
 pip install -e .
@@ -139,6 +139,20 @@ snapshot = first_page.get_snapshot()
 
 Page-scoped selectors, text editing, and builders automatically restrict the operation to that page.
 
+## Reading Units
+
+Reading-unit analysis returns semantically classified text blocks with reading order, source provenance, bounds, and
+relationships. Each call analyzes the current session state and makes a fresh request.
+
+```python
+document_analysis = pdf.analyze_reading_units()
+page_analysis = pdf.page(1).analyze_reading_units()
+
+for page in document_analysis.pages:
+    for unit in page.units:
+        print(unit.role, unit.text)
+```
+
 ## Selection
 
 Document- and page-scoped selectors return typed objects for images, paths, form XObjects, and form fields. Position
@@ -412,8 +426,8 @@ Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub
 
 ```bash
 # Create and push a release tag — GitHub Actions handles the rest
-git tag v2.0.0
-git push origin v2.0.0
+git tag v3.0.2
+git push origin v3.0.2
 ```
 
 #### Code Quality

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/README.md

@@ -1,6 +1,6 @@
 # PDFDancer Python Client
 
-This README documents `pdfdancer-client-python` version `3.0.0`.
+This README documents `pdfdancer-client-python` version `3.0.2`.
 
 ![PDFDancer logo](media/logo-silver-60h.webp)
 
@@ -33,7 +33,7 @@ pixel-perfect control from Python. The same API is also available for TypeScript
 ## Installation
 
 ```bash
-pip install pdfdancer-client-python==3.0.0
+pip install pdfdancer-client-python==3.0.2
 
 # Editable install for local development
 pip install -e .
@@ -103,6 +103,20 @@ snapshot = first_page.get_snapshot()
 
 Page-scoped selectors, text editing, and builders automatically restrict the operation to that page.
 
+## Reading Units
+
+Reading-unit analysis returns semantically classified text blocks with reading order, source provenance, bounds, and
+relationships. Each call analyzes the current session state and makes a fresh request.
+
+```python
+document_analysis = pdf.analyze_reading_units()
+page_analysis = pdf.page(1).analyze_reading_units()
+
+for page in document_analysis.pages:
+    for unit in page.units:
+        print(unit.role, unit.text)
+```
+
 ## Selection
 
 Document- and page-scoped selectors return typed objects for images, paths, form XObjects, and form fields. Position
@@ -376,8 +390,8 @@ Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub
 
 ```bash
 # Create and push a release tag — GitHub Actions handles the rest
-git tag v2.0.0
-git push origin v2.0.0
+git tag v3.0.2
+git push origin v3.0.2
 ```
 
 #### Code Quality

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/src/pdfdancer/__init__.py

@@ -42,6 +42,16 @@ from .models import (
     Point,
     Position,
     PositionMode,
+    ReadingUnit,
+    ReadingUnitBounds,
+    ReadingUnitDocumentAnalysis,
+    ReadingUnitMode,
+    ReadingUnitPageAnalysis,
+    ReadingUnitProvenance,
+    ReadingUnitRelationship,
+    ReadingUnitRelationshipType,
+    ReadingUnitRole,
+    ReadingUnitStreamMembership,
     ShapeType,
     Size,
     StandardFonts,
@@ -116,6 +126,16 @@ __all__ = [
     "Point",
     "StandardFonts",
     "PageSize",
+    "ReadingUnit",
+    "ReadingUnitBounds",
+    "ReadingUnitDocumentAnalysis",
+    "ReadingUnitMode",
+    "ReadingUnitPageAnalysis",
+    "ReadingUnitProvenance",
+    "ReadingUnitRelationship",
+    "ReadingUnitRelationshipType",
+    "ReadingUnitRole",
+    "ReadingUnitStreamMembership",
     "Orientation",
     "FontRecommendation",
     "FontType",

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/src/pdfdancer/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.0.1'
-__version_tuple__ = version_tuple = (3, 0, 1)
+__version__ = version = '3.0.2'
+__version_tuple__ = version_tuple = (3, 0, 2)
 
 __commit_id__ = commit_id = None

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/src/pdfdancer/models.py

@@ -268,6 +268,119 @@ class ShapeType(Enum):
     RECT = "RECT"  # Rectangular area with width and height
 
 
+class ReadingUnitRole(Enum):
+    HEADING = "HEADING"
+    PARAGRAPH = "PARAGRAPH"
+    LIST = "LIST"
+    TABLE = "TABLE"
+    CAPTION = "CAPTION"
+    CALLOUT = "CALLOUT"
+    PREFORMATTED_TEXT = "PREFORMATTED_TEXT"
+    PAGE_HEADER = "PAGE_HEADER"
+    PAGE_FOOTER = "PAGE_FOOTER"
+    PAGE_NUMBER = "PAGE_NUMBER"
+    FOOTNOTE = "FOOTNOTE"
+    WATERMARK = "WATERMARK"
+    UNKNOWN = "UNKNOWN"
+
+    @classmethod
+    def from_value(cls, value: Any) -> tuple["ReadingUnitRole", str]:
+        raw = value if isinstance(value, str) else "UNKNOWN"
+        try:
+            return cls(raw), raw
+        except ValueError:
+            return cls.UNKNOWN, raw
+
+
+class ReadingUnitRelationshipType(Enum):
+    CAPTION_FOR = "CAPTION_FOR"
+    HEADING_PARENT_OF = "HEADING_PARENT_OF"
+    UNKNOWN = "UNKNOWN"
+
+    @classmethod
+    def from_value(cls, value: Any) -> tuple["ReadingUnitRelationshipType", str]:
+        raw = value if isinstance(value, str) else "UNKNOWN"
+        try:
+            return cls(raw), raw
+        except ValueError:
+            return cls.UNKNOWN, raw
+
+
+class ReadingUnitMode(Enum):
+    PRIMARY = "PRIMARY"
+    UNKNOWN = "UNKNOWN"
+
+    @classmethod
+    def from_value(cls, value: Any) -> tuple["ReadingUnitMode", str]:
+        raw = value if isinstance(value, str) else "UNKNOWN"
+        try:
+            return cls(raw), raw
+        except ValueError:
+            return cls.UNKNOWN, raw
+
+
+@dataclass(frozen=True)
+class ReadingUnitBounds:
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+@dataclass(frozen=True)
+class ReadingUnitProvenance:
+    page_number: int
+    source_element_ids: List[str]
+    bounds: ReadingUnitBounds
+
+
+@dataclass(frozen=True)
+class ReadingUnitStreamMembership:
+    included: bool
+    order: Optional[int]
+
+
+@dataclass(frozen=True)
+class ReadingUnitRelationship:
+    type: ReadingUnitRelationshipType
+    raw_type: str
+    target_unit_id: str
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "ReadingUnitRelationship":
+        relationship_type, raw_type = ReadingUnitRelationshipType.from_value(
+            data.get("type")
+        )
+        return cls(relationship_type, raw_type, str(data.get("targetUnitId", "")))
+
+
+@dataclass(frozen=True)
+class ReadingUnit:
+    id: str
+    role: ReadingUnitRole
+    raw_role: str
+    text: str
+    stream: Mapping[str, ReadingUnitStreamMembership]
+    provenance: ReadingUnitProvenance
+    relationships: List[ReadingUnitRelationship]
+
+
+@dataclass(frozen=True)
+class ReadingUnitPageAnalysis:
+    page_number: int
+    mode: ReadingUnitMode
+    raw_mode: str
+    units: List[ReadingUnit]
+
+
+@dataclass(frozen=True)
+class ReadingUnitDocumentAnalysis:
+    page_count: int
+    mode: ReadingUnitMode
+    raw_mode: str
+    pages: List[ReadingUnitPageAnalysis]
+
+
 @dataclass
 class Point:
     """Represents a 2D point with x and y coordinates."""

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/src/pdfdancer/pdfdancer_v2.py

@@ -74,6 +74,15 @@ from .models import (
     PathObjectRef,
     Position,
     PositionMode,
+    ReadingUnit,
+    ReadingUnitBounds,
+    ReadingUnitDocumentAnalysis,
+    ReadingUnitMode,
+    ReadingUnitPageAnalysis,
+    ReadingUnitProvenance,
+    ReadingUnitRelationship,
+    ReadingUnitRole,
+    ReadingUnitStreamMembership,
     ShapeType,
     TextObjectRef,
 )
@@ -721,6 +730,11 @@ class PageClient:
     def get_snapshot(self, types: Optional[str] = None) -> PageSnapshot:
         return self.root.get_page_snapshot(self.page_number, types)
 
+    def analyze_reading_units(self) -> ReadingUnitPageAnalysis:
+        return cast(
+            ReadingUnitPageAnalysis, self.root.analyze_reading_units(self.page_number)
+        )
+
     @property
     def size(self) -> Optional[PageSize]:
         """Property alias for page size."""
@@ -2480,6 +2494,22 @@ class PDFDancer:
 
         return self._parse_document_snapshot(data)
 
+    def analyze_reading_units(
+        self, page_number: Optional[int] = None
+    ) -> Union[ReadingUnitDocumentAnalysis, ReadingUnitPageAnalysis]:
+        """Analyze the current session PDF, or one one-based page, into reading units."""
+        if page_number is not None:
+            if page_number < 1:
+                raise ValidationException(
+                    f"Page number must be >= 1 (1-based indexing), got {page_number}"
+                )
+            response = self._make_request(
+                "GET", f"/pdf/page/{page_number}/reading-units"
+            )
+            return self._parse_reading_unit_page_analysis(response.json())
+        response = self._make_request("GET", "/pdf/document/reading-units")
+        return self._parse_reading_unit_document_analysis(response.json())
+
     def get_page_snapshot(
         self, page_number: int, types: Optional[str] = None
     ) -> PageSnapshot:
@@ -3129,6 +3159,64 @@ class PDFDancer:
 
         return DocumentSnapshot(page_count=page_count, fonts=fonts, pages=pages)
 
+    def _parse_reading_unit_page_analysis(
+        self, data: Mapping[str, Any]
+    ) -> ReadingUnitPageAnalysis:
+        mode, raw_mode = ReadingUnitMode.from_value(data.get("mode"))
+        return ReadingUnitPageAnalysis(
+            page_number=int(data.get("pageNumber", 0)),
+            mode=mode,
+            raw_mode=raw_mode,
+            units=[self._parse_reading_unit(unit) for unit in data.get("units", [])],
+        )
+
+    def _parse_reading_unit_document_analysis(
+        self, data: Mapping[str, Any]
+    ) -> ReadingUnitDocumentAnalysis:
+        mode, raw_mode = ReadingUnitMode.from_value(data.get("mode"))
+        return ReadingUnitDocumentAnalysis(
+            page_count=int(data.get("pageCount", 0)),
+            mode=mode,
+            raw_mode=raw_mode,
+            pages=[
+                self._parse_reading_unit_page_analysis(page)
+                for page in data.get("pages", [])
+            ],
+        )
+
+    def _parse_reading_unit(self, data: Mapping[str, Any]) -> ReadingUnit:
+        role, raw_role = ReadingUnitRole.from_value(data.get("role"))
+        provenance_data = data.get("provenance") or {}
+        bounds_data = provenance_data.get("bounds") or {}
+        stream = {
+            str(mode): ReadingUnitStreamMembership(
+                bool(membership.get("included", False)), membership.get("order")
+            )
+            for mode, membership in (data.get("stream") or {}).items()
+        }
+        provenance = ReadingUnitProvenance(
+            page_number=int(provenance_data.get("pageNumber", 0)),
+            source_element_ids=list(provenance_data.get("sourceElementIds") or []),
+            bounds=ReadingUnitBounds(
+                float(bounds_data.get("x", 0)),
+                float(bounds_data.get("y", 0)),
+                float(bounds_data.get("width", 0)),
+                float(bounds_data.get("height", 0)),
+            ),
+        )
+        return ReadingUnit(
+            id=str(data.get("id", "")),
+            role=role,
+            raw_role=raw_role,
+            text=str(data.get("text", "")),
+            stream=stream,
+            provenance=provenance,
+            relationships=[
+                ReadingUnitRelationship.from_dict(item)
+                for item in data.get("relationships", [])
+            ],
+        )
+
     # Context Manager Support (Python enhancement)
     def __enter__(self) -> "PDFDancer":
         """Context manager entry."""

{pdfdancer_client_python-3.0.1 → pdfdancer_client_python-3.0.2}/src/pdfdancer_client_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 3.0.1
+Version: 3.0.2
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ Dynamic: license-file
 
 # PDFDancer Python Client
 
-This README documents `pdfdancer-client-python` version `3.0.0`.
+This README documents `pdfdancer-client-python` version `3.0.2`.
 
 ![PDFDancer logo](media/logo-silver-60h.webp)
 
@@ -69,7 +69,7 @@ pixel-perfect control from Python. The same API is also available for TypeScript
 ## Installation
 
 ```bash
-pip install pdfdancer-client-python==3.0.0
+pip install pdfdancer-client-python==3.0.2
 
 # Editable install for local development
 pip install -e .
@@ -139,6 +139,20 @@ snapshot = first_page.get_snapshot()
 
 Page-scoped selectors, text editing, and builders automatically restrict the operation to that page.
 
+## Reading Units
+
+Reading-unit analysis returns semantically classified text blocks with reading order, source provenance, bounds, and
+relationships. Each call analyzes the current session state and makes a fresh request.
+
+```python
+document_analysis = pdf.analyze_reading_units()
+page_analysis = pdf.page(1).analyze_reading_units()
+
+for page in document_analysis.pages:
+    for unit in page.units:
+        print(unit.role, unit.text)
+```
+
 ## Selection
 
 Document- and page-scoped selectors return typed objects for images, paths, form XObjects, and form fields. Position
@@ -412,8 +426,8 @@ Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub
 
 ```bash
 # Create and push a release tag — GitHub Actions handles the rest
-git tag v2.0.0
-git push origin v2.0.0
+git tag v3.0.2
+git push origin v3.0.2
 ```
 
 #### Code Quality