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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natural-pdf
-Version: 0.2.13
+Version: 0.2.16
 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.16}/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.16}/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.16}/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.16}/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.16}/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.16}/natural_pdf/flows/element.py

@@ -106,6 +106,7 @@ class FlowElement:
         cross_size_absolute: Optional[float] = None,
         cross_alignment: str = "center",  # "start", "center", "end"
         until: Optional[str] = None,
+        include_source: bool = False,
         include_endpoint: bool = True,
         **kwargs,
     ) -> "FlowRegion":
@@ -178,13 +179,9 @@ class FlowElement:
             is_forward = False
             segment_iterator = range(start_segment_index, -1, -1)
         elif direction == "right":
-            if is_primary_vertical:
-                raise NotImplementedError("'right' is for horizontal flows.")
             is_forward = True
             segment_iterator = range(start_segment_index, len(self.flow.segments))
         elif direction == "left":
-            if is_primary_vertical:
-                raise NotImplementedError("'left' is for horizontal flows.")
             is_forward = False
             segment_iterator = range(start_segment_index, -1, -1)
         else:
@@ -206,28 +203,34 @@ class FlowElement:
                 "direction": direction,
                 "until": until,
                 "include_endpoint": include_endpoint,
+                "include_source": include_source,
                 **kwargs,
             }
 
-            # --- Cross-size logic: Default to "full" if no specific ratio or absolute is given ---
+            # --- Cross-size logic: Default based on direction ---
             cross_size_for_op: Union[str, float]
             if cross_size_absolute is not None:
                 cross_size_for_op = cross_size_absolute
             elif cross_size_ratio is not None:  # User explicitly provided a ratio
+                # Cross dimension depends on direction, not flow arrangement
                 base_cross_dim = (
                     self.physical_object.width
-                    if is_primary_vertical
+                    if direction in ["above", "below"]
                     else self.physical_object.height
                 )
                 cross_size_for_op = base_cross_dim * cross_size_ratio
-            else:  # Default case: neither absolute nor ratio provided, so use "full"
-                cross_size_for_op = "full"
+            else:  # Default case: neither absolute nor ratio provided
+                # Default to element size for left/right, full for above/below
+                if direction in ["left", "right"]:
+                    cross_size_for_op = self.physical_object.height
+                else:
+                    cross_size_for_op = "full"
             op_direction_params["cross_size"] = cross_size_for_op
 
             if current_segment_idx == start_segment_index:
                 op_source = self.physical_object
                 op_direction_params["size"] = remaining_size if size is not None else None
-                op_direction_params["include_source"] = False
+                op_direction_params["include_source"] = include_source
 
                 source_for_op_call = op_source
                 if not isinstance(source_for_op_call, PhysicalRegion_Class):
@@ -245,7 +248,7 @@ class FlowElement:
                     "size": remaining_size if size is not None else None,
                     "cross_size": cross_size_for_op,
                     "cross_alignment": cross_alignment,  # Pass alignment
-                    "include_source": False,
+                    "include_source": include_source,
                     # Pass other relevant kwargs if Region._direction uses them (e.g. strict_type)
                     **{k: v for k, v in kwargs.items() if k in ["strict_type", "first_match_only"]},
                 }
@@ -283,7 +286,7 @@ class FlowElement:
                         if potential_hit:
                             boundary_element_hit = potential_hit  # Set the overall boundary flag
                             # Adjust segment_contribution to stop at this boundary_element_hit.
-                            if is_primary_vertical:
+                            if direction in ["below", "above"]:
                                 if direction == "below":
                                     edge = (
                                         boundary_element_hit.bottom
@@ -300,7 +303,7 @@ class FlowElement:
                                     bottom=edge if direction == "below" else None,
                                     top=edge if direction == "above" else None,
                                 )
