natural-pdf 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

docs/visual-debugging/index.md

@@ -0,0 +1,157 @@
+# Visual Debugging
+
+Sometimes it's hard to understand what's happening when working with PDFs. Natural PDF provides powerful visual debugging tools to help you see what you're extracting.
+
+## Adding Persistent Highlights
+
+Use the `.highlight()` method on `Element` or `ElementCollection` objects to add persistent highlights to a page. These highlights are stored and will appear when viewing the page later.
+
+```python
+from natural_pdf import PDF
+
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf")
+page = pdf.pages[0]
+
+# Find a specific element and add a persistent highlight
+page.find_all('text:contains("Summary")').highlight()
+page.find_all('text:contains("Date")').highlight()
+page.find_all('line').highlight()
+page.to_image(width=700)
+```
+
+## Customizing Persistent Highlights
+
+Customize the appearance of persistent highlights added with `.highlight()`:
+
+```python
+page.clear_highlights()
+
+title = page.find('text:bold[size>=12]')
+
+# Highlight with a specific color (string name, hex, or RGB/RGBA tuple)
+# title.highlight(color=(1, 0, 0, 0.3))  # Red with 30% opacity
+# title.highlight(color="#FF0000")        # Hex color
+title.highlight(color="red")           # Color name
+
+text = page.find('text:contains("Critical")')
+
+# Add a label to the highlight (appears in legend)
+text.highlight(label="Critical")
+
+# Combine color and label
+rect = page.find('rect')
+rect.highlight(color=(0, 0, 1, 0.2), label="Box")
+
+page.to_image(width=700)
+```
+
+## Highlighting Multiple Elements
+
+Highlighting an `ElementCollection` applies the highlight to all elements within it. By default, all elements in the collection get the same color and a label based on their type.
+
+```python
+# Find and highlight all headings with a single color/label
+headings = page.find_all('text[size>=14]:bold')
+headings.highlight(color=(0, 0.5, 0, 0.3), label="Headings")
+
+# Find and highlight all tables
+tables = page.find_all('region[type=table]')
+tables.highlight(color=(0, 0, 1, 0.2), label="Tables")
+
+# View the result
+page.viewer()
+```
+
+## Highlighting Regions
+
+You can highlight regions to see what area you're working with:
+
+```python
+# Find a title and create a region below it
+title = page.find('text:contains("Violations")')
+content = title.below(height=200)
+
+# Highlight the region
+content.show()
+```
+
+Or look at just the region by itself
+
+```python
+# Find a title and create a region below it
+title = page.find('text:contains("Violations")')
+content = title.below(height=200)
+
+# Crop to the region
+content.to_image(crop_only=True, include_highlights=False)
+```
+
+## Working with Text Styles
+
+Visualize text styles to understand the document structure:
+
+```python
+# Analyze and highlight text styles
+page.clear_highlights()
+
+page.analyze_text_styles()
+page.find_all('text').highlight(group_by='style_label')
+
+page.to_image(width=700)
+```
+
+## Displaying Attributes
+
+You can display element attributes directly on the highlights:
+
+```python
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/Atlanta_Public_Schools_GA_sample.pdf")
+page = pdf.pages[0]
+
+text = page.find_all('line')
+text.highlight(include_attrs=['width', 'color'])
+
+page.to_image(width=700)
+```
+
+Does it get busy? YES.
+
+## Clearing Highlights
+
+You can clear persistent highlights from a page:
+
+```python
+# Clear all highlights on the page
+page.clear_highlights()
+
+# Apply new highlights
+page.find_all('text:bold').highlight(label="Bold Text")
+page.viewer()
+```
+
+## Document QA Visualization
+
+Visualize document QA results:
+
+```python
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/0500000US42007.pdf")
+page = pdf.pages[0]
+page.to_image(width=700)
+```
+
+```python
+response = page.ask("How many votes did Kamala Harris get on Election Day?")
+response
+```
+
+```python
+response['source_elements'].show()
+```
+
+## Next Steps
+
+Now that you know how to visualize PDF content, you might want to explore:
+
+- [OCR capabilities](../ocr/index.md) for working with scanned documents
+- [Layout analysis](../layout-analysis/index.ipynb) for automatic structure detection
+- [Document QA](../document-qa/index.ipynb) for asking questions directly to your documents

natural_pdf/__init__.py

@@ -1,6 +1,7 @@
 """
 Natural PDF - A more intuitive interface for working with PDFs.
 """
+
 import logging
 
 # Create library logger
