natural-pdf 0.2.16__py3-none-any.whl → 0.2.18__py3-none-any.whl

natural_pdf/elements/base.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Uni
 
 from PIL import Image
 
+# Import global options
+import natural_pdf
 from natural_pdf.classification.mixin import ClassificationMixin
 from natural_pdf.core.render_spec import RenderSpec, Visualizable
 from natural_pdf.describe.mixin import DescribeMixin
@@ -18,6 +20,7 @@ if TYPE_CHECKING:
     from natural_pdf.core.page import Page
     from natural_pdf.elements.element_collection import ElementCollection
     from natural_pdf.elements.region import Region
+    from natural_pdf.flows.region import FlowRegion
 
 
 def extract_bbox(obj: Any) -> Optional[Tuple[float, float, float, float]]:
@@ -93,6 +96,16 @@ class DirectionalMixin:
     - above(): Create region above
     - below(): Create region below
 
+    Smart defaults:
+    - left() and right() default to element height
+    - above() and below() default to full page width
+    - All methods use a small offset (default 0.01 points) to avoid character overlap
+
+    Global offset configuration:
+    The default offset can be changed globally:
+        import natural_pdf as npdf
+        npdf.options.layout.directional_offset = 0.05  # Change to 0.05 points
+
     Note:
         This mixin requires the implementing class to have 'page', 'x0', 'top',
         'x1', and 'bottom' attributes for coordinate calculations.
@@ -107,8 +120,10 @@ class DirectionalMixin:
         until: Optional[str] = None,
         include_endpoint: bool = True,
         offset: float = 0.0,
+        apply_exclusions: bool = True,
+        multipage: bool = False,
         **kwargs,
