natural-pdf 0.2.2__tar.gz → 0.2.3__tar.gz

{natural_pdf-0.2.2/natural_pdf.egg-info → natural_pdf-0.2.3}/PKG-INFO

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

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/docs/quick-reference/index.md

@@ -156,11 +156,25 @@ elements.show(color="red")                      # Single collection
 elements.show(color="blue", label="Headers")    # With label
 elements.show(group_by='type')                  # Color by type
 
-# Multiple collections together
+# Quick highlighting (one-liner)
+page.highlight(elements1, elements2, elements3)  # Multiple elements
+page.highlight(                                  # With custom colors
+    (elements1, 'red'),
+    (elements2, 'blue'),
+    (elements3, 'green')
+)
+
+# Multiple collections with context manager
 with page.highlights() as h:
     h.add(elements1, color="red", label="Type 1")
     h.add(elements2, color="blue", label="Type 2")
     h.show()
+
+# Auto-display in Jupyter/Colab
+with page.highlights(show=True) as h:
+    h.add(elements1, label="Headers")
+    h.add(elements2, label="Content")
+    # Displays automatically when exiting context
 ```
 
 ### Viewing

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/docs/visual-debugging/index.md

@@ -83,6 +83,47 @@ with page.highlights() as h:
     h.show()
 ```
 
+### Jupyter/Colab Support
+
+In Jupyter notebooks and Google Colab, you can use `show=True` to automatically display the highlights when exiting the context:
+
+```python
+# Automatically displays the image in Jupyter/Colab
+with page.highlights(show=True) as h:
+    h.add(summary_elements, label='Summary')
+    h.add(date_elements, label='Date')
+    h.add(line_elements, label='Lines')
+    # No need to call h.show() - displays automatically!
+```
+
+### Quick Highlighting with `.highlight()`
+
+For simple highlighting tasks, use the `.highlight()` convenience method:
+
+```python
+# Highlight multiple elements in one line
+page.highlight(summary_elements, date_elements, line_elements)
+
+# With custom colors
+page.highlight(
+    (summary_elements, 'red'),
+    (date_elements, 'blue'),
+    (line_elements, 'green')
+)
+
+# With colors and labels
+page.highlight(
+    (summary_elements, 'red', 'Summary Text'),
+    (date_elements, 'blue', 'Date Fields'),
+    (line_elements, 'green', 'Separator Lines')
+)
+
+# Pass additional parameters like width or resolution
+page.highlight(summary_elements, date_elements, width=800, labels=True)
+```
+
+This method is particularly useful in Jupyter/Colab environments where the image displays automatically as the cell output.
+
 ## Customizing Multiple Highlights
 
 Customize the appearance of multiple highlights using the context manager:
@@ -133,7 +174,7 @@ content = title.below(height=200)
 content.show()
 ```
 
-Or look at just the region by itself
+Or look at just the region by itself:
 
 ```python
 # Find a title and create a region below it
