natural-pdf 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

natural_pdf/elements/base.py

@@ -2,13 +2,15 @@
 Base Element class for natural-pdf.
 """
 
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union, overload
 
 from PIL import Image
 
+# Import selector parsing functions
+from natural_pdf.selectors.parser import parse_selector, selector_to_filter_func
+
 if TYPE_CHECKING:
     from natural_pdf.core.page import Page
-    from natural_pdf.elements.base import Element
     from natural_pdf.elements.collections import ElementCollection
     from natural_pdf.elements.region import Region
 
@@ -135,19 +137,11 @@ class DirectionalMixin:
                 # Adjust cross boundaries if cross_size is 'element'
                 if cross_size == "element":
                     if is_horizontal:  # Adjust y0, y1
-                        target_y0 = (
-                            target.top if include_endpoint else target.bottom
-                        )  # Use opposite boundary if excluding
-                        target_y1 = target.bottom if include_endpoint else target.top
-                        y0 = min(y0, target_y0)
-                        y1 = max(y1, target_y1)
+                        y0 = min(y0, self.y0)
+                        y1 = max(y1, self.y1)
                     else:  # Adjust x0, x1
-                        target_x0 = (
-                            target.x0 if include_endpoint else target.x1
-                        )  # Use opposite boundary if excluding
-                        target_x1 = target.x1 if include_endpoint else target.x0
-                        x0 = min(x0, target_x0)
-                        x1 = max(x1, target_x1)
+                        x0 = min(x0, self.x0)
+                        x1 = max(x1, self.x1)
 
         # 4. Finalize bbox coordinates
         if is_horizontal:
@@ -525,7 +519,7 @@ class Element(DirectionalMixin):
             selector: Optional selector to filter by
             limit: Maximum number of elements to search through (default: 10)
             apply_exclusions: Whether to apply exclusion regions (default: True)
-            **kwargs: Additional parameters
+            **kwargs: Additional parameters for selector filtering (e.g., regex, case)
 
         Returns:
             Next element or None if not found
@@ -548,13 +542,19 @@ class Element(DirectionalMixin):
             # Limit search range for performance
             candidates = candidates[:limit] if limit else candidates
 
-            # Find matching elements
-            from natural_pdf.elements.collections import ElementCollection
+            # Parse the selector and create a filter function
+            parsed_selector = parse_selector(selector)
+            # Pass relevant kwargs (like regex, case) to the filter function builder
+            filter_func = selector_to_filter_func(parsed_selector, **kwargs)
+
+            # Iterate and return the first match
+            for candidate in candidates:
+                if filter_func(candidate):
+                    return candidate
+            return None  # No match found
 
-            matches = ElementCollection(candidates).find_all(selector, **kwargs)
-            return matches[0] if matches else None
+        # No selector, just return the next element if it exists
         elif idx + 1 < len(all_elements):
-            # No selector, just return the next element
             return all_elements[idx + 1]
 
         return None
@@ -573,7 +573,7 @@ class Element(DirectionalMixin):
             selector: Optional selector to filter by
             limit: Maximum number of elements to search through (default: 10)
             apply_exclusions: Whether to apply exclusion regions (default: True)
-            **kwargs: Additional parameters
+            **kwargs: Additional parameters for selector filtering (e.g., regex, case)
 
         Returns:
             Previous element or None if not found
@@ -598,13 +598,19 @@ class Element(DirectionalMixin):
             # Limit search range for performance
             candidates = candidates[:limit] if limit else candidates
 
-            # Find matching elements using ElementCollection
-            from natural_pdf.elements.collections import ElementCollection
+            # Parse the selector and create a filter function
+            parsed_selector = parse_selector(selector)
+            # Pass relevant kwargs (like regex, case) to the filter function builder
+            filter_func = selector_to_filter_func(parsed_selector, **kwargs)
+
+            # Iterate and return the first match (from reversed list)
+            for candidate in candidates:
+                if filter_func(candidate):
+                    return candidate
+            return None  # No match found
 
-            matches = ElementCollection(candidates).find_all(selector, **kwargs)
-            return matches[0] if matches else None  # find_all returns a collection
+        # No selector, just return the previous element if it exists
         elif idx > 0:
-            # No selector, just return the previous element
             return all_elements[idx - 1]
 
         return None
@@ -887,40 +893,128 @@ class Element(DirectionalMixin):
         """String representation of the element."""
         return f"<{self.__class__.__name__} bbox={self.bbox}>"
 
-    def find(self, selector: str, apply_exclusions=True, **kwargs) -> Optional["Element"]:
+    @overload
+    def find(
+        self,
+        *,
+        text: str,
+        apply_exclusions: bool = True,
+        regex: bool = False,
+        case: bool = True,
+        **kwargs,
+    ) -> Optional["Element"]: ...
+
+    @overload
+    def find(
+        self,
+        selector: str,
+        *,
+        apply_exclusions: bool = True,
+        regex: bool = False,
+        case: bool = True,
+        **kwargs,
+    ) -> Optional["Element"]: ...
+
+    def find(
+        self,
+        selector: Optional[str] = None,
+        *,
+        text: Optional[str] = None,
+        apply_exclusions: bool = True,
+        regex: bool = False,
+        case: bool = True,
+        **kwargs,
+    ) -> Optional["Element"]:
         """