-                            else:
+                            else:  # direction in ["right", "left"]
                                 if direction == "right":
                                     edge = (
                                         boundary_element_hit.x1
@@ -338,7 +341,7 @@ class FlowElement:
 
                         if potential_hit:
                             boundary_element_hit = potential_hit
-                            if is_primary_vertical:
+                            if direction in ["below", "above"]:
                                 if direction == "below":
                                     edge = (
                                         boundary_element_hit.bottom
@@ -355,7 +358,7 @@ class FlowElement:
                                     bottom=edge if direction == "below" else None,
                                     top=edge if direction == "above" else None,
                                 )
-                            else:
+                            else:  # direction in ["right", "left"]
                                 if direction == "right":
                                     edge = (
                                         boundary_element_hit.x1
@@ -381,7 +384,7 @@ class FlowElement:
                 and size is not None
             ):
                 current_part_consumed_size = 0.0
-                if is_primary_vertical:
+                if direction in ["below", "above"]:
                     current_part_consumed_size = segment_contribution.height
                     if current_part_consumed_size > remaining_size:
                         new_edge = (
@@ -394,7 +397,7 @@ class FlowElement:
                             top=new_edge if not is_forward else None,
                         )
                         current_part_consumed_size = remaining_size
-                else:
+                else:  # direction in ["left", "right"]
                     current_part_consumed_size = segment_contribution.width
                     if current_part_consumed_size > remaining_size:
                         new_edge = (
@@ -451,6 +454,7 @@ class FlowElement:
         width_absolute: Optional[float] = None,
         width_alignment: str = "center",
         until: Optional[str] = None,
+        include_source: bool = False,
         include_endpoint: bool = True,
         **kwargs,
     ) -> "FlowRegion":  # Stringized
@@ -462,6 +466,7 @@ class FlowElement:
                 cross_size_absolute=width_absolute,
                 cross_alignment=width_alignment,
                 until=until,
+                include_source=include_source,
                 include_endpoint=include_endpoint,
                 **kwargs,
             )
@@ -477,6 +482,7 @@ class FlowElement:
         width_absolute: Optional[float] = None,
         width_alignment: str = "center",
         until: Optional[str] = None,
+        include_source: bool = False,
         include_endpoint: bool = True,
         **kwargs,
     ) -> "FlowRegion":  # Stringized
@@ -488,6 +494,7 @@ class FlowElement:
                 cross_size_absolute=width_absolute,
                 cross_alignment=width_alignment,
                 until=until,
+                include_source=include_source,
                 include_endpoint=include_endpoint,
                 **kwargs,
             )
@@ -503,24 +510,21 @@ class FlowElement:
         height_absolute: Optional[float] = None,
         height_alignment: str = "center",
         until: Optional[str] = None,
+        include_source: bool = False,
         include_endpoint: bool = True,
         **kwargs,
     ) -> "FlowRegion":  # Stringized
-        if self.flow.arrangement == "horizontal":
-            return self._flow_direction(
-                direction="left",
-                size=width,
-                cross_size_ratio=height_ratio,
-                cross_size_absolute=height_absolute,
-                cross_alignment=height_alignment,
-                until=until,
-                include_endpoint=include_endpoint,
-                **kwargs,
-            )
-        else:
-            raise NotImplementedError(
-                "'left' in a vertical flow is ambiguous with current 1D flow logic and not yet implemented."
-            )
+        return self._flow_direction(
+            direction="left",
+            size=width,
+            cross_size_ratio=height_ratio,
+            cross_size_absolute=height_absolute,
+            cross_alignment=height_alignment,
+            until=until,
+            include_source=include_source,
+            include_endpoint=include_endpoint,
+            **kwargs,
+        )
 
     def right(
         self,
@@ -529,24 +533,21 @@ class FlowElement:
         height_absolute: Optional[float] = None,
         height_alignment: str = "center",
         until: Optional[str] = None,
+        include_source: bool = False,
         include_endpoint: bool = True,
         **kwargs,
     ) -> "FlowRegion":  # Stringized
-        if self.flow.arrangement == "horizontal":
-            return self._flow_direction(
-                direction="right",
-                size=width,
-                cross_size_ratio=height_ratio,
-                cross_size_absolute=height_absolute,
-                cross_alignment=height_alignment,
-                until=until,
-                include_endpoint=include_endpoint,
-                **kwargs,
-            )
-        else:
-            raise NotImplementedError(
-                "'right' in a vertical flow is ambiguous with current 1D flow logic and not yet implemented."
-            )
+        return self._flow_direction(
+            direction="right",
+            size=width,
+            cross_size_ratio=height_ratio,
+            cross_size_absolute=height_absolute,
+            cross_alignment=height_alignment,
+            until=until,
+            include_source=include_source,
+            include_endpoint=include_endpoint,
+            **kwargs,
+        )
 
     def __repr__(self) -> str:
         return f"<FlowElement for {self.physical_object.__class__.__name__} {self.bbox} in {self.flow}>"