natural-pdf 25.3.16__py3-none-any.whl

examples/until_boundaries_example.py

@@ -0,0 +1,156 @@
+"""
+Example demonstrating how to use the until parameter with above() and below() methods.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from natural_pdf import PDF
+
+
+def main():
+    """Main entry point."""
+    # Get the PDF path from command line or use a default
+    if len(sys.argv) > 1:
+        pdf_path = sys.argv[1]
+    else:
+        # Look for any PDF in the examples directory or pdfs directory
+        example_dir = Path(__file__).parent
+        pdf_files = list(example_dir.glob("*.pdf"))
+        
+        if not pdf_files:
+            pdfs_dir = example_dir.parent / "pdfs"
+            if pdfs_dir.exists():
+                pdf_files = list(pdfs_dir.glob("*.pdf"))
+        
+        if pdf_files:
+            pdf_path = str(pdf_files[0])
+        else:
+            print("No PDF file found. Please provide a path to a PDF file.")
+            sys.exit(1)
+    
+    print(f"Using PDF: {pdf_path}")
+    
+    # Open the PDF
+    pdf = PDF(pdf_path)
+    page = pdf.pages[0]
+    
+    # Clear any existing highlights
+    page.clear_highlights()
+    
+    # First, find some key elements on the page
+    heading1 = page.find('text[size>=12]')
+    
+    if not heading1:
+        # If no large headings, just use the first few elements as examples
+        elements = page.get_elements()
+        elements.sort(key=lambda e: (e.top, e.x0))  # Sort in reading order
+        
+        if len(elements) < 3:
+            print("Not enough elements found for demonstration")
+            return
+            
+        element1 = elements[0]
+        element2 = elements[len(elements) // 3]  # About 1/3 down
+        element3 = elements[len(elements) // 2]  # About halfway down
+        
+        # Highlight the reference elements
+        element1.highlight(label="First Element")
+        element2.highlight(label="Second Element")
+        element3.highlight(label="Third Element")
+        
+        print(f"First element: '{element1.text if hasattr(element1, 'text') else 'non-text'}' at y={element1.top}")
+        print(f"Second element: '{element2.text if hasattr(element2, 'text') else 'non-text'}' at y={element2.top}")
+        print(f"Third element: '{element3.text if hasattr(element3, 'text') else 'non-text'}' at y={element3.top}")
+        
+        # Demonstrate below() with until parameter
+        print("\nDemonstrating below() with until parameter")
+        
+        # Get the region from element1 to element2
+        region1 = element1.below(until=f'text:contains("{element2.text}")')
+        region1.highlight(label="Below until Second Element")
+        
+        # Get the region from element2 to element3, excluding element3
+        region2 = element2.below(until=f'text:contains("{element3.text}")', include_until=False)
+        region2.highlight(label="Below until Third Element (excluded)")
+        
+        # Demonstrate above() with until parameter
+        print("\nDemonstrating above() with until parameter")
+        
+        # Get the region from element3 up to element2
+        region3 = element3.above(until=f'text:contains("{element2.text}")')
+        region3.highlight(label="Above until Second Element")
+        
+        # Get the region from element2 up to element1, excluding element1
+        region4 = element2.above(until=f'text:contains("{element1.text}")', include_until=False)
+        region4.highlight(label="Above until First Element (excluded)")
+        
+        # Create an output directory
+        output_dir = Path(__file__).parent / "until_output"
+        output_dir.mkdir(exist_ok=True)
+        
+        # Save the result
+        page.save(str(output_dir / "until_boundaries.png"), labels=True)
+        
+        # Print the contents of the regions
+        print("\nContent in region 'below until second element':")
+        print(region1.extract_text()[:100] + "..." if len(region1.extract_text()) > 100 else region1.extract_text())
+        
+        print("\nContent in region 'above until second element':")
+        print(region3.extract_text()[:100] + "..." if len(region3.extract_text()) > 100 else region3.extract_text())
+        
+        print("\nExample completed. Check 'until_output/until_boundaries.png' for the result.")
+    else:
+        # Find more headings
+        headings = page.find_all('text[size>=12]')
+        
+        if len(headings) < 2:
+            # If not enough headings, fall back to the approach above
+            print("Not enough headings found. Using generic elements instead.")
+            main()  # Re-run with the above approach
+            return
+        
+        # Use the first two headings
+        heading1 = headings[0]
+        heading2 = headings[1]
+        
+        # Highlight the headings
+        heading1.highlight(label="First Heading")
+        heading2.highlight(label="Second Heading")
+        
+        print(f"First heading: '{heading1.text}' at y={heading1.top}")
+        print(f"Second heading: '{heading2.text}' at y={heading2.top}")
+        
+        # Demonstrate below() with until parameter
+        print("\nDemonstrating below() with until parameter")
+        
+        # Get the region from heading1 to heading2
+        region1 = heading1.below(until=f'text:contains("{heading2.text}")')
+        region1.highlight(label="Below until Second Heading")
+        
+        # Get the region from heading1 to heading2, excluding heading2
+        region2 = heading1.below(until=f'text:contains("{heading2.text}")', include_until=False)
+        region2.highlight(label="Below until Second Heading (excluded)")
+        
+        # Create an output directory
+        output_dir = Path(__file__).parent / "until_output"
+        output_dir.mkdir(exist_ok=True)
+        
+        # Save the result
+        page.to_image(path=str(output_dir / "until_boundaries_headings.png"), show_labels=True)
+        
+        # Print the contents of the regions
+        print("\nContent in region 'below until second heading':")
+        print(region1.extract_text()[:100] + "..." if len(region1.extract_text()) > 100 else region1.extract_text())
+        
+        print("\nContent in region 'below until second heading (excluded)':")
+        print(region2.extract_text()[:100] + "..." if len(region2.extract_text()) > 100 else region2.extract_text())
+        
+        print("\nExample completed. Check 'until_output/until_boundaries_headings.png' for the result.")
+        
+if __name__ == "__main__":
+    main()

examples/until_example.py

@@ -0,0 +1,112 @@
+"""
+Example demonstrating the 'until' feature of natural-pdf.
+(This was previously named 'select_until')
+"""
+import os
+import sys
+
+# Add the parent directory to the path to import the package
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from natural_pdf import PDF
+
+def until_example(pdf_path):
+    """Demonstrates the 'until' method for defining content regions."""
+    # Open the PDF
+    with PDF(pdf_path) as pdf:
+        page = pdf.pages[0]
+        
+        print(f"PDF loaded: {pdf_path}")
+        print(f"PDF has {len(pdf)} pages\n")
+        
+        # EXAMPLE 1: Select from "Summary:" until the thick line
+        print("EXAMPLE 1: Select from Summary until thick line")
+        print("----------------------------------------------")
+        
+        # Find the "Summary:" text
+        summary = page.find('text:contains("Summary:")')
+        print(f"Found 'Summary' text at: {summary.bbox}")
+        
+        # Find the thick line
+        thick_line = page.find('line[width>=2]')
+        print(f"Found thick line at: {thick_line.bbox}")
+        
+        # Create a region from Summary until the thick line
+        print("\nCreating region from 'Summary' until the thick line...")
+        summary_region = summary.until('line[width>=2]', width="full")
+        print(f"Region boundaries: {summary_region.bbox}")
+        
+        # Extract and display text from this region
+        region_text = summary_region.extract_text()
+        print("\nText from the region:")
+        print("-" * 60)
+        print(region_text)
+        print("-" * 60)
+        
+        # Find all text elements in this region
+        text_elements = summary_region.find_all('text')
+        print(f"\nFound {len(text_elements)} text elements in the region")
+        
+        # Display the first 5 elements
+        if text_elements:
+            print("First 5 elements:")
+            for i, el in enumerate(text_elements[:5]):
+                print(f"  {i+1}. '{el.text}'")
+        
+        # EXAMPLE 2: Demonstrate include_endpoint=False option
+        print("\nEXAMPLE 2: Without including endpoint element")
+        print("----------------------------------------------")
+        
+        # Create a region from Summary until the thick line, excluding the line
+        exclusive_region = summary.until('line[width>=2]', include_endpoint=False, width="full")
+        print(f"Region boundaries: {exclusive_region.bbox}")
+        
+        # Compare text length
+        inclusive_text = summary_region.extract_text()
+        exclusive_text = exclusive_region.extract_text()
+        
+        print(f"\nWith include_endpoint=True: {len(inclusive_text)} characters")
+        print(f"With include_endpoint=False: {len(exclusive_text)} characters")
+        
+        # EXAMPLE 3: Different elements for until
+        print("\nEXAMPLE 3: Select from one text to another")
+        print("----------------------------------------------")
+        
+        # Find text elements to use as boundaries
+        heading = page.find('text:contains("Violations")')
+        if heading:
+            # Select from "Violations" to "Critical"
+            target_word = page.find('text:contains("Critical")')
+            if target_word:
+                region = heading.until('text:contains("Critical")', width="full")
+                print(f"\nRegion from 'Violations' to 'Critical': {region.bbox}")
+                
+                text = region.extract_text()
+                print(f"Extracted {len(text)} characters of text")
+                if len(text) > 100:
+                    print(f"First 100 characters: {text[:100]}...")
+            else:
+                print("Could not find 'Critical' text")
+        else:
+            print("Could not find 'Violations' heading")
+            
+        print("\nEnd of 'until' method demonstration.")
+
+if __name__ == "__main__":
+    # Default to example PDF if no path is provided
+    if len(sys.argv) < 2:
+        # Use the example PDF in the pdfs directory
+        pdf_path = os.path.abspath(os.path.join(
+            os.path.dirname(__file__), '..', 'pdfs', '01-practice.pdf'))
+        if not os.path.exists(pdf_path):
+            print("Example PDF not found. Please provide a path to a PDF file.")
+            print("Usage: python until_example.py [path/to/file.pdf]")
+            sys.exit(1)
+    else:
+        pdf_path = sys.argv[1]
+        # Check if the file exists
+        if not os.path.exists(pdf_path):
+            print(f"File not found: {pdf_path}")
+            sys.exit(1)
+    
+    until_example(pdf_path)

examples/very_basics.py

@@ -0,0 +1,15 @@
+from natural_pdf import PDF
+
+# Open the PDF
+pdf = PDF("./pdfs/01-practice.pdf")
+
+# Approximate match for red
+serial = pdf.find('text[color~=red]')
+
+# Between 'Summary' and thick line
+summary = pdf.find('text:contains("Summary")').below(include_element=True, until='line[width>=2]')
+
+# Debug
+serial.highlight(label='Serial')
+summary.highlight(label='Summary')
+pdf.pages[0].to_image(path="output.png", show_labels=True)

natural_pdf/__init__.py

@@ -0,0 +1,55 @@
+"""
+Natural PDF - A more intuitive interface for working with PDFs.
+"""
+import logging
+
+# Create library logger
+logger = logging.getLogger("natural_pdf")
+
+# Add a NullHandler to prevent "No handler found" warnings
+# (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
+    """
+    # 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')
+        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.elements.collections import ElementCollection
+
+# Import QA module if available
+try:
+    from natural_pdf.qa import DocumentQA, get_qa_engine
+    HAS_QA = True
+except ImportError:
+    HAS_QA = False
+
+__version__ = "0.1.0"
+
+if HAS_QA:
+    __all__ = ["PDF", "Page", "Region", "ElementCollection", "configure_logging", "DocumentQA", "get_qa_engine"]
+else:
+    __all__ = ["PDF", "Page", "Region", "ElementCollection", "configure_logging"]

natural_pdf/analyzers/__init__.py

@@ -0,0 +1,9 @@
+"""
+Analyzers for natural-pdf.
+"""
+from natural_pdf.analyzers.document_layout import (
+    LayoutDetector,
+    YOLODocLayoutDetector,
+    TableTransformerDetector,
+    convert_to_regions
+)