pdflinkcheck 1.1.47__py3-none-any.whl → 1.1.72__py3-none-any.whl

pdflinkcheck/__init__.py

@@ -1,31 +1,69 @@
+# src/pdflinkcheck/__init__.py
+"""
+# License information
+pdflinkcheck - A PDF Link Checker
+
+Copyright (C) 2025 George Clayton Bennett
+
+Source code: https://github.com/City-of-Memphis-Wastewater/pdflinkcheck/
+
+This program is free software: You can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.                    
+
+The AGPL3+ is required because pdflinkcheck uses PyMuPDF, which is licensed under the AGPL3.
+"""
+import os as _os
+
 # Library functions
-from pdflinkcheck.analyze import run_analysis, extract_links, extract_toc
+from pdflinkcheck.analyze_pymupdf import extract_links_pymupdf, extract_toc_pymupdf
+from pdflinkcheck.analyze_pypdf import extract_links_pypdf, extract_toc_pypdf
+#from pdflinkcheck import analyze_pypdf
+from pdflinkcheck.report import run_report
+from pdflinkcheck.report import run_report as run_analysis # for backwards compatibility with previos versions
+#from pdflinkcheck import dev
 
 # For the kids. This is what I wanted when learning Python in a mysterious new REPL.
 # Is this Pythonic? No. Oh well. PEP 8, PEP 20.
-import os
-flag = os.environ.get('PDFLINKCHECK_GUI_EASTEREGG', '')
-pdflibkcheck_gui_lib_func_load = str(flag).strip().lower() in ('true', '1', 'yes', 'on')
-
-if pdflibkcheck_gui_lib_func_load:
+# Why is this not Pythonic? Devs expect no side effects when importing library functions.
+# What is a side effect?
+_gui_easteregg_env_flag = _os.environ.get('PDFLINKCHECK_GUI_EASTEREGG', '')
+_load_gui_func = str(_gui_easteregg_env_flag).strip().lower() in ('true', '1', 'yes', 'on')
+if _load_gui_func:
     try:
-        import pyhabitat # pyhabitat is a dependency of this package already
-        if pyhabitat.tkinter_is_available():
+        import pyhabitat as _pyhabitat # pyhabitat is a dependency of this package already
+        if _pyhabitat.tkinter_is_available():
             from pdflinkcheck.gui import start_gui
     except ImportError:
         # Optional: log or ignore silently
-        pass
+        print("start_gui() not imported")
 
 # Breadcrumbs, for stumbling upon.
-if pdflibkcheck_gui_lib_func_load:
+if _load_gui_func:
     __pdflinkcheck_gui_easteregg_enabled__ = True
 else:
     __pdflinkcheck_gui_easteregg_enabled__ = False
 
 # Define __all__ such that the library functions are self documenting.
 __all__ = [
+    "run_report",
     "run_analysis",
-    "extract_links",
-    "extract_toc",
-    "start_gui" if pdflibkcheck_gui_lib_func_load else None,
+    "extract_links_pymupdf", 
+    "extract_toc_pymupdf", 
+    "extract_links_pypdf", 
+    "extract_toc_pypdf", 
+    #"start_gui" if _load_gui_func else None,
+    #"dev", 
 ]
+if _load_gui_func:
+    __all__.append("start_gui")
+
+# 4. THE CLEANUP (This removes items from dir())
+del _os
+del _gui_easteregg_env_flag
+del _load_gui_func
+
+# Force avoid 'io' appearing, it's likely being imported, when it is imported by another package which is imported here:
+#if "io" in locals(): 
+#    del io

pdflinkcheck/{analyze.py → analyze_pymupdf.py}

@@ -1,14 +1,17 @@
 import sys
 from pathlib import Path
 import logging
-from typing import Dict, Any, Optional
-# ... other imports ...
-# Configure logging to suppress low-level pdfminer messages
+from typing import Dict, Any, Optional, List
+
 logging.getLogger("fitz").setLevel(logging.ERROR) 
-import fitz # PyMuPDF
 