-    ) -> "Region":
+    ) -> Union["Region", "FlowRegion"]:
         """
         Protected helper method to create a region in a specified direction relative to this element/region.
 
@@ -119,7 +134,8 @@ class DirectionalMixin:
             include_source: Whether to include this element/region's area in the result
             until: Optional selector string to specify a boundary element
             include_endpoint: Whether to include the boundary element found by 'until'
-            offset: Pixel offset when excluding source/endpoint (default: 0.1)
+            offset: Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)
+            apply_exclusions: Whether to respect exclusions when using 'until' selector (default: True)
             **kwargs: Additional parameters for the 'until' selector search
 
         Returns:
@@ -189,21 +205,46 @@ class DirectionalMixin:
                 # Only take ones on the same page
                 all_matches = [m for m in until if m.page == self.page]
             else:
-                all_matches = self.page.find_all(until, **kwargs)
+                all_matches = self.page.find_all(until, apply_exclusions=apply_exclusions, **kwargs)
             matches_in_direction = []
 
             # Filter and sort matches based on direction
+            # Also filter by cross-direction bounds when cross_size='element'
             if direction == "above":
                 matches_in_direction = [m for m in all_matches if m.bottom <= self.top]
+                # Filter by horizontal bounds if cross_size='element'
+                if cross_size == "element":
+                    matches_in_direction = [
+                        m for m in matches_in_direction if m.x0 < self.x1 and m.x1 > self.x0
+                    ]
                 matches_in_direction.sort(key=lambda e: e.bottom, reverse=True)
             elif direction == "below":
                 matches_in_direction = [m for m in all_matches if m.top >= self.bottom]
+                # Filter by horizontal bounds if cross_size='element'
+                if cross_size == "element":
+                    matches_in_direction = [
+                        m for m in matches_in_direction if m.x0 < self.x1 and m.x1 > self.x0
+                    ]
                 matches_in_direction.sort(key=lambda e: e.top)
             elif direction == "left":
                 matches_in_direction = [m for m in all_matches if m.x1 <= self.x0]
+                # Filter by vertical bounds if cross_size='element'
+                if cross_size == "element":
+                    matches_in_direction = [
+                        m
+                        for m in matches_in_direction
+                        if m.top < self.bottom and m.bottom > self.top
+                    ]
                 matches_in_direction.sort(key=lambda e: e.x1, reverse=True)
             elif direction == "right":
                 matches_in_direction = [m for m in all_matches if m.x0 >= self.x1]
+                # Filter by vertical bounds if cross_size='element'
+                if cross_size == "element":
+                    matches_in_direction = [
+                        m
+                        for m in matches_in_direction
+                        if m.top < self.bottom and m.bottom > self.top
+                    ]
                 matches_in_direction.sort(key=lambda e: e.x0)
 
             if matches_in_direction:
@@ -243,7 +284,51 @@ class DirectionalMixin:
         final_y1 = max(bbox[1], bbox[3])
         final_bbox = (final_x0, final_y0, final_x1, final_y1)
 
-        # 5. Create and return appropriate object based on self type
+        # 5. Check if multipage is needed
+        # Use global default if not explicitly set
+        use_multipage = multipage
+        # If multipage is False but auto_multipage is True, use True
+        if not multipage and natural_pdf.options.layout.auto_multipage:
+            use_multipage = True
+
+        # Prevent recursion: if called with internal flag, don't use multipage
+        if kwargs.get("_from_flow", False):
+            use_multipage = False
+
+        if use_multipage:
+            # Check if we need to cross page boundaries
+            needs_multipage = False
+
+            # Case 1: until was specified but target not found on current page
+            if until and not target:
+                needs_multipage = True
+
+            # Case 2: size extends beyond page boundaries
+            if not until:
+                if direction == "below" and final_bbox[3] >= self.page.height:
+                    needs_multipage = True
+                elif direction == "above" and final_bbox[1] <= 0:
+                    needs_multipage = True
+                elif direction == "right" and final_bbox[2] >= self.page.width:
+                    needs_multipage = True
+                elif direction == "left" and final_bbox[0] <= 0:
+                    needs_multipage = True
+
+            if needs_multipage:
+                # Use multipage implementation
+                return self._direction_multipage(
+                    direction=direction,
+                    size=size,
+                    cross_size=cross_size,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    offset=offset,
+                    apply_exclusions=apply_exclusions,
+                    **kwargs,
+                )
+
+        # 6. Create and return appropriate object based on self type
         from natural_pdf.elements.region import Region
 
         result = Region(self.page, final_bbox)
@@ -255,6 +340,144 @@ class DirectionalMixin:
 
         return result
 
+    def _direction_multipage(
+        self,
+        direction: str,
+        size: Optional[float] = None,
+        cross_size: str = "full",
+        include_source: bool = False,
+        until: Optional[str] = None,
+        include_endpoint: bool = True,
+        offset: float = 0.0,
+        apply_exclusions: bool = True,
+        **kwargs,
+    ) -> Union["Region", "FlowRegion"]:
+        """
+        Handle multipage directional navigation by creating a Flow.
+
+        Returns FlowRegion if result spans multiple pages, Region if on single page.
+        """
+        # Get access to the PDF to create a Flow
+        pdf = self.page.pdf
+        # Find the index of the current page
+        current_page_idx = None
+        for idx, page in enumerate(pdf.pages):
+            if page == self.page:
+                current_page_idx = idx
+                break
+
+        if current_page_idx is None:
+            # Fallback - just use current page
+            from natural_pdf.flows.flow import Flow
+
+            flow = Flow(segments=[self.page], arrangement="vertical")
+            from natural_pdf.flows.element import FlowElement
+
+            flow_element = FlowElement(physical_object=self, flow=flow)
+            return getattr(flow_element, direction)(**kwargs)
+
+        # Determine which pages to include in the Flow based on direction
+        if direction in ("below", "right"):
+            # Include current page and all following pages
+            flow_pages = pdf.pages[current_page_idx:]
+        else:  # above, left
+            # Include all pages up to and including current page
+            flow_pages = pdf.pages[: current_page_idx + 1]
+
+        # Create a temporary Flow
+        from natural_pdf.flows.flow import Flow
+
+        flow = Flow(segments=list(flow_pages), arrangement="vertical")
+
+        # Find the element in the flow
+        # We need to create a FlowElement that corresponds to self
+        from natural_pdf.flows.element import FlowElement
+
+        flow_element = FlowElement(physical_object=self, flow=flow)
+
+        # Call the directional method on the FlowElement
+        # Remove parameters that FlowElement methods don't expect
+        flow_kwargs = kwargs.copy()
+        flow_kwargs.pop("multipage", None)  # Remove multipage parameter
+        flow_kwargs.pop("apply_exclusions", None)  # FlowElement might not have this
+        flow_kwargs.pop("offset", None)  # FlowElement doesn't have offset
+        flow_kwargs.pop("cross_alignment", None)  # Remove to avoid duplicate
+
+        # Map cross_size to appropriate FlowElement parameter
+        if direction in ["below", "above"]:
+            # For vertical directions, cross_size maps to width parameters
+            if cross_size == "full":
+                width_absolute = None  # Let FlowElement use its defaults
+            elif cross_size == "element":
+                width_absolute = self.width
+            elif isinstance(cross_size, (int, float)):
+                width_absolute = cross_size
+            else:
+                width_absolute = None
+
+            result = (
+                flow_element.below(
+                    height=size,
+                    width_absolute=width_absolute,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **flow_kwargs,
+                )
+                if direction == "below"
+                else flow_element.above(
+                    height=size,
+                    width_absolute=width_absolute,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **flow_kwargs,
+                )
+            )
+        else:  # left, right
+            # For horizontal directions, cross_size maps to height parameters
+            if cross_size == "full":
+                height_absolute = None  # Let FlowElement use its defaults
+            elif cross_size == "element":
+                height_absolute = self.height
+            elif isinstance(cross_size, (int, float)):
+                height_absolute = cross_size
+            else:
+                height_absolute = None
+
+            result = (
+                flow_element.left(
+                    width=size,
+                    height_absolute=height_absolute,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **flow_kwargs,
+                )
+                if direction == "left"
+                else flow_element.right(
+                    width=size,
+                    height_absolute=height_absolute,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **flow_kwargs,
+                )
+            )
+
+        # If the result is a FlowRegion with only one constituent region,
+        # return that Region instead
+        from natural_pdf.flows.region import FlowRegion
+
+        if isinstance(result, FlowRegion) and len(result.constituent_regions) == 1:
+            single_region = result.constituent_regions[0]
+            # Copy over any metadata
+            if hasattr(result, "boundary_element_found"):
+                single_region.boundary_element = result.boundary_element_found
+            return single_region
+
+        return result
+
     def above(
         self,
         height: Optional[float] = None,
@@ -262,9 +485,11 @@ class DirectionalMixin:
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
-        offset: float = 0.1,
+        offset: Optional[float] = None,
+        apply_exclusions: bool = True,
+        multipage: bool = False,
         **kwargs,
-    ) -> "Region":
+    ) -> Union["Region", "FlowRegion"]:
         """
         Select region above this element/region.
 
