natural-pdf 0.2.13__tar.gz → 0.2.15__tar.gz

{natural_pdf-0.2.13/natural_pdf.egg-info → natural_pdf-0.2.15}/PKG-INFO

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

{natural_pdf-0.2.13 → natural_pdf-0.2.15}/natural_pdf/elements/base.py

@@ -106,7 +106,7 @@ class DirectionalMixin:
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
-        offset: float = 0.1,
+        offset: float = 0.0,
         **kwargs,
     ) -> "Region":
         """
@@ -1209,6 +1209,9 @@ class Element(
 
         return self
 
+    def exclude(self):
+        self.page.add_exclusion(self)
+
     def _get_render_specs(
         self,
         mode: Literal["show", "render"] = "show",

{natural_pdf-0.2.13 → natural_pdf-0.2.15}/natural_pdf/elements/element_collection.py

@@ -888,6 +888,9 @@ class ElementCollection(
         self._elements.sort(key=key, reverse=reverse)
         return self
 
+    def exclude(self):
+        self.page.add_exclusion(self)
+
     def highlight(
         self,
         label: Optional[str] = None,
@@ -1902,13 +1905,87 @@ class ElementCollection(
 
         return ElementCollection(all_found_elements)
 
-    def extract_each_text(self, **kwargs) -> List[str]:
-        """
-        Extract text from each element in this region.
+    def extract_each_text(
+        self,
+        order: Optional[Union[str, Callable[[T], Any]]] = None,
+        *,
+        newlines: bool = True,
+        **kwargs,
+    ) -> List[str]:
+        """Return a list with the extracted text for every element.
+
+        Parameters
+        ----------
+        order
+            Controls the ordering of elements **before** extraction:
+
+            * ``None`` (default) – keep the collection's current order.
+            * ``callable`` – a function that will be used as ``key`` for :pyfunc:`sorted`.
+            * ``"ltr"`` – left-to-right ordering (x0, then y-top).
+            * ``"rtl"`` – right-to-left ordering (−x0, then y-top).
+            * ``"natural"`` – natural reading order (y-top, then x0).
+
+        Remaining keyword arguments are forwarded to each element's
+        :py:meth:`extract_text` method.
         """