-from pdflinkcheck.remnants import find_link_remnants
-from pdflinkcheck.io import error_logger, export_report_data, LOG_FILE_PATH
+try:
+    import fitz  # PyMuPDF
+except ImportError:
+    fitz = None
+
+from pdflinkcheck.report import run_report
+#from pdflinkcheck.validate import run_validation
 
 """
 Inspect target PDF for both URI links and for GoTo links.
@@ -41,6 +44,44 @@ def get_link_rect(link_dict):
     return None
 
 def get_anchor_text(page, link_rect):
+    if not link_rect:
+        return "N/A: Missing Rect"
+
+    try:
+        # 1. Convert to fitz.Rect and normalize
+        rect = fitz.Rect(link_rect)
+        if rect.is_empty:
+            return "N/A: Rect Error"
+
+        # 2. Use asymmetric expansion (similar to the pypdf logic)
+        # 10 points horizontal to catch wide characters/kerning
+        # 3 points vertical to stay within the line
+        search_rect = fitz.Rect(
+            rect.x0 - 10, 
+            rect.y0 - 3, 
+            rect.x1 + 10, 
+            rect.y1 + 3
+        )
+
+        # 3. Extract all words on the page
+        # Each word is: (x0, y0, x1, y1, "text", block_no, line_no, word_no)
+        words = page.get_text("words")
+        
+        anchor_parts = []
+        for w in words:
+            word_rect = fitz.Rect(w[:4])
+            # Check if the word intersects our expanded link rectangle
+            if word_rect.intersects(search_rect):
+                anchor_parts.append(w[4])
+
+        cleaned_text = " ".join(anchor_parts).strip()
+        
+        return cleaned_text if cleaned_text else "N/A: No Visible Text"
+            
+    except Exception:
+        return "N/A: Rect Error"
+    
+def get_anchor_text_stable(page, link_rect):
     """
     Extracts text content using the link's bounding box coordinates.
     The bounding box is slightly expanded to ensure full characters are captured.
@@ -91,7 +132,6 @@ def get_anchor_text(page, link_rect):
         # Fallback for unexpected errors in rect conversion or retrieval
         return "N/A: Rect Error"
 
-
 def analyze_toc_fitz(doc):
     """
     Extracts the structural Table of Contents (PDF Bookmarks/Outline) 
@@ -120,7 +160,7 @@ def analyze_toc_fitz(doc):
 
 # 2. Updated Main Inspection Function to Include Text Extraction
 #def inspect_pdf_hyperlinks_fitz(pdf_path):
-def extract_toc(pdf_path):
+def extract_toc_pymupdf(pdf_path):
     """
     Opens a PDF, iterates through all pages and extracts the structural table of contents (TOC/bookmarks).
 
@@ -165,7 +205,8 @@ def serialize_fitz_object(obj):
     # Otherwise, return the object as is (it's already primitive)
     return obj
 
