natural-pdf 0.2.8__tar.gz → 0.2.10__tar.gz

{natural_pdf-0.2.8/natural_pdf.egg-info → natural_pdf-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natural-pdf
-Version: 0.2.8
+Version: 0.2.10
 Summary: A more intuitive interface for working with PDFs
 Author-email: Jonathan Soma <jonathan.soma@gmail.com>
 License-Expression: MIT

{natural_pdf-0.2.8 → natural_pdf-0.2.10}/natural_pdf/analyzers/guides.py

@@ -128,19 +128,59 @@ class GuidesList(UserList):
     """A list of guide coordinates that also provides methods for creating guides."""
 
     def __init__(self, parent_guides: "Guides", axis: Literal["vertical", "horizontal"], data=None):
-        super().__init__(data or [])
+        # Always sort the initial data
+        super().__init__(sorted(data) if data else [])
         self._parent = parent_guides
         self._axis = axis
 
     def __getitem__(self, i):
-        """Override to handle slicing properly."""
+        """Override to handle slicing and negative indexing properly."""
         if isinstance(i, slice):
             # Return a new GuidesList with the sliced data
             return self.__class__(self._parent, self._axis, self.data[i])
         else:
-            # For single index, return the value directly
+            # For single index, handle negative indices properly
+            if i < 0:
+                # Convert negative index to positive
+                i = len(self.data) + i
             return self.data[i]
 
+    def __setitem__(self, i, item):
+        """Override to maintain sorted order."""
+        self.data[i] = item
+        self.data.sort()
+
+    def append(self, item):
+        """Override to maintain sorted order."""
+        self.data.append(item)
+        self.data.sort()
+
+    def extend(self, other):
+        """Override to maintain sorted order."""
+        self.data.extend(other)
+        self.data.sort()
+
+    def insert(self, i, item):
+        """Override to maintain sorted order."""
+        self.data.append(item)  # Just append and sort
+        self.data.sort()
+
+    def __iadd__(self, other):
+        """Override to maintain sorted order."""
+        self.data.extend(other)
+        self.data.sort()
+        return self
+
+    @property
+    def data(self):
+        """Get the data list."""
+        return self._data
+
+    @data.setter
+    def data(self, value):
+        """Set the data list, always keeping it sorted."""
+        self._data = sorted(value) if value else []
+
     def from_content(
         self,
         markers: Union[str, List[str], "ElementCollection", Callable, None],
@@ -1842,6 +1882,370 @@ class Guides:
             self.horizontal.pop(index)
         return self
 
+    # -------------------------------------------------------------------------
+    # Region extraction properties
+    # -------------------------------------------------------------------------
+
+    @property
+    def columns(self):
+        """Access columns by index like guides.columns[0]."""
+        return _ColumnAccessor(self)
+
+    @property
+    def rows(self):
+        """Access rows by index like guides.rows[0]."""
+        return _RowAccessor(self)
+
+    @property
+    def cells(self):
+        """Access cells by index like guides.cells[row][col] or guides.cells[row, col]."""
+        return _CellAccessor(self)
+
+    # -------------------------------------------------------------------------
+    # Region extraction methods (alternative API)
+    # -------------------------------------------------------------------------
+
+    def column(self, index: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a column region from the guides.
+
+        Args:
+            index: Column index (0-based)
+            obj: Page or Region to create the column on (uses self.context if None)
+
+        Returns:
+            Region representing the specified column
+
+        Raises:
+            IndexError: If column index is out of range
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.vertical or index < 0 or index >= len(self.vertical) - 1:
+            raise IndexError(
+                f"Column index {index} out of range (have {len(self.vertical)-1} columns)"
+            )
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        _, y0, _, y1 = bounds
+
+        # Get column boundaries
+        x0 = self.vertical[index]
+        x1 = self.vertical[index + 1]
+
+        # Create region using absolute coordinates
+        if hasattr(target, "region"):
+            # Target has a region method (Page)
+            return target.region(x0, y0, x1, y1)
+        elif hasattr(target, "page"):
+            # Target is a Region, use its parent page
+            # The coordinates from guides are already absolute
+            return target.page.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def row(self, index: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a row region from the guides.
+
+        Args:
+            index: Row index (0-based)
+            obj: Page or Region to create the row on (uses self.context if None)
+
+        Returns:
+            Region representing the specified row
+
+        Raises:
+            IndexError: If row index is out of range
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.horizontal or index < 0 or index >= len(self.horizontal) - 1:
+            raise IndexError(f"Row index {index} out of range (have {len(self.horizontal)-1} rows)")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        x0, _, x1, _ = bounds
+
+        # Get row boundaries
+        y0 = self.horizontal[index]
+        y1 = self.horizontal[index + 1]
+
+        # Create region using absolute coordinates
+        if hasattr(target, "region"):
+            # Target has a region method (Page)
+            return target.region(x0, y0, x1, y1)
+        elif hasattr(target, "page"):
+            # Target is a Region, use its parent page
+            # The coordinates from guides are already absolute
+            return target.page.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def cell(self, row: int, col: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a cell region from the guides.
+
+        Args:
+            row: Row index (0-based)
+            col: Column index (0-based)
+            obj: Page or Region to create the cell on (uses self.context if None)
+
+        Returns:
+            Region representing the specified cell
+
+        Raises:
+            IndexError: If row or column index is out of range
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.vertical or col < 0 or col >= len(self.vertical) - 1:
+            raise IndexError(
+                f"Column index {col} out of range (have {len(self.vertical)-1} columns)"
+            )
+        if not self.horizontal or row < 0 or row >= len(self.horizontal) - 1:
+            raise IndexError(f"Row index {row} out of range (have {len(self.horizontal)-1} rows)")
+
+        # Get cell boundaries
+        x0 = self.vertical[col]
+        x1 = self.vertical[col + 1]
+        y0 = self.horizontal[row]
+        y1 = self.horizontal[row + 1]
+
+        # Create region using absolute coordinates
+        if hasattr(target, "region"):
+            # Target has a region method (Page)
+            return target.region(x0, y0, x1, y1)
+        elif hasattr(target, "page"):
+            # Target is a Region, use its parent page
+            # The coordinates from guides are already absolute
+            return target.page.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def left_of(self, guide_index: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a region to the left of a vertical guide.
+
+        Args:
+            guide_index: Vertical guide index
+            obj: Page or Region to create the region on (uses self.context if None)
+
+        Returns:
+            Region to the left of the specified guide
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.vertical or guide_index < 0 or guide_index >= len(self.vertical):
+            raise IndexError(f"Guide index {guide_index} out of range")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        x0, y0, _, y1 = bounds
+
+        # Create region from left edge to guide
+        x1 = self.vertical[guide_index]
+
+        if hasattr(target, "region"):
+            return target.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def right_of(self, guide_index: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a region to the right of a vertical guide.
+
+        Args:
+            guide_index: Vertical guide index
+            obj: Page or Region to create the region on (uses self.context if None)
+
+        Returns:
+            Region to the right of the specified guide
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.vertical or guide_index < 0 or guide_index >= len(self.vertical):
+            raise IndexError(f"Guide index {guide_index} out of range")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        _, y0, x1, y1 = bounds
+
+        # Create region from guide to right edge
+        x0 = self.vertical[guide_index]
+
+        if hasattr(target, "region"):
+            return target.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def above(self, guide_index: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a region above a horizontal guide.
+
+        Args:
+            guide_index: Horizontal guide index
+            obj: Page or Region to create the region on (uses self.context if None)
+
+        Returns:
+            Region above the specified guide
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.horizontal or guide_index < 0 or guide_index >= len(self.horizontal):
+            raise IndexError(f"Guide index {guide_index} out of range")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        x0, y0, x1, _ = bounds
+
+        # Create region from top edge to guide
+        y1 = self.horizontal[guide_index]
+
+        if hasattr(target, "region"):
+            return target.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def below(self, guide_index: int, obj: Optional[Union["Page", "Region"]] = None) -> "Region":
+        """
+        Get a region below a horizontal guide.
+
+        Args:
+            guide_index: Horizontal guide index
+            obj: Page or Region to create the region on (uses self.context if None)
+
+        Returns:
+            Region below the specified guide
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.horizontal or guide_index < 0 or guide_index >= len(self.horizontal):
+            raise IndexError(f"Guide index {guide_index} out of range")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        x0, _, x1, y1 = bounds
+
+        # Create region from guide to bottom edge
+        y0 = self.horizontal[guide_index]
+
+        if hasattr(target, "region"):
+            return target.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def between_vertical(
+        self, start_index: int, end_index: int, obj: Optional[Union["Page", "Region"]] = None
+    ) -> "Region":
+        """
+        Get a region between two vertical guides.
+
+        Args:
+            start_index: Starting vertical guide index
+            end_index: Ending vertical guide index
+            obj: Page or Region to create the region on (uses self.context if None)
+
+        Returns:
+            Region between the specified guides
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.vertical:
+            raise ValueError("No vertical guides available")
+        if start_index < 0 or start_index >= len(self.vertical):
+            raise IndexError(f"Start index {start_index} out of range")
+        if end_index < 0 or end_index >= len(self.vertical):
+            raise IndexError(f"End index {end_index} out of range")
+        if start_index >= end_index:
+            raise ValueError("Start index must be less than end index")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        _, y0, _, y1 = bounds
+
+        # Get horizontal boundaries
+        x0 = self.vertical[start_index]
+        x1 = self.vertical[end_index]
+
+        if hasattr(target, "region"):
+            return target.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
+    def between_horizontal(
+        self, start_index: int, end_index: int, obj: Optional[Union["Page", "Region"]] = None
+    ) -> "Region":
+        """
+        Get a region between two horizontal guides.
+
+        Args:
+            start_index: Starting horizontal guide index
+            end_index: Ending horizontal guide index
+            obj: Page or Region to create the region on (uses self.context if None)
+
+        Returns:
+            Region between the specified guides
+        """
+        target = obj or self.context
+        if target is None:
+            raise ValueError("No context available for region creation")
+
+        if not self.horizontal:
+            raise ValueError("No horizontal guides available")
+        if start_index < 0 or start_index >= len(self.horizontal):
+            raise IndexError(f"Start index {start_index} out of range")
+        if end_index < 0 or end_index >= len(self.horizontal):
+            raise IndexError(f"End index {end_index} out of range")
+        if start_index >= end_index:
+            raise ValueError("Start index must be less than end index")
+
+        # Get bounds from context
+        bounds = self._get_context_bounds()
+        if not bounds:
+            raise ValueError("Could not determine bounds")
+        x0, _, x1, _ = bounds
+
+        # Get vertical boundaries
+        y0 = self.horizontal[start_index]
+        y1 = self.horizontal[end_index]
+
+        if hasattr(target, "region"):
+            return target.region(x0, y0, x1, y1)
+        else:
+            raise TypeError(f"Cannot create region on {type(target)}")
+
     # -------------------------------------------------------------------------
     # Operations
     # -------------------------------------------------------------------------
@@ -3825,3 +4229,95 @@ class Guides:
             return "vertical"
         else:
             return "horizontal"
+
+
+# -------------------------------------------------------------------------
+# Accessor classes for property-based access
+# -------------------------------------------------------------------------
+
+
+class _ColumnAccessor:
+    """Provides indexed access to columns via guides.columns[index]."""
+
+    def __init__(self, guides: "Guides"):
+        self._guides = guides
+
+    def __len__(self):
+        """Return number of columns (vertical guides - 1)."""
+        return max(0, len(self._guides.vertical) - 1)
+
+    def __getitem__(self, index: int) -> "Region":
+        """Get column at the specified index."""
+        # Handle negative indexing
+        if index < 0:
+            index = len(self) + index
+        return self._guides.column(index)
+
+
+class _RowAccessor:
+    """Provides indexed access to rows via guides.rows[index]."""
+
+    def __init__(self, guides: "Guides"):
+        self._guides = guides
+
+    def __len__(self):
+        """Return number of rows (horizontal guides - 1)."""
+        return max(0, len(self._guides.horizontal) - 1)
+
+    def __getitem__(self, index: int) -> "Region":
+        """Get row at the specified index."""
+        # Handle negative indexing
+        if index < 0:
+            index = len(self) + index
+        return self._guides.row(index)
+
+
+class _CellAccessor:
+    """Provides indexed access to cells via guides.cells[row][col] or guides.cells[row, col]."""
+
+    def __init__(self, guides: "Guides"):
+        self._guides = guides
+
+    def __getitem__(self, key) -> Union["Region", "_CellRowAccessor"]:
+        """
+        Get cell(s) at the specified position.
+
+        Supports:
+        - guides.cells[row, col] - tuple indexing
+        - guides.cells[row][col] - nested indexing
+        """
+        if isinstance(key, tuple) and len(key) == 2:
+            # Direct tuple access: guides.cells[row, col]
+            row, col = key
+            # Handle negative indexing for both row and col
+            if row < 0:
+                row = len(self._guides.rows) + row
+            if col < 0:
+                col = len(self._guides.columns) + col
+            return self._guides.cell(row, col)
+        elif isinstance(key, int):
+            # First level of nested access: guides.cells[row]
+            # Handle negative indexing for row
+            if key < 0:
+                key = len(self._guides.rows) + key
+            # Return a row accessor that allows [col] indexing
+            return _CellRowAccessor(self._guides, key)
+        else:
+            raise TypeError(
+                f"Cell indices must be integers or tuple of two integers, got {type(key)}"
+            )
+
+
+class _CellRowAccessor:
+    """Provides column access for a specific row in nested cell indexing."""
+
+    def __init__(self, guides: "Guides", row: int):
+        self._guides = guides
+        self._row = row
+
+    def __getitem__(self, col: int) -> "Region":
+        """Get cell at [row][col]."""
+        # Handle negative indexing for column
+        if col < 0:
+            col = len(self._guides.columns) + col
+        return self._guides.cell(self._row, col)

{natural_pdf-0.2.8 → natural_pdf-0.2.10}/natural_pdf/cli.py

@@ -16,7 +16,7 @@ INSTALL_RECIPES: Dict[str, list[str]] = {
     "paddle": ["paddlepaddle>=3.0.0", "paddleocr>=3.0.1", "paddlex>=3.0.2", "pandas>=2.2.0"],
     "numpy-high": ["numpy>=2.0"],
     "numpy-low": ["numpy<1.27"],
-    "surya": ["surya-ocr>=0.13.0"],
+    "surya": ["surya-ocr<0.15"],
     "yolo": ["doclayout_yolo", "huggingface_hub>=0.29.3"],
     "docling": ["docling"],
     # light helpers

{natural_pdf-0.2.8 → natural_pdf-0.2.10}/natural_pdf/elements/element_collection.py

@@ -633,9 +633,7 @@ class ElementCollection(
         pdfplumber's layout engine if layout=True is specified.
 
         Args:
-            separator: String to insert between text from different elements when
-                      using simple joining (layout=False). Default is a single space.
-                      Ignored when layout=True as the layout engine handles spacing.
+            separator: String to join text from elements. Default is a single space.
             preserve_whitespace: Deprecated. Use layout=False for simple joining.
             use_exclusions: Deprecated. Exclusions should be applied *before* creating
                           the collection or by filtering the collection itself.
@@ -652,15 +650,49 @@ class ElementCollection(
         Returns:
             Combined text from elements, potentially with layout-based spacing.
         """
-        # Filter to just TextElements that likely have _char_dicts
-        text_elements = [
+        # Check if we have any elements at all
+        if not self._elements:
+            return ""
+
+        # Check if all elements are TextElements with character data
+        text_elements_with_chars = [
             el
             for el in self._elements
-            if isinstance(el, TextElement) and hasattr(el, "_char_dicts")
+            if isinstance(el, TextElement) and hasattr(el, "_char_dicts") and el._char_dicts
         ]
 
-        if not text_elements:
-            return ""
+        # If we have a mixed collection (Regions, TextElements without chars, etc),
+        # use a simpler approach: call extract_text on each element
+        if len(text_elements_with_chars) < len(self._elements):
+            # Mixed collection - extract text from each element
+            element_texts = []
+
+            # Sort elements by position first
+            sorted_elements = sorted(
+                self._elements,
+                key=lambda el: (
+                    el.page.index if hasattr(el, "page") else 0,
+                    el.top if hasattr(el, "top") else 0,
+                    el.x0 if hasattr(el, "x0") else 0,
+                ),
+            )
+
+            for el in sorted_elements:
+                if hasattr(el, "extract_text"):
+                    # Call extract_text on the element (works for TextElement, Region, etc)
+                    text = el.extract_text(**kwargs)
+                    if text:
+                        element_texts.append(text)
+                elif hasattr(el, "text"):
+                    # Fallback to text property if available
+                    text = getattr(el, "text", "")
+                    if text:
+                        element_texts.append(text)
+
+            return separator.join(element_texts)
+
+        # All elements are TextElements with char data - use the original approach
+        text_elements = text_elements_with_chars
 
         # Collect all character dictionaries
         all_char_dicts = []
@@ -669,11 +701,20 @@ class ElementCollection(
 
         if not all_char_dicts:
             # Handle case where elements exist but have no char dicts
-            logger.warning(
+            logger.debug(
                 "ElementCollection.extract_text: No character dictionaries found in TextElements."
             )
+            # Sort elements by position before joining
+            sorted_text_elements = sorted(
+                text_elements,
+                key=lambda el: (
+                    el.page.index if hasattr(el, "page") else 0,
+                    el.top if hasattr(el, "top") else 0,
+                    el.x0 if hasattr(el, "x0") else 0,
+                ),
+            )
             return separator.join(
-                getattr(el, "text", "") for el in text_elements
+                getattr(el, "text", "") for el in sorted_text_elements
             )  # Fallback to simple join of word text
 
         # Apply content filtering if provided
@@ -737,33 +778,20 @@ class ElementCollection(
                 all_char_dicts.sort(
                     key=lambda c: (c.get("page_number", 0), c.get("top", 0), c.get("x0", 0))
                 )
-                result = separator.join(c.get("text", "") for c in all_char_dicts)
+                result = " ".join(c.get("text", "") for c in all_char_dicts)
 
         else:
+            print("JOIN WITHOUT LAYOUT")
             # Default: Simple join without layout
             logger.debug("ElementCollection.extract_text: Using simple join (layout=False).")
-
-            # Instead of joining all characters individually, we need to:
-            # 1. Extract text from each element
-            # 2. Join the element texts with the separator
-
-            # Sort elements by document order (page, top, x0)
-            sorted_elements = sorted(
-                text_elements,
-                key=lambda el: (
-                    el.page.index if hasattr(el, "page") else 0,
-                    el.top if hasattr(el, "top") else 0,
-                    el.x0 if hasattr(el, "x0") else 0,
-                ),
-            )
-
-            # Extract text from each element
-            element_texts = []
-            for el in sorted_elements:
-                if hasattr(el, "text") and el.text:
-                    element_texts.append(el.text)
-
-            result = separator.join(element_texts)
+            result = separator.join(el.extract_text() for el in text_elements)
+
+            # # Sort chars by document order (page, top, x0)
+            # all_char_dicts.sort(
+            #     key=lambda c: (c.get("page_number", 0), c.get("top", 0), c.get("x0", 0))
+            # )
+            # # Simple join of character text
+            # result = "".join(c.get("text", "") for c in all_char_dicts)
 
         # Determine final strip flag – same rule as global helper unless caller overrides
         strip_text = strip if strip is not None else (not use_layout)