-        Find first element within this element's bounds matching the selector.
+        Find first element within this element's bounds matching the selector OR text.
         Creates a temporary region to perform the search.
 
+        Provide EITHER `selector` OR `text`, but not both.
+
         Args:
-            selector: CSS-like selector string
-            apply_exclusions: Whether to apply exclusion regions
-            **kwargs: Additional parameters for element filtering
+            selector: CSS-like selector string.
+            text: Text content to search for (equivalent to 'text:contains(...)').
+            apply_exclusions: Whether to apply exclusion regions (default: True).
+            regex: Whether to use regex for text search (`selector` or `text`) (default: False).
+            case: Whether to do case-sensitive text search (`selector` or `text`) (default: True).
+            **kwargs: Additional parameters for element filtering.
 
         Returns:
-            First matching element or None
+            First matching element or None.
         """
         from natural_pdf.elements.region import Region
 
         # Create a temporary region from this element's bounds
         temp_region = Region(self.page, self.bbox)
-        return temp_region.find(selector, apply_exclusions=apply_exclusions, **kwargs)
+        # Delegate to the region's find method
+        return temp_region.find(
+            selector=selector,
+            text=text,
+            apply_exclusions=apply_exclusions,
+            regex=regex,
+            case=case,
+            **kwargs,
+        )
+
+    @overload
+    def find_all(
+        self,
+        *,
+        text: str,
+        apply_exclusions: bool = True,
+        regex: bool = False,
+        case: bool = True,
+        **kwargs,
+    ) -> "ElementCollection": ...
+
+    @overload
+    def find_all(
+        self,
+        selector: str,
+        *,
+        apply_exclusions: bool = True,
+        regex: bool = False,
+        case: bool = True,
+        **kwargs,
+    ) -> "ElementCollection": ...
 
-    def find_all(self, selector: str, apply_exclusions=True, **kwargs) -> "ElementCollection":
+    def find_all(
+        self,
+        selector: Optional[str] = None,
+        *,
+        text: Optional[str] = None,
+        apply_exclusions: bool = True,
+        regex: bool = False,
+        case: bool = True,
+        **kwargs,
+    ) -> "ElementCollection":
         """
-        Find all elements within this element's bounds matching the selector.
+        Find all elements within this element's bounds matching the selector OR text.
         Creates a temporary region to perform the search.
 
+        Provide EITHER `selector` OR `text`, but not both.
+
         Args:
-            selector: CSS-like selector string
-            apply_exclusions: Whether to apply exclusion regions
-            **kwargs: Additional parameters for element filtering
+            selector: CSS-like selector string.
+            text: Text content to search for (equivalent to 'text:contains(...)').
+            apply_exclusions: Whether to apply exclusion regions (default: True).
+            regex: Whether to use regex for text search (`selector` or `text`) (default: False).
+            case: Whether to do case-sensitive text search (`selector` or `text`) (default: True).
+            **kwargs: Additional parameters for element filtering.
 
         Returns:
-            ElementCollection with matching elements
+            ElementCollection with matching elements.
         """
         from natural_pdf.elements.region import Region
 
         # Create a temporary region from this element's bounds
         temp_region = Region(self.page, self.bbox)
-        return temp_region.find_all(selector, apply_exclusions=apply_exclusions, **kwargs)
+        # Delegate to the region's find_all method
+        return temp_region.find_all(
+            selector=selector,
+            text=text,
+            apply_exclusions=apply_exclusions,
+            regex=regex,
+            case=case,
+            **kwargs,
+        )