@@ -10,10 +11,11 @@ logger = logging.getLogger("natural_pdf")
 # (Best practice for libraries)
 logger.addHandler(logging.NullHandler())
 
+
 # Utility function for users to easily configure logging
 def configure_logging(level=logging.INFO, handler=None):
     """Configure Natural PDF's logging.
-    
+
     Args:
         level: The logging level (e.g., logging.INFO, logging.DEBUG)
         handler: A custom handler, or None to use StreamHandler
@@ -21,28 +23,30 @@ def configure_logging(level=logging.INFO, handler=None):
     # Remove NullHandler if present
     if logger.handlers and isinstance(logger.handlers[0], logging.NullHandler):
         logger.removeHandler(logger.handlers[0])
-    
+
     if handler is None:
         handler = logging.StreamHandler()
-        formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
+        formatter = logging.Formatter("%(name)s - %(levelname)s - %(message)s")
         handler.setFormatter(formatter)
-    
+
     logger.addHandler(handler)
     logger.setLevel(level)
-    
+
     # Propagate level to all child loggers
     for name in logging.root.manager.loggerDict:
         if name.startswith("natural_pdf."):
             logging.getLogger(name).setLevel(level)
 
-from natural_pdf.core.pdf import PDF
+
 from natural_pdf.core.page import Page
-from natural_pdf.elements.region import Region
+from natural_pdf.core.pdf import PDF
 from natural_pdf.elements.collections import ElementCollection
+from natural_pdf.elements.region import Region
 
 # Import QA module if available
 try:
     from natural_pdf.qa import DocumentQA, get_qa_engine
+
     HAS_QA = True
 except ImportError:
     HAS_QA = False
@@ -50,27 +54,42 @@ except ImportError:
 __version__ = "0.1.1"
 
 if HAS_QA:
-    __all__ = ["PDF", "Page", "Region", "ElementCollection", "configure_logging", "DocumentQA", "get_qa_engine"]
+    __all__ = [
+        "PDF",
+        "Page",
+        "Region",
+        "ElementCollection",
+        "configure_logging",
+        "DocumentQA",
+        "get_qa_engine",
+    ]
 else:
     __all__ = ["PDF", "Page", "Region", "ElementCollection", "configure_logging"]
 
+from .collections.pdf_collection import PDFCollection
+
 # Core classes
 from .core.pdf import PDF
-from .collections.pdf_collection import PDFCollection
 from .elements.region import Region
 
 # Search options (if extras installed)
 try:
-    from .search.search_options import TextSearchOptions, MultiModalSearchOptions, BaseSearchOptions
+    from .search.search_options import BaseSearchOptions, MultiModalSearchOptions, TextSearchOptions
 except ImportError:
     # Define dummy classes if extras not installed, so imports don't break
     # but using them will raise the ImportError from check_haystack_availability
     class TextSearchOptions:
-        def __init__(self, *args, **kwargs): pass
+        def __init__(self, *args, **kwargs):
+            pass
+
     class MultiModalSearchOptions:
-        def __init__(self, *args, **kwargs): pass
+        def __init__(self, *args, **kwargs):
+            pass
+
     class BaseSearchOptions:
-        def __init__(self, *args, **kwargs): pass
+        def __init__(self, *args, **kwargs):
+            pass
+
 
 # Expose logging setup? (Optional)
 # from . import logging_config
@@ -78,10 +97,10 @@ except ImportError:
 
 # Explicitly define what gets imported with 'from natural_pdf import *'
 __all__ = [
-    'PDF',
-    'PDFCollection',
-    'Region',
-    'TextSearchOptions',       # Include search options
-    'MultiModalSearchOptions',
-    'BaseSearchOptions'
-]
+    "PDF",
+    "PDFCollection",
+    "Region",
+    "TextSearchOptions",  # Include search options
+    "MultiModalSearchOptions",
+    "BaseSearchOptions",
+]

natural_pdf/analyzers/__init__.py

@@ -1,6 +1,7 @@
 """
 Analyzers for natural-pdf.
 """
+
 from .layout import *
 from .text_structure import TextStyleAnalyzer
-from .utils import convert_to_regions
+from .utils import convert_to_regions

natural_pdf/analyzers/layout/base.py

@@ -1,7 +1,8 @@
 # layout_detector_base.py
 import logging
 from abc import ABC, abstractmethod
-from typing import Dict, List, Any, Optional, Set, Union
+from typing import Any, Dict, List, Optional, Set, Union
+
 from PIL import Image
 
 # Assuming layout_options defines BaseLayoutOptions
@@ -9,10 +10,13 @@ try:
     from .layout_options import BaseLayoutOptions
 except ImportError:
     # Placeholder if run standalone or options not found
-    class BaseLayoutOptions: pass
+    class BaseLayoutOptions:
+        pass
+
 
 logger = logging.getLogger(__name__)
 
+
 class LayoutDetector(ABC):
     """
     Abstract Base Class for layout detection engines.