@@ -274,7 +499,10 @@ class DirectionalMixin:
             include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify an upper boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
-            offset: Pixel offset when excluding source/endpoint (default: 0.1)
+            offset: Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)
+            apply_exclusions: Whether to respect exclusions when using 'until' selector (default: True)
+            multipage: If True, allows the region to span multiple pages. Returns FlowRegion
+                     if the result spans multiple pages, Region otherwise (default: False)
             **kwargs: Additional parameters
 
         Returns:
@@ -292,6 +520,10 @@ class DirectionalMixin:
             signature.above(until='text:contains("Date")')  # Region from date to signature
             ```
         """
+        # Use global default if offset not provided
+        if offset is None:
+            offset = natural_pdf.options.layout.directional_offset
+
         return self._direction(
             direction="above",
             size=height,
@@ -300,6 +532,8 @@ class DirectionalMixin:
             until=until,
             include_endpoint=include_endpoint,
             offset=offset,
+            apply_exclusions=apply_exclusions,
+            multipage=multipage,
             **kwargs,
         )
 
@@ -310,9 +544,11 @@ class DirectionalMixin:
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
-        offset: float = 0.1,
+        offset: Optional[float] = None,
+        apply_exclusions: bool = True,
+        multipage: bool = False,
         **kwargs,
-    ) -> "Region":
+    ) -> Union["Region", "FlowRegion"]:
         """
         Select region below this element/region.
 
@@ -322,7 +558,10 @@ class DirectionalMixin:
             include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify a lower boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
-            offset: Pixel offset when excluding source/endpoint (default: 0.1)
+            multipage: If True, allows the region to span multiple pages. Returns FlowRegion
+                     if the result spans multiple pages, Region otherwise (default: False)
+            offset: Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)
+            apply_exclusions: Whether to respect exclusions when using 'until' selector (default: True)
             **kwargs: Additional parameters
 
         Returns:
@@ -340,6 +579,10 @@ class DirectionalMixin:
             header.below(height=200)  # Gets 200pt tall region below header
             ```
         """
+        # Use global default if offset not provided
+        if offset is None:
+            offset = natural_pdf.options.layout.directional_offset
+
         return self._direction(
             direction="below",
             size=height,
@@ -348,6 +591,8 @@ class DirectionalMixin:
             until=until,
             include_endpoint=include_endpoint,
             offset=offset,
+            apply_exclusions=apply_exclusions,
+            multipage=multipage,
             **kwargs,
         )
 
@@ -358,9 +603,11 @@ class DirectionalMixin:
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
-        offset: float = 0.1,
+        offset: Optional[float] = None,
+        apply_exclusions: bool = True,
+        multipage: bool = False,
         **kwargs,
-    ) -> "Region":
+    ) -> Union["Region", "FlowRegion"]:
         """
         Select region to the left of this element/region.
 
