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

pdflinkcheck/io.py

@@ -1,8 +1,9 @@
 # src/pdflinkcheck/io.py
 import logging
 import json
+import sys
 from pathlib import Path
-from typing import Dict, Any, Union, List
+from typing import Dict, Any, Union, List, Optional
 
 # --- Configuration ---
 
@@ -27,6 +28,14 @@ def setup_error_logger():
     """
     Configures a basic logger that writes errors and warnings to a file 
     in the PDFLINKCHECK_HOME directory.
+
+    # Example of how an external module can log an error:
+    # from pdflinkcheck.io import error_logger
+    # try: 
+    #     ...
+    # except Exception as e:
+    #     error_logger.exception("An exception occurred during link extraction.")
+
     """
     # Create the logger instance
     logger = logging.getLogger('pdflinkcheck_logger')
@@ -57,14 +66,15 @@ error_logger = setup_error_logger()
 def export_report_data(
     report_data: Dict[str, Any], 
     pdf_filename: str, 
-    export_format: str = "JSON"
+    export_format: str = "JSON",
+    pdf_library: str = "", # expected to be specificed every time.
 ) -> Path:
     """
     Exports the structured analysis report data to a file in the 
     PDFLINKCHECK_HOME directory.
 
     Args:
-        report_data: The dictionary containing the results from run_analysis.
+        report_data: The dictionary containing the results from run_report.
         pdf_filename: The base filename of the PDF being analyzed (used for the output file name).
         export_format: The desired output format ('json' currently supported).
 
@@ -80,7 +90,7 @@ def export_report_data(
         
     # Create an output file name based on the PDF name and a timestamp
     base_name = Path(pdf_filename).stem
-    output_filename = f"{base_name}_report.json"
+    output_filename = f"{base_name}_{pdf_library}_report.json"
     output_path = PDFLINKCHECK_HOME / output_filename
 
     try:
@@ -88,7 +98,7 @@ def export_report_data(
             # Use indent for readability
             json.dump(report_data, f, indent=4)
             
-        print(f"\nReport successfully exported to: {output_path}")
+        print(f"\nReport successfully exported to: {get_friendly_path(output_path)}")
         return output_path
         
     except Exception as e:
@@ -96,11 +106,108 @@ def export_report_data(
         # Re-raise the exception after logging for caller to handle
         raise RuntimeError(f"Report export failed due to an I/O error: {e}")
 
-# Example of how an external module can log an error:
-# from pdflinkcheck.io import error_logger
-# try: 
-#     ...
-# except Exception as e:
-#     error_logger.exception("An exception occurred during link extraction.")
+def export_report_json(
+    report_data: Dict[str, Any], 
+    pdf_filename: str, 
+    pdf_library: str
+) -> Path:
+    """Exports structured dictionary results to a .json file."""
+    base_name = Path(pdf_filename).stem
+    output_path = PDFLINKCHECK_HOME / f"{base_name}_{pdf_library}_report.json"
+
+    try:
+        with open(output_path, 'w', encoding='utf-8') as f:
+            json.dump(report_data, f, indent=4)
+        print(f"\nJSON report exported: {get_friendly_path(output_path)}")
+        return output_path
+    except Exception as e:
+        error_logger.error(f"JSON export failed: {e}", exc_info=True)
+        raise RuntimeError(f"JSON export failed: {e}")
+
+def export_report_txt(
+    report_text: str, 
+    pdf_filename: str, 
+    pdf_library: str
+) -> Path:
+    """Exports the formatted string buffer to a .txt file."""
+    base_name = Path(pdf_filename).stem
+    output_path = PDFLINKCHECK_HOME / f"{base_name}_{pdf_library}_report.txt"
+
+    try:
+        output_path.write_text(report_text, encoding='utf-8')
+        print(f"\nTXT report exported: {get_friendly_path(output_path)}")
+        return output_path
+    except Exception as e:
+        error_logger.error(f"TXT export failed: {e}", exc_info=True)
+        raise RuntimeError(f"TXT export failed: {e}")
+
+def export_validation_json(
+    report_data: Dict[str, Any], 
+    pdf_filename: str, 
+    pdf_library: str
+) -> Path:
+    """Exports structured dictionary validation results to a .json file."""
+    base_name = Path(pdf_filename).stem
+    output_path = PDFLINKCHECK_HOME / f"{base_name}_{pdf_library}_validation.json"
 
+    try:
+        with open(output_path, 'w', encoding='utf-8') as f:
+            json.dump(report_data, f, indent=4)
+        print(f"\nJSON validation exported: {get_friendly_path(output_path)}")
+        return output_path
+    except Exception as e:
+        error_logger.error(f"JSON validation export failed: {e}", exc_info=True)
+        raise RuntimeError(f"JSON validation export failed: {e}")
 
+# --- helpers ---
+def get_friendly_path(full_path: str) -> str:
+    p = Path(full_path).resolve()
+    try:
+        # Replaces /home/oolong with ~
+        return str(p).replace(str(Path.home()), "~")
+    except ValueError:
+        return str(p)
+    
+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.
+    print("No PDF argument was provide. Falling back to using the first PDF available at the current path.")
+    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'
+        )
+        print(f"Fallback PDF found: {first_pdf_path.name}")
+        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

pdflinkcheck/report.py

@@ -0,0 +1,280 @@
+# pdflinkcheck/report.py
+
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+import pyhabitat
+
+from pdflinkcheck.io import error_logger, export_report_json, export_report_txt, get_first_pdf_in_cwd, get_friendly_path, LOG_FILE_PATH
+
+
+def run_report(pdf_path: str = None,  max_links: int = 0, export_format: str = "JSON", pdf_library: str = "pypdf", print_bool:bool=True) -> Dict[str, Any]:
+    """
+    Core high-level PDF link analysis logic. 
+    
+    This function orchestrates the extraction of active links and TOC 
+    using pdflinkcheck analysis, and 
+    prints a comprehensive, user-friendly report to the console.
+
+    Args:
+        pdf_path: The file system path (str) to the target PDF document.
+        max_links: Maximum number of links 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', and 'toc'.
+
+    To Do:
+        Aggregate print strings into a str for TXT export.
+        Modularize.
+    """
+
+    report_buffer = []
+
+    # Helper to handle conditional printing and mandatory buffering
+    def log(msg: str):
+        if print_bool: # this should not be here
+            print(msg) # this should not be here. esure elsewhere then remove
+        report_buffer.append(msg)
+
+    # Expected: "pypdf" or "PyMuPDF"
+    allowed_libraries = ("pypdf","pymupdf")
+    pdf_library = pdf_library.lower()
+    if pdf_library in allowed_libraries and pdf_library == "pypdf":
+        from pdflinkcheck.analyze_pypdf import (extract_links_pypdf as extract_links, extract_toc_pypdf as extract_toc)
+    elif pdf_library in allowed_libraries and pdf_library == "pymupdf":
+        try:
+            import fitz
+        except ImportError:
+            print("PyMuPDF was explicitly requested as the PDF Engine")
+            print("Use pypdf instead, or install PyMuPDF. ")
+            print("To install PyMuPDF locally, try: `uv sync --extra full` OR `pip install .[full]`")
+            if pyhabitat.on_termux():
+                print(f"pyhabitat.on_termux() = {pyhabitat.on_termux()}")
+                print("PyMuPDF is not expected to work on Termux. Use pypdf.")
+            print("\n")
+            return    
+        from pdflinkcheck.analyze_pymupdf import (extract_links_pymupdf as extract_links, extract_toc_pymupdf as extract_toc)
+    
+    log("\n--- Starting Analysis ... ---\n")
+    if pdf_path is None:
+        pdf_path = get_first_pdf_in_cwd()
+    if pdf_path is None:
+        log("pdf_path is None")
+        log("Tip: Drop a PDF in the current folder or pass in a path arg.")
+        return
+    try:
+        log(f"Target file: {get_friendly_path(pdf_path)}")
+        log(f"PDF Engine: {pdf_library}")
+
+        # 1. Extract all active links and TOC
+        extracted_links = extract_links(pdf_path)
+        structural_toc = extract_toc(pdf_path) 
+        #structural_toc = extract_toc_pypdf(pdf_path) 
+        toc_entry_count = len(structural_toc)
+        
+
+        if not extracted_links and not structural_toc:
+            log(f"\nNo hyperlinks or structural TOC found in {Path(pdf_path).name}.")
+            log("(This is common for scanned/image-only PDFs.)")
+            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)
+        limit = max_links if max_links > 0 else None
+        uri_and_other = uri_links + other_links
+        
+        # --- ANALYSIS SUMMARY (Using your print logic) ---
+        log("\n" + "=" * 70)
+        log(f"--- Link Analysis Results for {Path(pdf_path).name} ---")
+        log(f"Total active links: {len(extracted_links)} (External: {len(uri_links)}, Internal Jumps: {total_internal_links}, Other: {len(other_links)})")
+        log(f"Total **structural TOC entries (bookmarks)** found: {toc_entry_count}")
+        log("=" * 70)
+
+        # --- Section 1: TOC ---
+        str_structural_toc = print_structural_toc(structural_toc)
+        log(str_structural_toc)
+
+        # --- Section 2: ACTIVE INTERNAL JUMPS ---
+        log("\n" + "=" * 70)
+        log(f"## Active Internal Jumps (GoTo & Resolved Actions) - {total_internal_links} found")
+        log("=" * 70)
+        log("{:<5} | {:<5} | {:<40} | {}".format("Idx", "Page", "Anchor Text", "Jumps To Page"))
+        log("-" * 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')
+                log("{:<5} | {:<5} | {:<40} | {}".format(i, link['page'], link_text[:40], link['destination_page']))
+
+            if limit is not None and len(all_internal) > limit:
+                log(f"... and {len(all_internal) - limit} more links (use --max-links 0 to show all).")
+        else:
+            log(" No internal GoTo or Resolved Action links found.")
+        log("-" * 70)
+        
+        # --- Section 3: ACTIVE URI LINKS ---
+        log("\n" + "=" * 70)
+        log(f"## Active URI Links (External & Other) - {len(uri_and_other)} found") 
+        log("{:<5} | {:<5} | {:<40} | {}".format("Idx", "Page", "Anchor Text", "Target URI/Action"))
+        log("=" * 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')
+                log("{:<5} | {:<5} | {:<40} | {}".format(i, link['page'], link_text[:40], target))
+            if limit is not None and len(uri_and_other) > limit:
+                log(f"... and {len(uri_and_other) - limit} more links (use --max-links 0 to show all).")
+
+        else: 
+            log(" No external or 'Other' links found.")
+        log("-" * 70)
+
+        log("\n--- Analysis Complete ---\n")
+
+        # Final aggregation of the buffer into one string
+        report_buffer_str = "\n".join(report_buffer)
+        
+        # Return the collected data for potential future JSON/other output
+        final_report_data_dict =  {
+            "external_links": uri_links,
+            "internal_links": all_internal,
+            "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_dict, Path(pdf_path).name, export_format, pdf_library)
+        
+        if export_format:
+            fmt_upper = export_format.upper()
+            
+            if "JSON" in fmt_upper:
+                export_report_json(final_report_data_dict, pdf_path, pdf_library)
+            
+            if "TXT" in fmt_upper:
+                export_report_txt(report_buffer_str, pdf_path, pdf_library)
+        
+        report_results = {
+            "data": final_report_data_dict, # The structured JSON-ready dict
+            "text": report_buffer_str,      # The human-readable string
+            "metadata": {                  # Helpful for the GUI/Logs
+                "pdf_name": Path(pdf_path).name,
+                "library_used": pdf_library,
+                "total_links": len(extracted_links)
+            }
+        }
+        # Return a clean results object
+        return report_results
+    except Exception as e:
+        # Specific handling for common read failures
+        if "invalid pdf header" in str(e).lower() or "EOF marker not found" in str(e) or "stream has ended unexpectedly" in str(e):
+            log(f"\nWarning: Could not parse PDF structure — likely an image-only or malformed PDF.")
+            log("No hyperlinks or TOC can exist in this file.")
+            log("Result: No links found.")
+            return {
+                "data": {"external_links": [], "internal_links": [], "toc": []},
+                "text": "\n".join(report_buffer + [
+                    "\nWarning: PDF appears to be image-only or malformed.",
+                    "No hyperlinks or structural TOC found."
+                ]),
+                "metadata": {
+                    "pdf_name": Path(pdf_path).name,
+                    "library_used": pdf_library,
+                    "total_links": 0
+                }
+            }
+
+    except Exception as e:
+        # Log the critical failure
+        error_logger.error(f"Critical failure during run_report for {pdf_path}: {e}", exc_info=True)
+        log(f"FATAL: Analysis failed. Check logs at {LOG_FILE_PATH}", file=sys.stderr)
+        raise # Allow the exception to propagate or handle gracefully
+
+
+def print_structural_toc_print(structural_toc:dict)->str|None:
+    """
+    Prints the structural TOC data (bookmarks/outline) in a clean, 
+    hierarchical, and readable console format.
+
+    Args:
+        structural_toc: A list of TOC dictionaries.
+    """
+    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 print_structural_toc(structural_toc: list, print_bool: bool = False) -> str:
+    """
+    Formats the structural TOC data into a hierarchical string and optionally prints it.
+
+    Args:
+        structural_toc: A list of TOC dictionaries.
+        print_bool: Whether to print the output to the console.
+
+    Returns:
+        A formatted string of the structural TOC.
+    """
+    lines = []
+    lines.append("\n" + "=" * 70)
+    lines.append("## Structural Table of Contents (PDF Bookmarks/Outline)")
+    lines.append("=" * 70)
+
+    if not structural_toc:
+        msg = "No structural TOC (bookmarks/outline) found."
+        lines.append(msg)
+        output = "\n".join(lines)
+        if print_bool:
+            print(output)
+        return output
+
+    # Determine max page width for consistent alignment
+    valid_pages = [item['target_page'] for item in structural_toc if isinstance(item['target_page'], int)]
+    max_page = max(valid_pages) if valid_pages else 1
+    page_width = len(str(max_page))
+    
+    # Iterate and format
+    for item in structural_toc:
+        indent = " " * 4 * (item['level'] - 1)
+        # Handle cases where page might be N/A or None
+        target_page = item.get('target_page', "N/A")
+        page_str = str(target_page).rjust(page_width)
+        
+        lines.append(f"{indent}{item['title']} . . . page {page_str}")
+
+    lines.append("-" * 70)
+    
+    # Final aggregation
+    str_structural_toc = "\n".join(lines)
+    
+    if print_bool:
+        print(str_structural_toc)
+        
+    return str_structural_toc

pdflinkcheck/stdlib_server.py

@@ -0,0 +1,176 @@
+# src/pdflinkcheck/stdlib_server.py
+import http.server
+import socketserver
+import json
+import tempfile
+import shutil
+import os
+from pathlib import Path
+import email  # This replaces cgi for multipart parsing
+
+from pdflinkcheck.report import run_report
+
+PORT = 8000
+
+HTML_FORM = """
+<!doctype html>
+<html>
+<head><title>pdflinkcheck Stdlib Server</title></head>
+<body style="font-family: sans-serif; max-width: 800px; margin: 40px auto;">
+  <h1>pdflinkcheck API (Pure Stdlib, without cgi)</h1>
+  <p>Upload a PDF for link/TOC analysis. Zero third-party deps, future-proof.</p>
+  <form action="/" method="post" enctype="multipart/form-data">
+    <p><input type="file" name="file" accept=".pdf" required></p>
+    <p>
+      <label>Engine:</label>
+      <select name="pdf_library">
+        <option value="pypdf" selected>pypdf (pure Python, Termux-friendly)</option>
+        <option value="pymupdf">pymupdf (faster, if installed)</option>
+      </select>
+    </p>
+    <p>
+      <label>Max links to show (0 = all):</label>
+      <input type="number" name="max_links" value="0" min="0">
+    </p>
+    <p><button type="submit">Analyze PDF</button></p>
+  </form>
+  <hr>
+  <p>Returns JSON. Works on Termux & Python 3.13+.</p>
+</body>
+</html>
+"""
+
+class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    allow_reuse_address = True
+
+class PDFLinkCheckHandler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        if self.path == "/":
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(HTML_FORM.encode("utf-8"))
+            return
+            
+        if self.path == "/favicon.ico":
+            return
+            # Silent no-content response (most browsers cache this)
+            self.send_response(204)
+            self.end_headers()
+            return
+        
+        self.send_error(404, "Not Found")
+
+    def do_POST(self):
+        if self.path != "/":
+            self.send_error(404, "Not Found")
+            return
+
+        # Get Content-Type and Content-Length
+        content_type = self.headers.get("Content-Type")
+        if not content_type or "multipart/form-data" not in content_type:
+            self._send_json_error("Expected multipart/form-data", 400)
+            return
+
+        content_length = int(self.headers.get("Content-Length", 0))
+        if content_length == 0:
+            self._send_json_error("No body sent", 400)
+            return
+
+        # Read the entire body
+        body = self.rfile.read(content_length)
+
+        # Parse using email.message (pure stdlib, no cgi)
+        msg = email.message_from_bytes(b"Content-Type: " + content_type.encode() + b"\r\n\r\n" + body)
+
+        if not msg.is_multipart():
+            self._send_json_error("Invalid multipart message", 400)
+            return
+
+        # Extract parts
+        file_item = None
+        pdf_library = "pypdf"
+        max_links = 0
+
+        for part in msg.get_payload():
+            disposition = part.get("Content-Disposition", "")
+            if not disposition.startswith("form-data"):
+                continue
+
+            name = part.get_param("name", header="Content-Disposition")
+            filename = part.get_param("filename", header="Content-Disposition")
+
+            if name == "file" and filename:
+                if not filename.lower().endswith(".pdf"):
+                    self._send_json_error("Only .pdf files allowed", 400)
+                    return
+                file_item = part.get_payload(decode=True)  # bytes
+                file_filename = filename
+
+            elif name == "pdf_library":
+                pdf_library = part.get_payload(decode=True).decode().lower()
+                if pdf_library not in {"pypdf", "pymupdf"}:
+                    self._send_json_error("Invalid pdf_library", 400)
+                    return
+
+            elif name == "max_links":
+                try:
+                    max_links = int(part.get_payload(decode=True).decode())
+                except ValueError:
+                    max_links = 0
+
+        if not file_item:
+            self._send_json_error("No PDF file uploaded", 400)
+            return
+
+        # Save uploaded file to temp
+        tmp_path = None
+        try:
+            with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp_file:
+                tmp_file.write(file_item)
+                tmp_path = tmp_file.name
+
+            result = run_report(
+                pdf_path=tmp_path,
+                max_links=max_links if max_links > 0 else 0,
+                export_format="",
+                pdf_library=pdf_library,
+                print_bool=False
+            )
+
+            response = {
+                "filename": file_filename,
+                "pdf_library_used": pdf_library,
+                "total_links": result["metadata"]["total_links"],
+                "data": result["data"],
+                "text_report": result["text"]
+            }
+
+            self._send_json(response)
+
+        except Exception as e:
+            self._send_json_error(f"Analysis failed: {str(e)}", 500)
+        finally:
+            if tmp_path and os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+
+    def _send_json(self, data, status=200):
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        json_bytes = json.dumps(data, indent=2, ensure_ascii=False).encode("utf-8")
+        self.wfile.write(json_bytes)
+
+    def _send_json_error(self, message, status=400):
+        self._send_json({"error": message}, status)
+
+if __name__ == "__main__":
+    with ThreadedTCPServer(("", PORT), PDFLinkCheckHandler) as httpd:
+        print(f"pdflinkcheck pure-stdlib server (no cgi) running at http://localhost:{PORT}")
+        print("Future-proof for Python 3.13+ • Handles concurrent uploads")
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\nShutting down...")
+            httpd.server_close()