natural-pdf 0.2.1.dev0__py3-none-any.whl → 0.2.3__py3-none-any.whl

natural_pdf/elements/base.py

@@ -260,7 +260,7 @@ class DirectionalMixin:
 
         Args:
             height: Height of the region above, in points
-            width: Width mode - "full" for full page width or "element" for element width
+            width: Width mode - "full" (default) for full page width or "element" for element width
             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)
@@ -268,6 +268,18 @@ class DirectionalMixin:
 
         Returns:
             Region object representing the area above
+
+        Examples:
+            ```python
+            # Default: full page width
+            signature.above()  # Gets everything above across full page width
+
+            # Match element width
+            signature.above(width='element')  # Gets region above matching signature width
+
+            # Stop at specific element
+            signature.above(until='text:contains("Date")')  # Region from date to signature
+            ```
         """
         return self._direction(
             direction="above",
@@ -293,7 +305,7 @@ class DirectionalMixin:
 
         Args:
             height: Height of the region below, in points
-            width: Width mode - "full" for full page width or "element" for element width
+            width: Width mode - "full" (default) for full page width or "element" for element width
             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)
@@ -301,6 +313,18 @@ class DirectionalMixin:
 
         Returns:
             Region object representing the area below
+
+        Examples:
+            ```python
+            # Default: full page width
+            header.below()  # Gets everything below across full page width
+
+            # Match element width
+            header.below(width='element')  # Gets region below matching header width
+
+            # Limited height
+            header.below(height=200)  # Gets 200pt tall region below header
+            ```
         """
         return self._direction(
             direction="below",
@@ -315,7 +339,7 @@ class DirectionalMixin:
     def left(
         self,
         width: Optional[float] = None,
-        height: str = "full",
+        height: str = "element",
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
@@ -326,7 +350,7 @@ class DirectionalMixin:
 
         Args:
             width: Width of the region to the left, in points
-            height: Height mode - "full" for full page height or "element" for element height
+            height: Height mode - "element" (default) for element height or "full" for full page height
             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)
@@ -334,6 +358,18 @@ class DirectionalMixin:
 
         Returns:
             Region object representing the area to the left
+
+        Examples:
+            ```python
+            # Default: matches element height
+            table.left()  # Gets region to the left at same height as table
+
+            # Full page height
+            table.left(height='full')  # Gets entire left side of page
+
+            # Custom height
+            table.left(height=100)  # Gets 100pt tall region to the left
+            ```
         """
         return self._direction(
             direction="left",
@@ -348,7 +384,7 @@ class DirectionalMixin:
     def right(
         self,
         width: Optional[float] = None,
-        height: str = "full",
+        height: str = "element",
         include_source: bool = False,
         until: Optional[str] = None,
         include_endpoint: bool = True,
@@ -359,7 +395,7 @@ class DirectionalMixin:
 
         Args:
             width: Width of the region to the right, in points
-            height: Height mode - "full" for full page height or "element" for element height
+            height: Height mode - "element" (default) for element height or "full" for full page height
             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)
@@ -367,6 +403,18 @@ class DirectionalMixin:
 
         Returns:
             Region object representing the area to the right
+
+        Examples:
+            ```python
+            # Default: matches element height
+            label.right()  # Gets region to the right at same height as label
+
+            # Full page height
+            label.right(height='full')  # Gets entire right side of page
+
+            # Custom height
+            label.right(height=50)  # Gets 50pt tall region to the right
+            ```
         """
         return self._direction(
             direction="right",
@@ -381,8 +429,28 @@ class DirectionalMixin:
     def to_region(self):
         return self.expand()
 
+    @overload
+    def expand(self, amount: float) -> "Region":
+        """Expand in all directions by the same amount."""
+        ...
+
+    @overload
+    def expand(
+        self,
+        *,
+        left: float = 0,
+        right: float = 0,
+        top: float = 0,
+        bottom: float = 0,
+        width_factor: float = 1.0,
+        height_factor: float = 1.0,
+    ) -> "Region":
+        """Expand by different amounts in each direction."""
+        ...
+
     def expand(
         self,
+        amount: Optional[float] = None,
         left: float = 0,
         right: float = 0,
         top: float = 0,
@@ -394,6 +462,7 @@ class DirectionalMixin:
         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)
@@ -403,7 +472,20 @@ class DirectionalMixin:
 
         Returns:
             New expanded Region object
+
+        Examples:
+            # Expand 5 pixels in all directions
+            expanded = element.expand(5)
+
+            # Expand by different amounts in each direction
+            expanded = element.expand(left=10, right=5, top=3, bottom=7)
+
+            # 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
@@ -1212,7 +1294,7 @@ class Element(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1224,7 +1306,7 @@ class Element(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1236,7 +1318,7 @@ class Element(
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1251,9 +1333,9 @@ class Element(
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
-            contains: How to determine if elements are inside: 'all' (fully inside),
-                     'any' (any overlap), or 'center' (center point inside).
-                     (default: "all")
+            overlap: How to determine if elements overlap with this element: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             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).
@@ -1270,7 +1352,7 @@ class Element(
         return temp_region.find(
             selector=selector,
             text=text,
-            contains=contains,
+            overlap=overlap,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,
@@ -1282,7 +1364,7 @@ class Element(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1294,7 +1376,7 @@ class Element(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1306,7 +1388,7 @@ class Element(
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1321,9 +1403,9 @@ class Element(
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
-            contains: How to determine if elements are inside: 'all' (fully inside),
-                     'any' (any overlap), or 'center' (center point inside).
-                     (default: "all")
+            overlap: How to determine if elements overlap with this element: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             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).
@@ -1340,7 +1422,7 @@ class Element(
         return temp_region.find_all(
             selector=selector,
             text=text,
-            contains=contains,
+            overlap=overlap,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,

natural_pdf/elements/element_collection.py

@@ -891,6 +891,7 @@ class ElementCollection(
         label_format: Optional[str] = None,
         annotate: Optional[List[str]] = None,
         bins: Optional[Union[int, List[float]]] = None,
+        **kwargs,
     ) -> List[Dict]:
         """
         Determines the parameters for highlighting each element based on the strategy.
@@ -1672,9 +1673,9 @@ class ElementCollection(
 
         Args:
             selector: CSS-like selector string
-            contains: How to determine if elements are inside: 'all' (fully inside),
-                      'any' (any overlap), or 'center' (center point inside).
-                      (default: "all")
+            overlap: How to determine if elements overlap: 'full' (fully inside),
+                      'partial' (any overlap), or 'center' (center point inside).
+                      (default: "full")
             apply_exclusions: Whether to exclude elements in exclusion regions
         """
         return self.apply(lambda element: element.find(selector, **kwargs))
@@ -1684,7 +1685,7 @@ class ElementCollection(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1696,7 +1697,7 @@ class ElementCollection(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1708,7 +1709,7 @@ class ElementCollection(
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1723,9 +1724,9 @@ class ElementCollection(
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
-            contains: How to determine if elements are inside: 'all' (fully inside),
-                     'any' (any overlap), or 'center' (center point inside).
-                     (default: "all")
+            overlap: How to determine if elements overlap: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             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).
@@ -1747,7 +1748,7 @@ class ElementCollection(
                 found_in_element: "ElementCollection" = element.find_all(
                     selector=selector,
                     text=text,
-                    contains=contains,
+                    overlap=overlap,
                     apply_exclusions=apply_exclusions,
                     regex=regex,
                     case=case,

natural_pdf/elements/region.py

@@ -960,7 +960,7 @@ class Region(
         right_content_col = min(width - 1, content_col_indices[-1] + padding)
 
         # Convert trimmed pixel coordinates back to PDF coordinates
-        scale_factor = resolution / 72.0  # Scale factor used in to_image()
+        scale_factor = resolution / 72.0  # Scale factor used in render()
 
         # Calculate new PDF coordinates and ensure they are Python floats
         trimmed_x0 = float(work_region.x0 + (left_content_col / scale_factor))
@@ -1982,7 +1982,7 @@ class Region(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1994,7 +1994,7 @@ class Region(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2006,7 +2006,7 @@ class Region(
         selector: Optional[str] = None,  # Now optional
         *,
         text: Optional[str] = None,  # New text parameter
-        contains: str = "all",  # New parameter for containment behavior
+        overlap: str = "full",  # How elements overlap with the region
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2020,9 +2020,9 @@ class Region(
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
-            contains: How to determine if elements are inside: 'all' (fully inside),
-                     'any' (any overlap), or 'center' (center point inside).
-                     (default: "all")
+            overlap: How to determine if elements overlap with the region: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             apply_exclusions: Whether to exclude elements in 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).
@@ -2035,7 +2035,7 @@ class Region(
         elements = self.find_all(
             selector=selector,
             text=text,
-            contains=contains,
+            overlap=overlap,
             apply_exclusions=apply_exclusions,
             regex=regex,
             case=case,
@@ -2048,7 +2048,7 @@ class Region(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2060,7 +2060,7 @@ class Region(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2072,7 +2072,7 @@ class Region(
         selector: Optional[str] = None,  # Now optional
         *,
         text: Optional[str] = None,  # New text parameter
-        contains: str = "all",  # New parameter to control inside/overlap behavior
+        overlap: str = "full",  # How elements overlap with the region
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -2086,9 +2086,9 @@ class Region(
         Args:
             selector: CSS-like selector string.
             text: Text content to search for (equivalent to 'text:contains(...)').
-            contains: How to determine if elements are inside: 'all' (fully inside),
-                     'any' (any overlap), or 'center' (center point inside).
-                     (default: "all")
+            overlap: How to determine if elements overlap with the region: 'full' (fully inside),
+                     'partial' (any overlap), or 'center' (center point inside).
+                     (default: "full")
             apply_exclusions: Whether to exclude elements in 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).
@@ -2104,10 +2104,10 @@ class Region(
         if selector is None and text is None:
             raise ValueError("Provide either 'selector' or 'text'.")
 
-        # Validate contains parameter
-        if contains not in ["all", "any", "center"]:
+        # Validate overlap parameter
+        if overlap not in ["full", "partial", "center"]:
             raise ValueError(
-                f"Invalid contains value: {contains}. Must be 'all', 'any', or 'center'"
+                f"Invalid overlap value: {overlap}. Must be 'full', 'partial', or 'center'"
             )
 
         # Construct selector if 'text' is provided
@@ -2142,7 +2142,7 @@ class Region(
             region_bbox = self.bbox
             matching_elements = []
 
-            if contains == "all":  # Fully inside (strict)
+            if overlap == "full":  # Fully inside (strict)
                 matching_elements = [
                     el
                     for el in potential_elements
@@ -2151,9 +2151,9 @@ class Region(
                     and el.x1 <= region_bbox[2]
                     and el.bottom <= region_bbox[3]
                 ]
-            elif contains == "any":  # Any overlap
+            elif overlap == "partial":  # Any overlap
                 matching_elements = [el for el in potential_elements if self.intersects(el)]
-            elif contains == "center":  # Center point inside
+            elif overlap == "center":  # Center point inside
                 matching_elements = [
                     el for el in potential_elements if self.is_element_center_inside(el)
                 ]
@@ -3437,7 +3437,7 @@ class Region(
                     r_idx = int(cell.metadata.get("row_index"))
                     c_idx = int(cell.metadata.get("col_index"))
                     text_val = cell.extract_text(
-                        layout=False, apply_exclusions=False, content_filter=content_filter
+                        layout=False, apply_exclusions=True, content_filter=content_filter
                     ).strip()
                     table_grid[r_idx][c_idx] = text_val if text_val else None
                 except Exception as _err:

natural_pdf/elements/text.py

@@ -215,6 +215,11 @@ class TextElement(Element):
         if isinstance(color, (int, float)):
             return (color, color, color)
 
+        # If it's a single-value tuple (grayscale), treat as grayscale
+        if isinstance(color, tuple) and len(color) == 1:
+            gray = color[0]
+            return (gray, gray, gray)
+
         # If it's a tuple of 3 values, treat as RGB
         if isinstance(color, tuple) and len(color) == 3:
             return color

natural_pdf/extraction/manager.py

@@ -119,17 +119,11 @@ class StructuredDataManager:
         )
         messages = self._prepare_llm_messages(content, prompt, using, schema)
 
-        try:
-            logger.debug(f"Extracting with model '{selected_model}'")
-            completion = client.beta.chat.completions.parse(
-                model=selected_model, messages=messages, response_format=schema, **kwargs
-            )
-            parsed_data = completion.choices[0].message.parsed
-            return StructuredDataResult(
-                data=parsed_data, success=True, error_message=None, model_used=selected_model
-            )
-        except Exception as e:
-            logger.error(f"Extraction failed: {str(e)}")
-            return StructuredDataResult(
-                data=None, success=False, error_message=str(e), model_used=selected_model
-            )
+        logger.debug(f"Extracting with model '{selected_model}'")
+        completion = client.beta.chat.completions.parse(
+            model=selected_model, messages=messages, response_format=schema, **kwargs
+        )
+        parsed_data = completion.choices[0].message.parsed
+        return StructuredDataResult(
+            data=parsed_data, success=True, error_message=None, model_used=selected_model
+        )

natural_pdf/extraction/mixin.py

@@ -35,7 +35,7 @@ class ExtractionMixin(ABC):
 
     Host class requirements:
     - Must implement extract_text(**kwargs) -> str
-    - Must implement to_image(**kwargs) -> PIL.Image
+    - Must implement render(**kwargs) -> PIL.Image
     - Must have access to StructuredDataManager (usually via parent PDF)
 
     Example:
@@ -72,25 +72,24 @@ class ExtractionMixin(ABC):
 
         Args:
             using: 'text' or 'vision'
-            **kwargs: Additional arguments passed to extract_text or to_image
+            **kwargs: Additional arguments passed to extract_text or render
 
         Returns:
             str: Extracted text if using='text'
             PIL.Image.Image: Rendered image if using='vision'
             None: If content cannot be retrieved
         """
-        if not hasattr(self, "extract_text") or not callable(self.extract_text):
-            logger.error(f"ExtractionMixin requires 'extract_text' method on {self!r}")
-            return None
-        if not hasattr(self, "to_image") or not callable(self.to_image):
-            logger.error(f"ExtractionMixin requires 'to_image' method on {self!r}")
-            return None
-
         try:
             if using == "text":
+                if not hasattr(self, "extract_text") or not callable(self.extract_text):
+                    logger.error(f"ExtractionMixin requires 'extract_text' method on {self!r}")
+                    return None
                 layout = kwargs.pop("layout", True)
                 return self.extract_text(layout=layout, **kwargs)
             elif using == "vision":
+                if not hasattr(self, "render") or not callable(self.render):
+                    logger.error(f"ExtractionMixin requires 'render' method on {self!r}")
+                    return None
                 resolution = kwargs.pop("resolution", 72)
                 include_highlights = kwargs.pop("include_highlights", False)
                 labels = kwargs.pop("labels", False)
@@ -102,8 +101,13 @@ class ExtractionMixin(ABC):
                 logger.error(f"Unsupported value for 'using': {using}")
                 return None
         except Exception as e:
-            logger.error(f"Error getting {using} content from {self!r}: {e}")
-            return None
+            import warnings
+
+            warnings.warn(
+                f"Error getting {using} content from {self!r}: {e}",
+                RuntimeWarning,
+            )
+            raise
 
     def extract(
         self: Any,
@@ -275,10 +279,7 @@ class ExtractionMixin(ABC):
             raise RuntimeError("StructuredDataManager is not available")
 
         # Get content
-        layout_for_text = kwargs.pop("layout", True)
-        content = self._get_extraction_content(
-            using=using, layout=layout_for_text, **kwargs
-        )  # Pass kwargs
+        content = self._get_extraction_content(using=using, **kwargs)  # Pass kwargs
 
         if content is None or (
             using == "text" and isinstance(content, str) and not content.strip()
@@ -359,10 +360,11 @@ class ExtractionMixin(ABC):
             )
 
         if not result.success:
-            raise ValueError(
-                f"Stored result for '{target_key}' indicates a failed extraction attempt. "
-                f"Error: {result.error_message}"
+            # Return None for failed extractions to allow batch processing to continue
+            logger.warning(
+                f"Extraction '{target_key}' failed: {result.error_message}. Returning None."
             )
+            return None
 
         if result.data is None:
             # This case might occur if success=True but data is somehow None
@@ -591,16 +593,28 @@ class ExtractionMixin(ABC):
             raise RuntimeError("StructuredDataManager is not available")
 
         # Content preparation
-        layout_for_text = kwargs.pop("layout", True)
-        content = self._get_extraction_content(using=using, layout=layout_for_text, **kwargs)
+        content = self._get_extraction_content(using=using, **kwargs)
+
+        import warnings
 
         if content is None or (
             using == "text" and isinstance(content, str) and not content.strip()
         ):
+            preview = None
+            if isinstance(content, str):
+                preview = content[:120]
+            msg = (
+                f"No content available for extraction (using='{using}'). "
+                "Ensure the page has a text layer or render() returns an image. "
+                "For scanned PDFs run apply_ocr() or switch to using='vision'. "
+                f"Content preview: {preview!r}"
+            )
+            warnings.warn(msg, RuntimeWarning)
+
             result = StructuredDataResult(
                 data=None,
                 success=False,
-                error_message=f"No content available for extraction (using='{using}')",
+                error_message=msg,
                 model_used=model,
             )
         else:

natural_pdf/selectors/parser.py

@@ -721,8 +721,8 @@ def _build_filter_list(selector: Dict[str, Any], **kwargs) -> List[Dict[str, Any
         # Start with a base name, modify for specifics like :not
         filter_name = f"pseudo-class :{name}"
 
-        # Relational pseudo-classes are handled separately by the caller
-        if name in ("above", "below", "near", "left-of", "right-of"):
+        # Relational pseudo-classes and collection-level pseudo-classes are handled separately by the caller
+        if name in ("above", "below", "near", "left-of", "right-of", "first", "last"):
             continue
 
         # --- Handle :not() ---