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

pdflinkcheck/gui.py

@@ -1,8 +1,10 @@
 # src/pdflinkcheck/gui.py
 import tkinter as tk
-from tkinter import filedialog, ttk
+from tkinter import filedialog, ttk, messagebox # Added messagebox
 import sys
 from pathlib import Path
+from typing import Optional # Added Optional
+from importlib.resources import files
 
 # Import the core analysis function
 from pdflinkcheck.analyze import run_analysis 
@@ -16,60 +18,140 @@ class RedirectText:
         """Insert the incoming string into the Text widget."""
         self.text_widget.insert(tk.END, string)
         self.text_widget.see(tk.END) # Scroll to the end
-        self.text_widget.update_idletasks() # Refresh GUI
+        ## self.text_widget.update_idletasks() # Refresh GUI << Suppress: The mainloop will handle updates efficiently without forcing them.
 
-    def flush(self):
+    def flush(self, *args):
         """Required for file-like objects, but does nothing here."""
         pass
 
 class PDFLinkCheckerApp(tk.Tk):
     def __init__(self):
         super().__init__()
-        self.title("PDF Link Checker")
+        self.title("PDF Link Check")
         self.geometry("800x600")
         
         # Style for the application
         style = ttk.Style(self)
         style.theme_use('clam')
         
+        # --- 1. Initialize Variables ---
         self.pdf_path = tk.StringVar(value="")
-        self.check_remnants_var = tk.BooleanVar(value=True)
+        self.check_remnants_var = tk.BooleanVar(value=True) 
         self.max_links_var = tk.StringVar(value="50")
-        self.show_all_links_var = tk.BooleanVar(value=False)
+        self.show_all_links_var = tk.BooleanVar(value=True) 
+        self.export_report_format_var = tk.StringVar(value="JSON")
+        self.do_export_report_var = tk.BooleanVar(value=True) 
+
+        self.supported_export_formats = ["JSON", "MD", "TXT"]
+        self.supported_export_formats = ["JSON"]
+        
         
+        # --- 2. Create Widgets ---
         self._create_widgets()
+        
+        # --- 3. Set Initial Dependent Widget States ---
+        self._toggle_max_links_entry() 
+        self._toggle_export_report()
+        
+
+    def _show_license(self):
+        """
+        Reads the embedded LICENSE file (AGPLv3) and displays its content in a new modal window.
+        """
+        try:
+            # CORRECT WAY: Use the Traversable object's read_text() method.
+            # This handles files located inside zip archives (.pyz, pipx venvs) correctly.
+            license_path_traversable = files("pdflinkcheck.data") / "LICENSE"
+            license_content = license_path_traversable.read_text(encoding="utf-8")
+            
+        except FileNotFoundError:
+            messagebox.showerror(
+                "License Error", 
+                "LICENSE file not found within the installation package (pdflinkcheck.data/LICENSE). Check build process."
+            )
+            return
+        except Exception as e:
+            messagebox.showerror("Read Error", f"Failed to read embedded LICENSE file: {e}")
+            return
+
+        # --- Display in a New Toplevel Window ---
+        license_window = tk.Toplevel(self)
+        license_window.title("Software License")
+        license_window.geometry("600x400")
+        
+        # Text widget for content
+        text_widget = tk.Text(license_window, wrap=tk.WORD, font=('Monospace', 10), padx=10, pady=10)
+        text_widget.insert(tk.END, license_content)
+        text_widget.config(state=tk.DISABLED)
+        
+        # Scrollbar
+        scrollbar = ttk.Scrollbar(license_window, command=text_widget.yview)
+        text_widget['yscrollcommand'] = scrollbar.set
+        
+        # Layout
+        scrollbar.pack(side=tk.RIGHT, fill=tk.Y)
+        text_widget.pack(fill='both', expand=True)
+        
+        # Make the window modal (optional, but good practice for notices)
+        license_window.transient(self)
+        license_window.grab_set()
+        self.wait_window(license_window)
 
     def _create_widgets(self):
         # --- Control Frame (Top) ---
         control_frame = ttk.Frame(self, padding="10")
         control_frame.pack(fill='x')
 
-        # File Selection
+        # Row 0: File Selection
         ttk.Label(control_frame, text="PDF Path:").grid(row=0, column=0, padx=5, pady=5, sticky='w')
         ttk.Entry(control_frame, textvariable=self.pdf_path, width=60).grid(row=0, column=1, padx=5, pady=5, sticky='ew')
         ttk.Button(control_frame, text="Browse...", command=self._select_pdf).grid(row=0, column=2, padx=5, pady=5)
 