@@ -370,7 +617,10 @@ class DirectionalMixin:
             include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify a left boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
-            offset: Pixel offset when excluding source/endpoint (default: 0.1)
+            offset: Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)
+            apply_exclusions: Whether to respect exclusions when using 'until' selector (default: True)
+            multipage: If True, allows the region to span multiple pages. Returns FlowRegion
+                     if the result spans multiple pages, Region otherwise (default: False)
             **kwargs: Additional parameters
 
         Returns:
@@ -388,6 +638,10 @@ class DirectionalMixin:
             table.left(height=100)  # Gets 100pt tall region to the left
             ```
         """
+        # Use global default if offset not provided
+        if offset is None:
+            offset = natural_pdf.options.layout.directional_offset
+
         return self._direction(
             direction="left",
             size=width,
@@ -396,6 +650,8 @@ class DirectionalMixin:
             until=until,
             include_endpoint=include_endpoint,
             offset=offset,
+            apply_exclusions=apply_exclusions,
+            multipage=multipage,
             **kwargs,
         )
 
@@ -406,9 +662,11 @@ class DirectionalMixin:
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
-        offset: float = 0.1,
+        offset: Optional[float] = None,
+        apply_exclusions: bool = True,
+        multipage: bool = False,
         **kwargs,
-    ) -> "Region":
+    ) -> Union["Region", "FlowRegion"]:
         """
         Select region to the right of this element/region.
 
@@ -418,7 +676,10 @@ class DirectionalMixin:
             include_source: Whether to include this element/region in the result (default: False)
             until: Optional selector string to specify a right boundary element
             include_endpoint: Whether to include the boundary element in the region (default: True)
-            offset: Pixel offset when excluding source/endpoint (default: 0.1)
+            offset: Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)
+            apply_exclusions: Whether to respect exclusions when using 'until' selector (default: True)
+            multipage: If True, allows the region to span multiple pages. Returns FlowRegion
+                     if the result spans multiple pages, Region otherwise (default: False)
             **kwargs: Additional parameters
 
         Returns:
@@ -436,6 +697,10 @@ class DirectionalMixin:
             label.right(height=50)  # Gets 50pt tall region to the right
             ```
         """
+        # Use global default if offset not provided
+        if offset is None:
+            offset = natural_pdf.options.layout.directional_offset
+
         return self._direction(
             direction="right",
             size=width,
@@ -444,6 +709,8 @@ class DirectionalMixin:
             until=until,
             include_endpoint=include_endpoint,
             offset=offset,
+            apply_exclusions=apply_exclusions,
+            multipage=multipage,
             **kwargs,
         )
 
@@ -451,7 +718,7 @@ class DirectionalMixin:
         return self.expand()
 
     @overload
-    def expand(self, amount: float) -> "Region":
+    def expand(self, amount: float, *, apply_exclusions: bool = True) -> "Region":
         """Expand in all directions by the same amount."""
         ...
 
@@ -459,12 +726,13 @@ class DirectionalMixin:
     def expand(
         self,
         *,
-        left: float = 0,
-        right: float = 0,
-        top: float = 0,
-        bottom: float = 0,
+        left: Union[float, bool, str] = 0,
+        right: Union[float, bool, str] = 0,
+        top: Union[float, bool, str] = 0,
+        bottom: Union[float, bool, str] = 0,
         width_factor: float = 1.0,
         height_factor: float = 1.0,
+        apply_exclusions: bool = True,
     ) -> "Region":
         """Expand by different amounts in each direction."""
         ...
@@ -472,24 +740,29 @@ class DirectionalMixin:
     def expand(
         self,
         amount: Optional[float] = None,
-        left: float = 0,
-        right: float = 0,
-        top: float = 0,
-        bottom: float = 0,
+        left: Union[float, bool, str] = 0,
+        right: Union[float, bool, str] = 0,
+        top: Union[float, bool, str] = 0,
+        bottom: Union[float, bool, str] = 0,
         width_factor: float = 1.0,
         height_factor: float = 1.0,
+        apply_exclusions: bool = True,
     ) -> "Region":
         """
         Create a new region expanded from this element/region.
 
         Args:
             amount: If provided as the first positional argument, expand all edges by this amount