-        return self.apply(
-            lambda element: element.extract_text(**kwargs) if element is not None else None
-        )
+
+        # -- Determine ordering --------------------------------------------------
+        elements: List[T] = list(self._elements)  # make a shallow copy we can sort
+
+        if order is not None and len(elements) > 1:
+            try:
+                if callable(order):
+                    elements.sort(key=order)
+                elif isinstance(order, str):
+                    preset = order.lower()
+                    if preset in {"ltr", "left-to-right"}:
+                        elements.sort(
+                            key=lambda el: (
+                                (
+                                    getattr(el, "page", None).index
+                                    if hasattr(el, "page") and el.page
+                                    else 0
+                                ),
+                                getattr(el, "x0", 0),
+                                getattr(el, "top", 0),
+                            )
+                        )
+                    elif preset in {"rtl", "right-to-left"}:
+                        elements.sort(
+                            key=lambda el: (
+                                (
+                                    getattr(el, "page", None).index
+                                    if hasattr(el, "page") and el.page
+                                    else 0
+                                ),
+                                -getattr(el, "x0", 0),
+                                getattr(el, "top", 0),
+                            )
+                        )
+                    elif preset in {"natural", "tdlr", "top-down"}:
+                        elements.sort(
+                            key=lambda el: (
+                                (
+                                    getattr(el, "page", None).index
+                                    if hasattr(el, "page") and el.page
+                                    else 0
+                                ),
+                                getattr(el, "top", 0),
+                                getattr(el, "x0", 0),
+                            )
+                        )
+                    else:
+                        # Unknown preset – silently ignore to keep original order
+                        pass
+            except Exception:
+                # If anything goes wrong, fall back to original order
+                pass
+
+        # -- Extract ----------------------------------------------------------------
+        return [
+            el.extract_text(newlines=newlines, **kwargs) if el is not None else None  # type: ignore[arg-type]
+            for el in elements
+        ]
 
     def correct_ocr(
         self,
@@ -2673,10 +2750,17 @@ class ElementCollection(
         else:
             v_dist = 0  # Vertically overlapping
 
-        # Use Chebyshev distance (max of horizontal and vertical)
-        # This creates a square proximity zone
-        distance = max(h_dist, v_dist)
+        # ------------------------------------------------------------------
+        # Decide connection logic based on vertical_gap parameter
+        # ------------------------------------------------------------------
+        if vertical_gap is not None:
+            # Consider elements connected when they vertically stack within
+            # the allowed gap **and** have some horizontal overlap
+            horizontal_overlap = not (h_dist > 0)
+            return horizontal_overlap and v_dist <= vertical_gap
 
+        # Fallback to legacy Chebyshev distance using ``threshold``
+        distance = max(h_dist, v_dist)
         return distance <= threshold
 
     def _merge_region_group(
@@ -2752,6 +2836,9 @@ class ElementCollection(
     def dissolve(
         self,
         padding: float = 2.0,
+        *,
+        vertical_gap: Optional[float] = None,
+        vertical: Optional[bool] = False,
         geometry: Literal["rect", "polygon"] = "rect",
         group_by: List[str] = None,
     ) -> "ElementCollection":
@@ -2764,8 +2851,19 @@ class ElementCollection(
         bounding boxes.
 
         Args:
-            padding: Maximum distance in points between elements to consider
-                them connected. Default is 2.0 points.
+            padding: Maximum chebyshev distance (in any direction) between
+                elements to consider them connected **when ``vertical_gap`` is
+                not provided**. Default 2.0 pt.
+
+            vertical_gap: If given, switches to *stack-aware* dissolve:
+                two elements are connected when their horizontal projections
+                overlap (any amount) **and** the vertical distance between them
+                is ≤ ``vertical_gap``.  This lets you combine multi-line labels
+                that share the same column but have blank space between lines.
+
+            vertical: If given, automatically sets vertical_gap to maximum to
+                allow for easy vertical stacking.
+
             geometry: Type of geometry to use for merged regions. Currently only
                 "rect" (bounding box) is supported. "polygon" will raise
                 NotImplementedError.
@@ -2807,6 +2905,9 @@ class ElementCollection(
         if geometry not in ["rect", "polygon"]:
             raise ValueError(f"Invalid geometry type: {geometry}. Must be 'rect' or 'polygon'")
 
+        if vertical:
+            vertical_gap = float("inf")
+
         from natural_pdf.elements.region import Region
 
         # Filter to elements with bbox (all elements that can be dissolved)
@@ -2835,7 +2936,9 @@ class ElementCollection(
             logger.debug(f"Processing group {group_key} with {len(group_elements)} elements")
 
             # Find connected components within this group
-            components = self._find_connected_components_elements(group_elements, padding)
+            components = self._find_connected_components_elements(
+                group_elements, padding, vertical_gap
+            )
 
             # Merge each component
             for component_elements in components:
@@ -2894,7 +2997,7 @@ class ElementCollection(
         return groups
 
     def _find_connected_components_elements(
-        self, elements: List["Element"], padding: float
+        self, elements: List["Element"], padding: float, vertical_gap: Optional[float] = None
     ) -> List[List["Element"]]:
         """Find connected components among elements using union-find."""
         if not elements:
@@ -2919,7 +3022,7 @@ class ElementCollection(
         # Check all pairs of elements for connectivity
         for i in range(len(elements)):
             for j in range(i + 1, len(elements)):
-                if self._are_elements_connected(elements[i], elements[j], padding):
+                if self._are_elements_connected(elements[i], elements[j], padding, vertical_gap):
                     union(i, j)
 
         # Group elements by their connected component
@@ -3004,7 +3107,9 @@ class ElementCollection(
 
         return merged_region
 
-    def _are_elements_connected(self, elem1: "Element", elem2: "Element", threshold: float) -> bool:
+    def _are_elements_connected(
+        self, elem1: "Element", elem2: "Element", threshold: float, vertical_gap: float | None
+    ) -> bool:
         """Check if two elements are connected (adjacent or overlapping)."""
         # Check if elements are on the same page
         # Handle edge cases where elements might not have a page attribute
@@ -3057,6 +3162,12 @@ class ElementCollection(
         # This creates a square proximity zone
         distance = max(h_dist, v_dist)
 
+        if vertical_gap is not None:
+            # 1. vertical distance ≤ vertical_gap
+            # 2. horizontal ranges overlap OR touch
+            h_overlap = (min(x1_1, x1_2) - max(x0_1, x0_2)) >= 0
+            return h_overlap and v_dist <= vertical_gap
+
         return distance <= threshold
 
     def _copy_element_attributes_to_region(
@@ -3163,3 +3274,30 @@ class ElementCollection(
         return self
 
     # ------------------------------------------------------------------
+
+    # ------------------------------------------------------------------
+    # Public alias: combine
+    # ------------------------------------------------------------------
+    def combine(
+        self,
+        padding: float = 2.0,
+        *,
+        vertical_gap: Optional[float] = None,
+        vertical: Optional[bool] = False,
+        geometry: Literal["rect", "polygon"] = "rect",
+        group_by: List[str] = None,
+    ) -> "ElementCollection":
+        """Alias for :py:meth:`dissolve` – retained for discoverability.
+
+        Many users find the verb *combine* more intuitive than *dissolve* when
+        merging nearby or stacked elements into unified Regions.  The parameters
+        are identical; see :py:meth:`dissolve` for full documentation.
+        """
+
+        return self.dissolve(
+            padding=padding,
+            vertical_gap=vertical_gap,
+            vertical=vertical,
+            geometry=geometry,
+            group_by=group_by,
+        )

{natural_pdf-0.2.13 → natural_pdf-0.2.15}/natural_pdf/elements/rect.py

@@ -88,6 +88,40 @@ class RectangleElement(Element):
         """Get the stroke width of the rectangle."""
         return self._obj.get("linewidth", 0)
 
+    @property
+    def is_horizontal(self) -> bool:
+        """Check if this is a horizontal line based on coordinates."""
+        # Calculate absolute difference in coordinates
+        dx = abs(self.x1 - self.x0)
+        dy = abs(self.top - self.bottom)
+
+        # Define a tolerance for near-horizontal lines (e.g., 1 point)
+        tolerance = 1.0
+
+        # Horizontal if y-change is within tolerance and x-change is significant
+        return dy <= tolerance and dx > tolerance
+
+    @property
+    def is_vertical(self) -> bool:
+        """Check if this is a vertical line based on coordinates."""
+        # Calculate absolute difference in coordinates
+        dx = abs(self.x1 - self.x0)
+        dy = abs(self.top - self.bottom)
+
+        # Define a tolerance for near-vertical lines (e.g., 1 point)
+        tolerance = 1.0
+
+        # Vertical if x-change is within tolerance and y-change is significant
+        return dx <= tolerance and dy > tolerance
+
+    @property
+    def orientation(self) -> str:
+        """Get the orientation of the line ('horizontal', 'vertical', or 'diagonal')."""
+        if self.is_horizontal:
+            return "horizontal"
+        elif self.is_vertical:
+            return "vertical"
+
     def extract_text(self, **kwargs) -> str:
         """
         Extract text from inside this rectangle.

{natural_pdf-0.2.13 → natural_pdf-0.2.15}/natural_pdf/elements/region.py

@@ -738,6 +738,9 @@ class Region(
             and self.bottom > element.top
         )
 
+    def exclude(self):
+        self.page.add_exclusion(self)
+
     def highlight(
         self,
         label: Optional[str] = None,
@@ -1229,7 +1232,13 @@ class Region(
             return [e for e in page_elements if self._is_element_in_region(e)]
 
     def extract_text(
-        self, apply_exclusions=True, debug=False, content_filter=None, **kwargs
+        self,
+        apply_exclusions: bool = True,
+        debug: bool = False,
+        *,
+        newlines: Union[bool, str] = True,
+        content_filter=None,
+        **kwargs,
     ) -> str:
         """
         Extract text from this region, respecting page exclusions and using pdfplumber's
@@ -1238,6 +1247,7 @@ class Region(
         Args:
             apply_exclusions: Whether to apply exclusion regions defined on the parent page.
             debug: Enable verbose debugging output for filtering steps.
+            newlines: Whether to strip newline characters from the extracted text.
             content_filter: Optional content filter to exclude specific text patterns. Can be:
                 - A regex pattern string (characters matching the pattern are EXCLUDED)
                 - A callable that takes text and returns True to KEEP the character
@@ -1311,6 +1321,18 @@ class Region(
             user_kwargs=final_kwargs,  # Pass kwargs including content_filter
         )
 
+        # Flexible newline handling (same logic as TextElement)
+        if isinstance(newlines, bool):
+            if newlines is False:
+                replacement = " "
+            else:
+                replacement = None
+        else:
+            replacement = str(newlines)
+
+        if replacement is not None:
+            result = result.replace("\n", replacement).replace("\r", replacement)
+
         logger.debug(f"Region {self.bbox}: extract_text finished, result length: {len(result)}.")
         return result
 

{natural_pdf-0.2.13 → natural_pdf-0.2.15}/natural_pdf/elements/text.py

@@ -2,7 +2,7 @@
 Text element classes for natural-pdf.
 """
 
-from typing import TYPE_CHECKING, Any, Dict, Optional
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union
 
 from natural_pdf.elements.base import Element
 
@@ -236,7 +236,13 @@ class TextElement(Element):
         return (0, 0, 0)
 
     def extract_text(
-        self, keep_blank_chars=True, strip: Optional[bool] = True, content_filter=None, **kwargs
+        self,
+        keep_blank_chars: bool = True,
+        strip: Optional[bool] = True,
+        *,
+        newlines: Union[bool, str] = True,
+        content_filter=None,
+        **kwargs,
     ) -> str:
         """
         Extract text from this element.
@@ -292,6 +298,18 @@ class TextElement(Element):
         if strip:
             result = result.strip()
 
+        # Flexible newline handling
+        if isinstance(newlines, bool):
+            if newlines is False:
+                replacement = " "  # single space when False
+            else:
+                replacement = None  # keep as-is when True
+        else:
+            replacement = str(newlines)
+
+        if replacement is not None:
+            result = result.replace("\n", replacement).replace("\r", replacement)
+
         return result
 
     def contains(self, substring: str, case_sensitive: bool = True) -> bool:

{natural_pdf-0.2.13 → natural_pdf-0.2.15}/natural_pdf/selectors/parser.py

@@ -423,7 +423,33 @@ def parse_selector(selector: str) -> Dict[str, Any]:
         # Check for other pseudo-class blocks `:name` or `:name(...)`
         pseudo_match = pseudo_pattern.match(selector)
         if pseudo_match:
+            # --- NEW: robustly capture arguments that may contain nested parentheses --- #
             name, args_str = pseudo_match.groups()
+            match_end_idx = pseudo_match.end()
+
+            # If the args_str contains unmatched opening parens, continue scanning the
+            # selector until parentheses are balanced. This allows patterns like
+            # :contains((Tre) Ofertu) or complex regex with grouping.
+            if args_str is not None and args_str.count("(") > args_str.count(")"):
+                balance = args_str.count("(") - args_str.count(")")
+                i = match_end_idx
+                while i < len(selector) and balance > 0:
+                    char = selector[i]
+                    # Append char to args_str as we extend the capture
+                    args_str += char
+                    if char == "(":
+                        balance += 1
+                    elif char == ")":
+                        balance -= 1
+                    i += 1
+                # After loop, ensure parentheses are balanced; otherwise raise error
+                if balance != 0:
+                    raise ValueError(
+                        f"Mismatched parentheses in pseudo-class :{name}(). Full selector: '{original_selector_for_error}'"
+                    )
+                # Update where the selector should be sliced off from
+                match_end_idx = i
+
             name = name.lower()  # Normalize pseudo-class name
             processed_args = args_str  # Keep as string initially, or None
 
@@ -436,7 +462,8 @@ def parse_selector(selector: str) -> Dict[str, Any]:
             # else: args remain None
 
             result["pseudo_classes"].append({"name": name, "args": processed_args})
-            selector = selector[pseudo_match.end() :].strip()
+            # IMPORTANT: use match_end_idx (may have been extended)
+            selector = selector[match_end_idx:].strip()
             processed_chunk = True
             continue
 

{natural_pdf-0.2.13 → natural_pdf-0.2.15/natural_pdf.egg-info}/PKG-INFO

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