-        # Options
+        # Row 1: Remnants and Max Links Label/Entry
         ttk.Checkbutton(
             control_frame, 
             text="Check for Remnants (URLs/Emails)", 
             variable=self.check_remnants_var
         ).grid(row=1, column=0, padx=5, pady=5, sticky='w')
 
+        ttk.Label(control_frame, text="Max Links to Display:").grid(row=1, column=1, padx=5, pady=5, sticky='e')
+        self.max_links_entry = ttk.Entry(control_frame, textvariable=self.max_links_var, width=10)
+        self.max_links_entry.grid(row=1, column=2, padx=5, pady=5, sticky='w')
+
+        export_group_frame = ttk.Frame(control_frame)
+        export_group_frame.grid(row=2, column=0, padx=5, pady=5, sticky='w') # Placed in the original Checkbutton's column
+
+        ttk.Checkbutton(
+            export_group_frame, 
+            text="Export Report", 
+            variable=self.do_export_report_var,
+            command=self._toggle_export_report
+        ).pack(side=tk.LEFT, padx=(0, 5)) # Pack Checkbutton to the left with small internal padding
+        self.export_report_format = ttk.Combobox(
+            export_group_frame, 
+            textvariable=self.export_report_format_var,
+            values=self.supported_export_formats,
+            state='readonly', # Prevents user from typing invalid values
+            width=5
+        )
+        self.export_report_format.set(self.supported_export_formats[0]) # Set default text
+        self.export_report_format.pack(side=tk.LEFT)
+         # Pack Entry tightly next to it
+
         ttk.Checkbutton(
             control_frame, 
             text="Show All Links (Override Max)", 
             variable=self.show_all_links_var,
-            # Optional: Disable max_links entry when this is checked
             command=self._toggle_max_links_entry
-        ).grid(row=2, column=0, padx=5, pady=5, sticky='w')
+        ).grid(row=2, column=2, padx=5, pady=5, sticky='w')
 
-        ttk.Label(control_frame, text="Max Links to Display:").grid(row=1, column=1, padx=5, pady=5, sticky='e')
-        self.max_links_entry = ttk.Entry(control_frame, textvariable=self.max_links_var, width=10)
-        self.max_links_entry.grid(row=1, column=2, padx=5, pady=5, sticky='w')
+        # Row 3: Run Button and License Button
+        run_btn = ttk.Button(control_frame, text="▶ Run Analysis", command=self._run_analysis_gui, style='Accent.TButton')
+        run_btn.grid(row=3, column=0, columnspan=2, pady=10, sticky='ew', padx=(0, 5))
         
-        # Run Button
-        ttk.Button(control_frame, text="▶ Run Analysis", command=self._run_analysis_gui, style='Accent.TButton').grid(row=2, column=0, columnspan=3, pady=10)
+        license_btn = ttk.Button(control_frame, text="Show License", command=self._show_license)
+        license_btn.grid(row=3, column=2, columnspan=1, pady=10, sticky='ew', padx=(5, 0)) # Sticky 'ew' makes it fill
+
         
         control_frame.grid_columnconfigure(1, weight=1)
 
@@ -80,16 +162,26 @@ class PDFLinkCheckerApp(tk.Tk):
         ttk.Label(output_frame, text="Analysis Report Output:").pack(fill='x')
         
         # Scrollable Text Widget for output
-        self.output_text = tk.Text(output_frame, wrap=tk.WORD, state=tk.DISABLED, bg='#333333', fg='white', font=('Monospace', 10))
-        self.output_text.pack(fill='both', expand=True, padx=5, pady=5)
+        # Use an internal frame for text and scrollbar to ensure correct packing
+        text_scroll_frame = ttk.Frame(output_frame)
+        text_scroll_frame.pack(fill='both', expand=True, padx=5, pady=5)
         
-        # Scrollbar
-        scrollbar = ttk.Scrollbar(output_frame, command=self.output_text.yview)
-        self.output_text['yscrollcommand'] = scrollbar.set
+        self.output_text = tk.Text(text_scroll_frame, wrap=tk.WORD, state=tk.DISABLED, bg='#333333', fg='white', font=('Monospace', 10))
+        self.output_text.pack(side=tk.LEFT, fill='both', expand=True) # Text fills and expands
+
+        # Scrollbar (Scrollbar must be packed AFTER the text widget)
+        scrollbar = ttk.Scrollbar(text_scroll_frame, command=self.output_text.yview)
         scrollbar.pack(side=tk.RIGHT, fill=tk.Y)