-def extract_links(pdf_path):
+
+def extract_links_pymupdf(pdf_path):
     """
     Opens a PDF, iterates through all pages and extracts all link annotations. 
     It categorizes the links into External, Internal, or Other actions, and extracts the anchor text.
@@ -225,7 +266,7 @@ def extract_links(pdf_path):
                 # This will be skipped by URI, which is not expected to have a page key
                 target_page_num_reported = "N/A"
                 if link.get('page') is not None:
-                    target_page_num_reported = int(link.get('page')) # accurate for link target, don't add 1 (weird)
+                    target_page_num_reported = int(link.get('page'))+1 # accurate for link target, don't add 1 (weird)
 
                 if link['kind'] == fitz.LINK_URI:
                     target =  link.get('uri', 'URI (Unknown Target)')
@@ -283,226 +324,15 @@ def extract_links(pdf_path):
         print(f"An error occurred: {e}", file=sys.stderr)
     return links_data
 
-def print_structural_toc(structural_toc):
-    """
-    Prints the structural TOC data (bookmarks/outline) in a clean, 
-    hierarchical, and readable console format.
-
-    Args:
-        structural_toc: A list of TOC dictionaries returned by `analyze_toc_fitz`.
-    """
-    print("\n" + "=" * 70)
-    print("## Structural Table of Contents (PDF Bookmarks/Outline)")
-    print("=" * 70)
-    if not structural_toc:
-        print("No structural TOC (bookmarks/outline) found.")
-        return
-
-    # Determine max page width for consistent alignment (optional but nice)
-    max_page = max(item['target_page'] for item in structural_toc) if structural_toc else 1
-    page_width = len(str(max_page))
-    
-    # Iterate and format
-    for item in structural_toc:
-        # Use level for indentation (e.g., Level 1 = 0 spaces, Level 2 = 4 spaces, Level 3 = 8 spaces)
-        indent = " " * 4 * (item['level'] - 1)
-        # Format the title and target page number
-        page_str = str(item['target_page']).rjust(page_width)
-        print(f"{indent}{item['title']} . . . page {page_str}")
-
-    print("-" * 70)
-
-
-def get_first_pdf_in_cwd() -> Optional[str]:
-    """
-    Scans the current working directory (CWD) for the first file ending 
-    with a '.pdf' extension (case-insensitive).
-
-    This is intended as a convenience function for running the tool 
-    without explicitly specifying a path.
-
-    Returns:
-        The absolute path (as a string) to the first PDF file found, 
-        or None if no PDF files are present in the CWD.
-    """
-    # 1. Get the current working directory (CWD)
-    cwd = Path.cwd()
-    
-    # 2. Use Path.glob to find files matching the pattern. 
-    #    We use '**/*.pdf' to also search nested directories if desired, 
-    #    but typically for a single PDF in CWD, '*.pdf' is enough. 
-    #    Let's stick to files directly in the CWD for simplicity.
-    
-    # We use list comprehension with next() for efficiency, or a simple loop.
-    # Using Path.glob('*.pdf') to search the CWD for files ending in .pdf
-    # We make it case-insensitive by checking both '*.pdf' and '*.PDF'
-    
-    # Note: On Unix systems, glob is case-sensitive by default.
-    # The most cross-platform safe way is to iterate and check the suffix.
-    
-    try:
-        # Check for files in the current directory only
-        # Iterating over the generator stops as soon as the first match is found.
-        first_pdf_path = next(
-            p.resolve() for p in cwd.iterdir() 
-            if p.is_file() and p.suffix.lower() == '.pdf'
-        )
-        return str(first_pdf_path)
-    except StopIteration:
-        # If the generator runs out of items, no PDF was found
-        return None
-    except Exception as e:
-        # Handle potential permissions errors or other issues
-        print(f"Error while searching for PDF in CWD: {e}", file=sys.stderr)
-        return None
-
-def run_analysis(pdf_path: str = None, check_remnants: bool = True, max_links: int = 0, export_format: Optional[str] = "JSON") -> Dict[str, Any]:
-    """
-    Core high-level PDF link analysis logic. 
-    
-    This function orchestrates the extraction of active links and TOC 
-    using PyMuPDF, finds link remnants (plain text URLs/emails), and 
-    prints a comprehensive, user-friendly report to the console.
-
-    Args:
-        pdf_path: The file system path (str) to the target PDF document.
-        check_remnants: Boolean flag to enable/disable scanning for plain text 
-                        links that are not active hyperlinks.
-        max_links: Maximum number of links/remnants to display in each console 
-                   section. If <= 0, all links will be displayed.
-
-    Returns:
-        A dictionary containing the structured results of the analysis:
-        'external_links', 'internal_links', 'remnants', and 'toc'.
-    """
-
-    if pdf_path is None:
-        pdf_path = get_first_pdf_in_cwd()
-    if pdf_path is None:
-        print("pdf_path is None")
-        print("Tip: Drop a PDF in the current folder or pass in a path arg.")
-        return
-    try:
-        print(f"Running PyMuPDF analysis on {Path(pdf_path).name}...")
-
-        # 1. Extract all active links and TOC
-        extracted_links = extract_links(pdf_path)
-        structural_toc = extract_toc(pdf_path) 
-        toc_entry_count = len(structural_toc)
-        
-        # 2. Find link remnants
-        remnants = []
-        if check_remnants:
-            remnants = find_link_remnants(pdf_path, extracted_links) # Pass active links to exclude them
-
-        if not extracted_links and not remnants and not structural_toc:
-            print(f"\nNo hyperlinks, remnants, or structural TOC found in {Path(pdf_path).name}.")
-            return {}
-            
-        # 3. Separate the lists based on the 'type' key
-        uri_links = [link for link in extracted_links if link['type'] == 'External (URI)']
-        goto_links = [link for link in extracted_links if link['type'] == 'Internal (GoTo/Dest)']
-        resolved_action_links = [link for link in extracted_links if link['type'] == 'Internal (Resolved Action)']
-        other_links = [link for link in extracted_links if link['type'] not in ['External (URI)', 'Internal (GoTo/Dest)', 'Internal (Resolved Action)']]
-
-        total_internal_links = len(goto_links) + len(resolved_action_links)
-        
-        # --- ANALYSIS SUMMARY (Using your print logic) ---
-        print("\n" + "✪" * 70)
-        print(f"--- Link Analysis Results for {Path(pdf_path).name} ---")
-        print(f"Total active links: {len(extracted_links)} (External: {len(uri_links)}, Internal Jumps: {total_internal_links}, Other: {len(other_links)})")
-        print(f"Total **structural TOC entries (bookmarks)** found: {toc_entry_count}")
-        print(f"Total **potential missing links** found: {len(remnants)}")
-        print("✪" * 70)
-
-        limit = max_links if max_links > 0 else None
-
-        uri_and_other = uri_links + other_links
-        
-        # --- Section 1: ACTIVE URI LINKS ---
-        print("\n" + "=" * 70)
-        print(f"## Active URI Links (External & Other) - {len(uri_and_other)} found") 
-        print("{:<5} | {:<5} | {:<40} | {}".format("Idx", "Page", "Anchor Text", "Target URI/Action"))
-        print("=" * 70)
-        
-        if uri_and_other:
-            for i, link in enumerate(uri_and_other[:limit], 1):
-                target = link.get('url') or link.get('remote_file') or link.get('target')
-                link_text = link.get('link_text', 'N/A')
-                print("{:<5} | {:<5} | {:<40} | {}".format(i, link['page'], link_text[:40], target))
-            if limit is not None and len(uri_and_other) > limit:
-                print(f"... and {len(uri_and_other) - limit} more links (use --max-links to see all or --max-links 0 to show all).")
-
-        else: 
-            print(" No external or 'Other' links found.")
-
-        # --- Section 2: ACTIVE INTERNAL JUMPS ---
-        print("\n" + "=" * 70)
-        print(f"## Active Internal Jumps (GoTo & Resolved Actions) - {total_internal_links} found")
-        print("=" * 70)
-        print("{:<5} | {:<5} | {:<40} | {}".format("Idx", "Page", "Anchor Text", "Jumps To Page"))
-        print("-" * 70)
-        
-        all_internal = goto_links + resolved_action_links
-        if total_internal_links > 0:
-            for i, link in enumerate(all_internal[:limit], 1):
-                link_text = link.get('link_text', 'N/A')
-                print("{:<5} | {:<5} | {:<40} | {}".format(i, link['page'], link_text[:40], link['destination_page']))
-
-            if limit is not None and len(all_internal) > limit:
-                print(f"... and {len(all_internal) - limit} more links (use --max-links to see all or --max-links 0 to show all).")
-        else:
-            print(" No internal GoTo or Resolved Action links found.")
-            
-        # --- Section 3: REMNANTS ---
-        print("\n" + "=" * 70)
-        print(f"## ⚠️ Link Remnants (Potential Missing Links to Fix) - {len(remnants)} found")
-        print("=" * 70)
-        
-        if remnants:
-            print("{:<5} | {:<5} | {:<15} | {}".format("Idx", "Page", "Remnant Type", "Text Found (Needs Hyperlink)"))
-            print("-" * 70)
-            for i, remnant in enumerate(remnants[:limit], 1):
-                print("{:<5} | {:<5} | {:<15} | {}".format(i, remnant['page'], remnant['type'], remnant['text']))
-            if max_links!=0 and len(remnants) > max_links:
-                print(f"... and {len(remnants) - max_links} more remnants (use --max-links to see all).")
-        else:
-            print(" No URI or Email remnants found that are not already active links.")
-            
-        # --- Section 4: TOC ---
-        print_structural_toc(structural_toc)
-        
-        # Return the collected data for potential future JSON/other output
-        final_report_data =  {
-            "external_links": uri_links,
-            "internal_links": all_internal,
-            "remnants": remnants,
-            "toc": structural_toc
-        }
-
-        # 5. Export Report 
-        if export_format:
-            # Assuming export_to will hold the output format string (e.g., "JSON")
-            export_report_data(final_report_data, Path(pdf_path).name, export_format)
-
-        return final_report_data
-    except Exception as e:
-        # Log the critical failure
-        error_logger.error(f"Critical failure during run_analysis for {pdf_path}: {e}", exc_info=True)
-        print(f"FATAL: Analysis failed. Check logs at {LOG_FILE_PATH}", file=sys.stderr)
-        raise # Allow the exception to propagate or handle gracefully
-
-
 
 def call_stable():
     """
     Placeholder function for command-line execution (e.g., in __main__).
     Note: This requires defining PROJECT_NAME, CLI_MAIN_FILE, etc., or 