@@ -144,6 +185,27 @@ content = title.below(height=200)
 content.show(crop=True)
 ```
 
+### Highlighting Multiple Regions
+
+The `.highlight()` method works with regions too:
+
+```python
+# Create multiple regions
+left = page.region(left=0, right=page.width/3, top=0, bottom=page.height)
+mid = page.region(left=page.width/3, right=page.width/3*2, top=0, bottom=page.height)
+right = page.region(left=page.width/3*2, right=page.width, top=0, bottom=page.height)
+
+# Highlight all three regions
+page.highlight(left, mid, right)
+
+# Or with custom colors
+page.highlight(
+    (left, 'red', 'Left Column'),
+    (mid, 'green', 'Middle Column'),
+    (right, 'blue', 'Right Column')
+)
+```
+
 ## Working with Text Styles
 
 Visualize text styles to understand the document structure:

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/natural_pdf/collections/mixins.py

@@ -29,9 +29,22 @@ class DirectionalCollectionMixin:
         """Find regions to the right of all elements in this collection."""
         return self.apply(lambda element: element.right(**kwargs))
 
-    def expand(self, **kwargs) -> "ElementCollection":
-        """Expand all elements in this collection."""
-        return self.apply(lambda element: element.expand(**kwargs))
+    def expand(self, *args, **kwargs) -> "ElementCollection":
+        """Expand all elements in this collection.
+
+        Args:
+            *args: If a single positional argument is provided, expands all elements
+                   by that amount in all directions.
+            **kwargs: Keyword arguments for directional expansion (left, right, top, bottom, etc.)
+
+        Examples:
+            # Expand all elements by 5 pixels in all directions
+            collection.expand(5)
+
+            # Expand with different amounts in each direction
+            collection.expand(left=10, right=5, top=3, bottom=7)
+        """
+        return self.apply(lambda element: element.expand(*args, **kwargs))
 
 
 class ApplyMixin:

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/natural_pdf/core/highlighting_service.py

@@ -335,6 +335,7 @@ class HighlightContext:
         self.show_on_exit = show_on_exit
         self.highlight_groups = []
         self._color_manager = ColorManager()
+        self._exit_image = None  # Store image for Jupyter display
 
     def add(
         self,
@@ -421,6 +422,11 @@ class HighlightContext:
             )
             return None
 
+    @property
+    def image(self) -> Optional[Image.Image]:
+        """Get the last generated image (useful after context exit)."""
+        return self._exit_image
+
     def __enter__(self) -> "HighlightContext":
         """Enter the context."""
         return self
@@ -428,7 +434,25 @@ class HighlightContext:
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Exit the context, optionally showing highlights."""
         if self.show_on_exit and not exc_type:
-            self.show()
+            self._exit_image = self.show()
+
+            # Check if we're in a Jupyter/IPython environment
+            try:
+                # Try to get IPython instance
+                from IPython import get_ipython
+
+                ipython = get_ipython()
+                if ipython is not None:
+                    # We're in IPython/Jupyter
+                    from IPython.display import display
+
+                    if self._exit_image is not None:
+                        display(self._exit_image)
+            except (ImportError, NameError):
+                # Not in Jupyter or IPython not available - that's OK
+                pass
+
+        # __exit__ must return False to not suppress exceptions
         return False
 
 

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/natural_pdf/core/page.py

@@ -1976,7 +1976,7 @@ class Page(
         """Get all line elements on this page."""
         return self._element_mgr.lines
 
-    def highlight(
+    def add_highlight(
         self,
         bbox: Optional[Tuple[float, float, float, float]] = None,
         color: Optional[Union[Tuple, str]] = None,
@@ -1987,7 +1987,7 @@ class Page(
         existing: str = "append",
     ) -> "Page":
         """
-        Highlight a bounding box or the entire page.
+        Add a highlight to a bounding box or the entire page.
         Delegates to the central HighlightingService.
 
         Args:
@@ -2015,7 +2015,7 @@ class Page(
         )
         return self
 
-    def highlight_polygon(
+    def add_highlight_polygon(
         self,
         polygon: List[Tuple[float, float]],
         color: Optional[Union[Tuple, str]] = None,

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/natural_pdf/core/page_collection.py

@@ -259,7 +259,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -271,7 +271,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -283,7 +283,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -297,9 +297,9 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         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 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).
@@ -313,7 +313,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
             element = page.find(
                 selector=selector,
                 text=text,
-                contains=contains,
+                overlap=overlap,
                 apply_exclusions=apply_exclusions,
                 regex=regex,
                 case=case,
@@ -328,7 +328,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -340,7 +340,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -352,7 +352,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         selector: Optional[str] = None,
         *,
         text: Optional[str] = None,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -366,9 +366,9 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
         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 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).
@@ -383,7 +383,7 @@ class PageCollection(TextMixin, Generic[P], ApplyMixin, ShapeDetectionMixin, Vis
             elements = page.find_all(
                 selector=selector,
                 text=text,
-                contains=contains,
+                overlap=overlap,
                 apply_exclusions=apply_exclusions,
                 regex=regex,
                 case=case,

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/natural_pdf/core/render_spec.py

@@ -92,6 +92,50 @@ class Visualizable:
     _get_render_specs() to gain full image generation capabilities.
     """
 
+    def highlight(self, *elements, **kwargs):
+        """
+        Convenience method for highlighting elements in Jupyter/Colab.
+
+        This method creates a highlight context, adds the elements, and returns
+        the resulting image. It's designed for simple one-liner usage in notebooks.
+
+        Args:
+            *elements: Elements or element collections to highlight
+            **kwargs: Additional parameters passed to show()
+
+        Returns:
+            PIL Image with highlights
+
+        Example:
+            # Simple one-liner highlighting
+            page.highlight(left, mid, right)
+
+            # With custom colors
+            page.highlight(
+                (tables, 'blue'),
+                (headers, 'red'),
+                (footers, 'green')
+            )
+        """
+        from natural_pdf.core.highlighting_service import HighlightContext
+
+        # Create context and add elements
+        ctx = HighlightContext(self, show_on_exit=False)
+
+        for element in elements:
+            if isinstance(element, tuple) and len(element) == 2:
+                # Element with color: (element, color)
+                ctx.add(element[0], color=element[1])
+            elif isinstance(element, tuple) and len(element) == 3:
+                # Element with color and label: (element, color, label)
+                ctx.add(element[0], color=element[1], label=element[2])
+            else:
+                # Just element
+                ctx.add(element)
+
+        # Return the image directly
+        return ctx.show(**kwargs)
+
     def _get_render_specs(
         self, mode: Literal["show", "render"] = "show", **kwargs
     ) -> List[RenderSpec]:

{natural_pdf-0.2.2 → natural_pdf-0.2.3}/natural_pdf/elements/base.py

@@ -429,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,
@@ -442,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)
@@ -451,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
@@ -1260,7 +1294,7 @@ class Element(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1272,7 +1306,7 @@ class Element(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1284,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,
@@ -1299,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).
@@ -1318,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,
@@ -1330,7 +1364,7 @@ class Element(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1342,7 +1376,7 @@ class Element(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1354,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,
@@ -1369,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).
@@ -1388,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-0.2.2 → natural_pdf-0.2.3}/natural_pdf/elements/element_collection.py

@@ -1673,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))
@@ -1685,7 +1685,7 @@ class ElementCollection(
         self,
         *,
         text: str,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1697,7 +1697,7 @@ class ElementCollection(
         self,
         selector: str,
         *,
-        contains: str = "all",
+        overlap: str = "full",
         apply_exclusions: bool = True,
         regex: bool = False,
         case: bool = True,
@@ -1709,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,
@@ -1724,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).
@@ -1748,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,