+        self.output_text['yscrollcommand'] = scrollbar.set # Link text widget back to scrollbar
 
     def _select_pdf(self):
+        if self.pdf_path.get():
+            initialdir = str(Path(self.pdf_path.get()).parent)
+        else:
+            initialdir = str(Path.cwd())
+
         file_path = filedialog.askopenfilename(
+            initialdir=initialdir,
             defaultextension=".pdf",
             filetypes=[("PDF files", "*.pdf"), ("All files", "*.*")]
         )
@@ -103,6 +195,13 @@ class PDFLinkCheckerApp(tk.Tk):
         else:
             self.max_links_entry.config(state=tk.NORMAL)
 
+    def _toggle_export_report(self):
+        """Enables/disables the report file export."""
+        if self.do_export_report_var.get():
+            self.export_report_format.config(state=tk.NORMAL)
+        else:
+            self.export_report_format.config(state=tk.DISABLED)
+
     def _run_analysis_gui(self):
         pdf_path_str = self.pdf_path.get()
         if not Path(pdf_path_str).exists():
@@ -110,18 +209,21 @@ class PDFLinkCheckerApp(tk.Tk):
             return
         
         if self.show_all_links_var.get():
-            # Pass 0 to the backend, which analyze.py interprets as "Show All"
             max_links_to_pass = 0 
         else:
             try:
                 max_links_to_pass = int(self.max_links_var.get())
-                if max_links_to_pass <= 0:
+                if max_links_to_pass < 1:
                      self._display_error("Error: Max Links must be a positive number (or use 'Show All').")
                      return
             except ValueError:
                 self._display_error("Error: Max Links must be an integer.")
                 return
 
+        export_format = None
+        if self.do_export_report_var.get():
+            export_format = self.export_report_format_var.get().lower()
+
         # 1. Clear previous output and enable editing
         self.output_text.config(state=tk.NORMAL)
         self.output_text.delete('1.0', tk.END)
@@ -136,11 +238,13 @@ class PDFLinkCheckerApp(tk.Tk):
             run_analysis(
                 pdf_path=pdf_path_str,
                 check_remnants=self.check_remnants_var.get(),
-                max_links=max_links_to_pass
+                max_links=max_links_to_pass,
+                export_format=export_format
             )
             self.output_text.insert(tk.END, "\n--- Analysis Complete ---\n")
 
         except Exception as e:
+            self.output_text.insert(tk.END, "\n")
             self._display_error(f"An unexpected error occurred during analysis: {e}")
 
         finally:
@@ -149,17 +253,41 @@ class PDFLinkCheckerApp(tk.Tk):
             self.output_text.config(state=tk.DISABLED)
 
     def _display_error(self, message):
-        self.output_text.config(state=tk.NORMAL)
-        self.output_text.delete('1.0', tk.END)
+        # Ensure output is in normal state to write
+        original_state = self.output_text.cget('state')
+        if original_state == tk.DISABLED:
+            self.output_text.config(state=tk.NORMAL)
+            
+        #self.output_text.delete('1.0', tk.END)
         self.output_text.insert(tk.END, f"[ERROR] {message}\n", 'error')
         self.output_text.tag_config('error', foreground='red')
+
+        # Restore state
         self.output_text.config(state=tk.DISABLED)
 
 
-def start_gui():
-    """Entry point function to launch the application."""
-    app = PDFLinkCheckerApp()
-    app.mainloop()
+def auto_close_window(root, delay_ms:int = 0):
+    """
+    Schedules the Tkinter window to be destroyed after a specified delay.
+    """
+    if delay_ms > 0:
+        print(f"Window is set to automatically close in {delay_ms/1000} seconds.")
+        root.after(delay_ms, root.destroy)
+    else:
+        return
+
+
+def start_gui(time_auto_close:int=0):
+    """
+    Entry point function to launch the application.
+    """
+    print("pdflinkcheck: start_gui ...")
+    tk_app = PDFLinkCheckerApp()
+
+    auto_close_window(tk_app, time_auto_close)
+
+    tk_app.mainloop()
+    print("pdflinkcheck: gui closed.")
 
 if __name__ == "__main__":
     start_gui()

pdflinkcheck/io.py