-    passing them as arguments to run_analysis.
+    passing them as arguments to run_report.
     """
-    print("Begin analysis...")
-    run_analysis()
-    print("Analysis complete.")
+    run_report(pdf_library = "pymupdf")
+    #run_validation(pdf_library = "pymupdf")
 
 if __name__ == "__main__":
     call_stable()

pdflinkcheck/analyze_pypdf.py

@@ -0,0 +1,184 @@
+# src/pdflinkcheck/analyze_pypdf.py
+import sys
+from pathlib import Path
+import logging
+from typing import Dict, Any, Optional, List
+
+from pypdf import PdfReader
+from pypdf.generic import Destination, NameObject, ArrayObject, IndirectObject
+
+
+from pdflinkcheck.io import error_logger, export_report_data, get_first_pdf_in_cwd, LOG_FILE_PATH
+from pdflinkcheck.report import run_report
+#from pdflinkcheck.validate import run_validation
+
+"""
+Inspect target PDF for both URI links and for GoTo links, using only pypdf, not Fitz
+"""
+
+def get_anchor_text_pypdf(page, rect) -> str:
+    """
+    Extracts text within the link's bounding box using a visitor function.
+    Reliable for finding text associated with a link without PyMuPDF.
+    """
+    if not rect:
+        return "N/A: Missing Rect"
+    
+    # Standardize rect orientation (pypdf Rects are [x0, y0, x1, y1])
+    # Note: PDF coordinates use bottom-left as (0,0)
+    x_min = min(rect[0], rect[2])
+    y_min = min(rect[1], rect[3])
+    x_max = max(rect[0], rect[2])
+    y_max = max(rect[1], rect[3])
+    
+    parts: List[str] = []
+
+    def visitor_body(text, cm, tm, font_dict, font_size):
+        # tm[4], tm[5] are the current text insertion point coordinates (x, y)
+        x, y = tm[4], tm[5]
+
+        # Using a threshold to account for font metrics/descenders
+        # Generous tolerance (±10 pt) to catch descenders, ascenders, kerning, and minor misalignments
+        tolerance = 10
+        if (x_min - tolerance) <= x <= (x_max + tolerance) and (y_min - tolerance) <= y <= (y_max + tolerance):
+            if text.strip():
+                parts.append(text)
+
+    page.extract_text(visitor_text=visitor_body)
+    
+    raw_extracted = "".join(parts)
+    cleaned = " ".join(raw_extracted.split()).strip()
+    
+    return cleaned if cleaned else "Graphic/Empty Link"
+
+def resolve_pypdf_destination(reader: PdfReader, dest, obj_id_to_page: dict) -> str:
+    """
+    Resolves a Destination object or IndirectObject to a 1-based page number string.
+    """
+    try:
+        if isinstance(dest, Destination):
+            return str(dest.page_number + 1)
+        
+        if isinstance(dest, IndirectObject):
+            return str(obj_id_to_page.get(dest.idnum, "Unknown"))
+        
+        if isinstance(dest, ArrayObject) and len(dest) > 0:
+            if isinstance(dest[0], IndirectObject):
+                return str(obj_id_to_page.get(dest[0].idnum, "Unknown"))
+            
+        return "Unknown"
+    except Exception:
+        return "Error Resolving"
+
+def extract_links_pypdf(pdf_path):
+    """
+    Termux-compatible link extraction using pure-Python pypdf.
+    Matches the reporting schema of the PyMuPDF version.
+    """
+    reader = PdfReader(pdf_path)
+    
+    # Pre-map Object IDs to Page Numbers for fast internal link resolution
+    obj_id_to_page = {
+        page.indirect_reference.idnum: i + 1 
+        for i, page in enumerate(reader.pages)
+    }
+
+    all_links = []
+    
+    for i, page in enumerate(reader.pages):
+        page_num = i + 1
+        if "/Annots" not in page:
+            continue
+            
+        for annot in page["/Annots"]:
+            obj = annot.get_object()
+            if obj.get("/Subtype") != "/Link":
+                continue
+
+            rect = obj.get("/Rect")
+            anchor_text = get_anchor_text_pypdf(page, rect)
+            
+            link_dict = {
+                'page': page_num,
+                'rect': list(rect) if rect else None,
+                'link_text': anchor_text,
+                'type': 'Other Action',
+                'target': 'Unknown'
+            }
+
+            # Handle URI (External)
+            if "/A" in obj and "/URI" in obj["/A"]:
+                uri = obj["/A"]["/URI"]
+                link_dict.update({
+                    'type': 'External (URI)',
+                    'url': uri,
+                    'target': uri
+                })
+
+            # Handle GoTo (Internal)
+            elif "/Dest" in obj or ("/A" in obj and "/D" in obj["/A"]):
+                dest = obj.get("/Dest") or obj["/A"].get("/D")
+                target_page = resolve_pypdf_destination(reader, dest, obj_id_to_page)
+                link_dict.update({
+                    'type': 'Internal (GoTo/Dest)',
+                    'destination_page': target_page,
+                    'target': f"Page {target_page}"
+                })
+            
+            # Handle Remote GoTo (GoToR)
+            elif "/A" in obj and obj["/A"].get("/S") == "/GoToR":
+                remote_file = obj["/A"].get("/F")
+                link_dict.update({
+                    'type': 'Remote (GoToR)',
+                    'remote_file': str(remote_file),
+                    'target': f"File: {remote_file}"
+                })
+
+            all_links.append(link_dict)
+                        
+    return all_links
+
+
+def extract_toc_pypdf(pdf_path: str) -> List[Dict[str, Any]]:
+    try:
+        reader = PdfReader(pdf_path)
+        # Note: outline is a property, not a method.
+        toc_tree = reader.outline 
+        toc_data = []
+        
+        def flatten_outline(outline_items, level=1):
+            for item in outline_items:
+                if isinstance(item, Destination):
+                    # Using the reader directly is the only way to avoid 
+                    # the 'Destination' object has no attribute error
+                    try:
+                        page_num = reader.get_destination_page_number(item) + 1
+                    except:
+                        page_num = "N/A"
+
+                    toc_data.append({
+                        "level": level,
+                        "title": item.title,
+                        "target_page": page_num
+                    })
+                elif isinstance(item, list):
+                    # pypdf nests children in a list immediately following the parent
+                    flatten_outline(item, level + 1)
+        
+        flatten_outline(toc_tree)
+        return toc_data
+    except Exception as e:
+        print(f"TOC error: {e}", file=sys.stderr)
+        return []
+
+def call_stable():
+    """
+    Placeholder function for command-line execution (e.g., in __main__).
+    Note: This requires defining PROJECT_NAME, CLI_MAIN_FILE, etc., or 
+    passing them as arguments to run_report.
+    """
+    run_report(pdf_library = "pypdf")
+    #run_validation(pdf_library = "pypdf")
+
+if __name__ == "__main__":
+    call_stable()