-            left: Amount to expand left edge (positive value expands leftwards)
-            right: Amount to expand right edge (positive value expands rightwards)
-            top: Amount to expand top edge (positive value expands upwards)
-            bottom: Amount to expand bottom edge (positive value expands downwards)
+            left: Amount to expand left edge:
+                - float: Fixed pixel expansion
+                - True: Expand to page edge
+                - str: Selector to expand until (excludes target by default, prefix with '+' to include)
+            right: Amount to expand right edge (same options as left)
+            top: Amount to expand top edge (same options as left)
+            bottom: Amount to expand bottom edge (same options as left)
             width_factor: Factor to multiply width by (applied after absolute expansion)
             height_factor: Factor to multiply height by (applied after absolute expansion)
+            apply_exclusions: Whether to respect exclusions when using selectors (default: True)
 
         Returns:
             New expanded Region object
@@ -501,31 +774,108 @@ class DirectionalMixin:
             # Expand by different amounts in each direction
             expanded = element.expand(left=10, right=5, top=3, bottom=7)
 
+            # Expand to page edges
+            expanded = element.expand(left=True, right=True)  # Full width
+
+            # Expand until specific elements
+            statute = page.find('text:contains("Statute")')
+            expanded = statute.expand(right='text:contains("Repeat?")')  # Excludes "Repeat?"
+            expanded = statute.expand(right='+text:contains("Repeat?")')  # Includes "Repeat?"
+
             # Use width/height factors
             expanded = element.expand(width_factor=1.5, height_factor=2.0)
         """
         # If amount is provided as first positional argument, use it for all directions
         if amount is not None:
             left = right = top = bottom = amount
-        # Start with current coordinates
-        new_x0 = self.x0
-        new_x1 = self.x1
-        new_top = self.top
-        new_bottom = self.bottom
-
-        # Apply absolute expansions first
-        new_x0 -= left
-        new_x1 += right
-        new_top -= top  # Expand upward (decrease top coordinate)
-        new_bottom += bottom  # Expand downward (increase bottom coordinate)
+
+        # Helper function to process expansion values
+        def process_expansion(value, direction):
+            """Process expansion value and return the new coordinate."""
+            is_horizontal = direction in ("left", "right")
+            is_positive = direction in ("right", "bottom")
+
+            # Get current bounds
+            if is_horizontal:
+                current_edge = self.x1 if is_positive else self.x0
+                page_limit = self.page.width if is_positive else 0
+            else:
+                current_edge = self.bottom if is_positive else self.top
+                page_limit = self.page.height if is_positive else 0
+
+            # Handle boolean True - expand to page edge
+            if value is True:
+                return page_limit
+
+            # Handle numeric values - fixed pixel expansion
+            elif isinstance(value, (int, float)):
+                if is_positive:
+                    return current_edge + value
+                else:
+                    return current_edge - value
+
+            # Handle string selectors - use directional methods
+            elif isinstance(value, str):
+                # Check if we should include the endpoint
+                include_endpoint = value.startswith("+")
+                selector = value[1:] if include_endpoint else value
+
+                # Use directional methods to get the region
+                if direction == "left":
+                    region = self.left(
+                        until=selector,
+                        include_endpoint=include_endpoint,
+                        include_source=True,
+                        apply_exclusions=apply_exclusions,
+                    )
+                    return region.x0
+                elif direction == "right":
+                    region = self.right(
+                        until=selector,
+                        include_endpoint=include_endpoint,
+                        include_source=True,
+                        apply_exclusions=apply_exclusions,
+                    )
+                    return region.x1
+                elif direction == "top":
+                    region = self.above(
+                        until=selector,
+                        include_endpoint=include_endpoint,
+                        include_source=True,
+                        width="element",
+                        apply_exclusions=apply_exclusions,
+                    )
+                    return region.top
+                elif direction == "bottom":
+                    region = self.below(
+                        until=selector,
+                        include_endpoint=include_endpoint,
+                        include_source=True,
+                        width="element",
+                        apply_exclusions=apply_exclusions,
+                    )
+                    return region.bottom
+
+                # Should not reach here
+                return current_edge
+
+            else:
+                # Invalid value type, return current edge
+                return current_edge
+
+        # Process each direction
+        new_x0 = process_expansion(left, "left") if left else self.x0
+        new_x1 = process_expansion(right, "right") if right else self.x1
+        new_top = process_expansion(top, "top") if top else self.top
+        new_bottom = process_expansion(bottom, "bottom") if bottom else self.bottom
 
         # Apply percentage factors if provided
         if width_factor != 1.0 or height_factor != 1.0:
-            # Calculate center point *after* absolute expansion
+            # Calculate center point *after* expansion
             center_x = (new_x0 + new_x1) / 2
             center_y = (new_top + new_bottom) / 2
 
-            # Calculate current width and height *after* absolute expansion
+            # Calculate current width and height *after* expansion
             current_width = new_x1 - new_x0
             current_height = new_bottom - new_top
 
@@ -1210,7 +1560,22 @@ class Element(
         return self
 
     def exclude(self):
-        self.page.add_exclusion(self)
+        """
+        Exclude this element from text extraction and other operations.
+
+        For Region elements, this excludes everything within the region's bounds.
+        For other elements (like TextElement), this excludes only the specific element,
+        not the entire area it occupies.
+        """
+        from natural_pdf.elements.region import Region
+
+        # Use 'region' method for Region objects, 'element' method for everything else
+        if isinstance(self, Region):
+            method = "region"
+        else:
+            method = "element"
+
+        self.page.add_exclusion(self, method=method)
 
     def _get_render_specs(
         self,