@@ -0,0 +1,106 @@
+# src/pdflinkcheck/io.py
+import logging
+import json
+from pathlib import Path
+from typing import Dict, Any, Union, List
+
+# --- Configuration ---
+
+# Define the base directory for pdflinkcheck data (~/.pdflinkcheck)
+try:
+    # Use the home directory and append the tool's name
+    PDFLINKCHECK_HOME = Path.home() / ".pdflinkcheck"
+except Exception:
+    # Fallback if Path.home() fails in certain environments (e.g., some CI runners)
+    PDFLINKCHECK_HOME = Path("/tmp/.pdflinkcheck_temp")
+
+# Ensure the directory exists
+PDFLINKCHECK_HOME.mkdir(parents=True, exist_ok=True)
+
+# Define the log file path
+LOG_FILE_PATH = PDFLINKCHECK_HOME / "pdflinkcheck_errors.log"
+
+# --- Logging Setup ---
+
+# Set up a basic logger for error tracking
+def setup_error_logger():
+    """
+    Configures a basic logger that writes errors and warnings to a file 
+    in the PDFLINKCHECK_HOME directory.
+    """
+    # Create the logger instance
+    logger = logging.getLogger('pdflinkcheck_logger')
+    logger.setLevel(logging.WARNING) # Log WARNING and above
+
+    # Prevent propagation to the root logger (which might print to console)
+    logger.propagate = False 
+
+    # Create file handler
+    file_handler = logging.FileHandler(LOG_FILE_PATH, mode='a')
+    file_handler.setLevel(logging.WARNING)
+    
+    # Create formatter
+    formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+    file_handler.setFormatter(formatter)
+    
+    # Check if the handler is already added (prevents duplicate log entries)
+    if not any(isinstance(handler, logging.FileHandler) for handler in logger.handlers):
+        logger.addHandler(file_handler)
+
+    return logger
+
+# Initialize the logger instance
+error_logger = setup_error_logger()
+
+# --- Export Functionality ---
+
+def export_report_data(
+    report_data: Dict[str, Any], 
+    pdf_filename: str, 
+    export_format: str = "JSON"
+) -> 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.
+        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).
+
+    Returns:
+        The path object pointing to the successfully created report file.
+        
+    Raises:
+        ValueError: If the export_format is not supported.
+    """
+    if export_format.upper() != "JSON":
+        error_logger.error(f"Unsupported export format requested: {export_format}")
+        raise ValueError("Only 'JSON' format is currently supported for report export.")
+        
+    # 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_path = PDFLINKCHECK_HOME / output_filename
+
+    try:
+        with open(output_path, 'w', encoding='utf-8') as f:
+            # Use indent for readability
+            json.dump(report_data, f, indent=4)
+            
+        print(f"\nReport successfully exported to: {output_path}")
+        return output_path
+        
+    except Exception as e:
+        error_logger.error(f"Failed to export report to JSON: {e}", exc_info=True)
+        # 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.")
+
+

pdflinkcheck-1.1.47.dist-info/METADATA

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: pdflinkcheck
+Version: 1.1.47
+Summary: A purpose-built PDF link analysis and reporting tool with GUI and CLI.
+Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
+Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/pdflinkcheck
+Project-URL: Repository, https://github.com/city-of-memphis-wastewater/pdflinkcheck
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Other Audience
+Classifier: Topic :: File Formats
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Typing :: Typed
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyhabitat>=1.0.53
+Requires-Dist: pymupdf>=1.26.6
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1.13; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# pdflinkcheck
+
+A purpose-built tool for comprehensive analysis of hyperlinks and link remnants within PDF documents, primarily using the PyMuPDF library. Use the CLI or the GUI.
+
+-----
+
+![Screenshot of the pdflinkcheck GUI](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_gui_v1.1.32.png)
+
+-----
+
+## 📥 Access and Installation
+
+The recommended way to use `pdflinkcheck` is to either install the CLI with `pipx` or to download the appropriate latest binary for your system from [Releases](https://github.com/City-of-Memphis-Wastewater/pdflinkcheck/releases/).
+
+### 🚀 Recommended Access (Binary Files)
+
+For the most user-typical experience, download the single-file binary matching your OS.
+
+| **File Type** | **Primary Use Case** | **Recommended Launch Method** |
+| :--- | :--- | :--- |
+| **Executable (.exe, .elf, .pyz)** | **GUI (Double-Click)** | Double-click the file (use the accompanying `.bat` file on Windows). |
+| **PYZ (Python Zip App)** | **CLI (Terminal)** | Run using your system's `python` command: `python pdflinkcheck-VERSION.pyz analyze ...` |
+
+### Installation via pipx
+
+For an isolated environment where you can access `pdflinkcheck` from any terminal:
+
+```bash
+# Ensure you have pipx installed first (if not, run: pip install pipx)
+pipx install pdflinkcheck
+```
+
+-----
+
+## 💻 Graphical User Interface (GUI)
+
+The tool can be run as simple cross-platform graphical interface (Tkinter).
+
+### Launching the GUI
+
+There are three ways to launch the GUI interface:
+
+1.  **Implicit Launch:** Run the main command with no arguments, subcommands, or flags (`pdflinkcheck`).
+2.  **Explicit Command:** Use the dedicated GUI subcommand (`pdflinkcheck gui`).
+3.  **Binary Double-Click:**
+      * **Windows:** Double-click the `pdflinkcheck-VERSION-gui.bat` file.
+      * **macOS/Linux:** Double-click the downloaded `.pyz` or `.elf` file.
+
+### Planned GUI Updates
+
+We are actively working on the following enhancements:
+
+  * **Report Export:** Functionality to export the full analysis report to a plain text file.
+  * **License Visibility:** A dedicated "License Info" button within the GUI to display the terms of the AGPLv3+ license.
+
+-----
+
+## 🚀 CLI Usage
+
+The core functionality is accessed via the `analyze` command. All commands include the built-in `--help` flag for quick reference.
+
+### Available Commands
+
+|**Command**|**Description**|
+|---|---|
+|`pdflinkcheck analyze`|Analyzes a PDF file for links and remnants.|
+|`pdflinkcheck gui`|Explicitly launch the Graphical User Interface.|
+|`pdflinkcheck license`|**Displays the full AGPLv3+ license text in the terminal.**|
+
+### `analyze` Command Options
+
+|**Option**|**Description**|**Default**|
+|---|---|---|
+|`<PDF_PATH>`|**Required.** The path to the PDF file to analyze.|N/A|
+|`--check-remnants / --no-check-remnants`|Toggle scanning the text layer for unlinked URLs/Emails.|`--check-remnants`|
+|`--max-links INTEGER`|Maximum number of links/remnants to display in the detailed report sections. Use `0` to show all.|`0` (Show All)|
+|`--export-format FORMAT`|Format for the exported report. If specified, the report is saved to a file named after the PDF. Currently supported: `JSON`.|`JSON`|
+|`--help`|Show command help and exit.|N/A|
+
+### `gui` Command Options
+
+| **Option**             | **Description**                                                                                               | **Default**    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------- | -------------- |
+| `--auto-close INTEGER` | **(For testing/automation only).** Delay in milliseconds after which the GUI window will automatically close. | `0` (Disabled) |
+#### Example Runs
+
+
+
+```bash 
+# Analyze a document, show all links/remnants, and save the report as JSON
+pdflinkcheck analyze "TE Maxson WWTF O&M Manual.pdf" --export-format JSON
+
+# Analyze a document but skip the time-consuming remnant check
+pdflinkcheck analyze "another_doc.pdf" --no-check-remnants 
+
+# Analyze a document but keep the print block short, showing only the first 10 links for each type
+pdflinkcheck analyze "TE Maxson WWTF O&M Manual.pdf" --max-links 10
+
+# Show the GUI for only a moment, like in a build check
+pdflinkcheck gui --auto-close 3000 
+```
+
+
+-----
+
+## 📦 Library Access (Advanced)
+
+For developers importing `pdflinkcheck` into other Python projects, the core analysis functions are exposed directly in the root namespace:
+
+|**Function**|**Description**|
+|---|---|
+|`run_analysis()`|**(Primary function)** Performs the full analysis, prints to console, and handles file export.|
+|`extract_links()`|Low-level function to retrieve all explicit links (URIs, GoTo, etc.) from a PDF path.|
+|`extract_toc()`|Low-level function to extract the PDF's internal Table of Contents (bookmarks/outline).|
+
+Python
+
+```
+from pdflinkcheck.analyze import run_analysis, extract_links, extract_toc
+```
+
+-----
+
+## ✨ Features
+
+  * **Active Link Extraction:** Identifies and categorizes all programmed links (External URIs, Internal GoTo/Destinations, Remote Jumps).
+  * **Anchor Text Retrieval:** Extracts the visible text corresponding to each link's bounding box.
+  * **Remnant Detection:** Scans the document's text layer for unlinked URIs and email addresses that should potentially be converted into active links.
+  * **Structural TOC:** Extracts the PDF's internal Table of Contents (bookmarks/outline).
+
+-----
+
+## 📜 License Implications (AGPLv3+)
+
+**pdflinkcheck is licensed under the GNU Affero General Public License version 3 or later (AGPLv3+).**
+
+This license has significant implications for **distribution and network use**, particularly for organizations:
+
+  * **Source Code Provision:** If you distribute this tool (modified or unmodified) to anyone, you **must** provide the full source code under the same license.
+  * **Network Interaction (Affero Clause):** If you modify this tool and make the modified version available to users over a computer network (e.g., as a web service or backend), you **must** also offer the source code to those network users.
+
+> **Before deploying or modifying this tool for organizational use, especially for internal web services or distribution, please ensure compliance with the AGPLv3+ terms.**
+
+-----
+
+## 🥚 Optional REPL‑Friendly GUI Access (Easter Egg)
+
+For users who prefer exploring tools interactively—especially those coming from MATLAB or other REPL‑first environments—`pdflinkcheck` includes an optional Easter egg that exposes the GUI launcher directly in the library namespace.
+
+This feature is **disabled by default** and has **no effect on normal imports**.
+
+### Enabling the Easter Egg
+
+Set the environment variable before importing the library:
+
+```python
+import os
+os.environ["PDFLINKCHECK_GUI_EASTEREGG"] = "true"
+
+import pdflinkcheck
+pdflinkcheck.start_gui()
+```
+
+Accepted values include: `true`, `1`, `yes`, `on` (case‑insensitive).
+
+### Purpose
+
+This opt‑in behavior is designed to make the library feel welcoming to beginners who are experimenting in a Python REPL for the first time. When enabled, the `start_gui()` function becomes available at the top level:
+
+```python
+pdflinkcheck.start_gui()
+```
+
+If the `PDFLINKCHECK_GUI_EASTEREGG` environment variable is not set—or if GUI support is unavailable—`pdflinkcheck` behaves as a normal library with no GUI functions exposed.
+
+-----
+
+## ⚠️ Compatibility Notes
+
+### Platform Compatibility: 
+
+This tool relies on the `PyMuPDF` library. 
+All testing has failed to run in a **Termux (Android)** environment due to underlying C/C++ library compilation issues with PyMuPDF. 
+It is recommended for use on standard Linux, macOS, or Windows operating systems.
+
+#### Termux Compatibility as a Key Goal
+A key goal of City-of-Memphis-Wastewater is to release all software as Termux-compatible. Unfortunately, that simply isn't possible with PyMuPDF as a dependency. 
+We tried alternative PDF libaries like `pdfminer`, `pdfplumber`, and `borb`, but none of these offered the level of detail concerning GoTo links.
+Due to Termux compatibility goals, we do not generally make Tkinter-based interfaces, so that was a fun, minimalist opportunity on this project. 
+
+Termux compatibility is important in the modern age as Android devices are common among technicians, field engineers, and maintenace staff. 
+Android is the most common operating system in the Global South. 
+We aim to produce stable software that can do the most possible good. 
+
+We love web-stack GUIs served locally as a final product.
+All that packaged up into a Termux-compatible ELF or PYZ - What could be better!
+
+In the future we may find a work-around and be able to drop the PyMuPDF dependency. 
+This would have lots of implications:
+- Reduced artifact size.
+- Alpine-compatible Docker image.
+- Web-stack GUI rather than Tkinter, to be compatible with Termux.
+- A different license from the AGPL3, if we choose at that time.
+
+In the meantime, the standalone binaries and pipx installation provide excellent cross-platform support on Windows, macOS, and standard Linux desktops/laptops.
+
+### Document Compatibility: 
+While `pdflinkcheck` uses the robust PyMuPDF library, not all PDF files can be processed successfully. This tool is designed primarily for digitally generated (vector-based) PDFs.
+
+Processing may fail or yield incomplete results for:
+* **Scanned PDFs** (images of text) that lack an accessible text layer.
+* **Encrypted or Password-Protected** documents.
+* **Malformed or non-standard** PDF files.
+
+-----
+
+## Run from Source (Developers)
+
+```bash
+git clone http://github.com/city-of-memphis-wastewater/pdflinkcheck.git
+cd pdflinkcheck
+uv sync
+uv run python src/pdflinkcheck/cli.py --help
+```