@@ -26,8 +30,8 @@ class LayoutDetector(ABC):
         """Initializes the base layout detector."""
         self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
         self.logger.info(f"Initializing {self.__class__.__name__}")
-        self.supported_classes: Set[str] = set() # Subclasses should populate this
-        self._model_cache: Dict[str, Any] = {} # Cache for initialized models
+        self.supported_classes: Set[str] = set()  # Subclasses should populate this
+        self._model_cache: Dict[str, Any] = {}  # Cache for initialized models
 
     @abstractmethod
     def detect(self, image: Image.Image, options: BaseLayoutOptions) -> List[Dict[str, Any]]:
@@ -83,20 +87,20 @@ class LayoutDetector(ABC):
         """
         cache_key = self._get_cache_key(options)
         if cache_key not in self._model_cache:
-             self.logger.info(f"Loading model for cache key: {cache_key}")
-             try:
-                 # Ensure dependencies are met before loading
-                 if not self.is_available():
-                      raise RuntimeError(f"{self.__class__.__name__} dependencies are not met.")
-                 self._model_cache[cache_key] = self._load_model_from_options(options)
-                 self.logger.info(f"Model loaded successfully for key: {cache_key}")
-             except Exception as e:
-                  self.logger.error(f"Failed to load model for key {cache_key}: {e}", exc_info=True)
-                  # Remove potentially corrupted cache entry
-                  self._model_cache.pop(cache_key, None)
-                  raise # Re-raise exception after logging
+            self.logger.info(f"Loading model for cache key: {cache_key}")
+            try:
+                # Ensure dependencies are met before loading
+                if not self.is_available():
+                    raise RuntimeError(f"{self.__class__.__name__} dependencies are not met.")
+                self._model_cache[cache_key] = self._load_model_from_options(options)
+                self.logger.info(f"Model loaded successfully for key: {cache_key}")
+            except Exception as e:
+                self.logger.error(f"Failed to load model for key {cache_key}: {e}", exc_info=True)
+                # Remove potentially corrupted cache entry
+                self._model_cache.pop(cache_key, None)
+                raise  # Re-raise exception after logging
         else:
-             self.logger.debug(f"Using cached model for key: {cache_key}")
+            self.logger.debug(f"Using cached model for key: {cache_key}")
         return self._model_cache[cache_key]
 
     @abstractmethod
@@ -110,8 +114,9 @@ class LayoutDetector(ABC):
 
     def _normalize_class_name(self, name: str) -> str:
         """Convert class names with spaces/underscores to hyphenated lowercase format."""
-        if not isinstance(name, str): name = str(name) # Ensure string
-        return name.lower().replace(' ', '-').replace('_', '-')
+        if not isinstance(name, str):
+            name = str(name)  # Ensure string
+        return name.lower().replace(" ", "-").replace("_", "-")
 
     def validate_classes(self, classes: List[str]) -> None:
         """
@@ -124,8 +129,10 @@ class LayoutDetector(ABC):
             ValueError: If any class is not supported.
         """
         if not self.supported_classes:
-             self.logger.warning("Supported classes not defined for this detector. Skipping class validation.")
-             return
+            self.logger.warning(
+                "Supported classes not defined for this detector. Skipping class validation."
+            )
+            return
 
         if classes:
             # Normalize both requested and supported classes for comparison
@@ -138,8 +145,10 @@ class LayoutDetector(ABC):
                 unsupported_original = [
                     c for c in classes if self._normalize_class_name(c) in unsupported_normalized
                 ]
-                raise ValueError(f"Classes not supported by {self.__class__.__name__}: {unsupported_original}. "
-                               f"Supported (normalized): {sorted(list(normalized_supported))}")
+                raise ValueError(
+                    f"Classes not supported by {self.__class__.__name__}: {unsupported_original}. "
+                    f"Supported (normalized): {sorted(list(normalized_supported))}"
+                )
 
     def __del__(self):
         """Cleanup resources."""
@@ -148,4 +157,3 @@ class LayoutDetector(ABC):
         # Consider implications if models are shared or expensive to reload
         # del self._model_cache # Optional: uncomment if models should be released aggressively
         self._model_cache.clear()
-