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

pdflinkcheck/data/README.md

@@ -0,0 +1,278 @@
+# pdflinkcheck
+
+A purpose-built tool for comprehensive analysis of hyperlinks and GoTo links within PDF documents. Users may leverage either the PyMuPDF or the pypdf 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.58.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/).
+
+### 🚀 Release Artifact Files (EXE, PYZ, ELF)
+
+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)** | **GUI** | Double-click the file. |
+| **PYZ (Python Zip App)** | **CLI** or **GUI** | Run using your system's `python` command: `python pdflinkcheck-VERSION.pyz --help` |
+
+### 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[full]
+
+# On Termux
+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. 
+
+`DEV_TYPER_HELP_TREE=1 pdflinkcheck help-tree`:
+![Screenshot of the pdflinkcheck CLI Tree Help](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_cli_v1.1.58_tree_help.png)
+
+`pdflinkcheck --help`:
+![Screenshot of the pdflinkcheck CLI Tree Help](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_cli_v1.1.58.png)
+
+
+### Available Commands
+
+|**Command**|**Description**|
+|---|---|
+|`pdflinkcheck analyze`|Analyzes a PDF file for links |
+|`pdflinkcheck gui`|Explicitly launch the Graphical User Interface.|
+|`pdflinkcheck docs`|Access documentation, including the README and AGPLv3+ license.|
+
+### `analyze` Command Options
+
+|**Option**|**Description**|**Default**|
+|---|---|---|
+|`<PDF_PATH>`|**Required.** The path to the PDF file to analyze.|N/A|
+|`--pdf-library / -p`|Select engine: `pymupdf` or `pypdf`.|`pypdf`|
+|`--export-format / -e`|Export to `JSON`, `TXT`, or `None` to suppress file output.|`JSON`|
+|`--max-links / -m`|Maximum links to display per section. Use `0` for all.|`0`|
+
+### `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, and save the report as JSON and TXT
+pdflinkcheck analyze "TE Maxson WWTF O&M Manual.pdf" --export-format JSON,TXT
+
+# 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 
+
+# Show both the LICENSE and README.md docs
+pdflinkcheck docs --license --readme 
+```
+
+-----
+
+## 📦 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_report()`|**(Primary function)** Performs the full analysis, prints to console, and handles file export.|
+|`extract_links_pynupdf()`|Function to retrieve all explicit links (URIs, GoTo, etc.) from a PDF path.|
+|`extract_toc_pymupdf()`|Function to extract the PDF's internal Table of Contents (bookmarks/outline).|
+|`extract_links_pynupdf()`|Function to retrieve all explicit links (URIs, GoTo, etc.) from a PDF path, using the pypdf library.|
+|`extract_toc_pymupdf()`|Function to extract the PDF's internal Table of Contents (bookmarks/outline), using the pypdf library.|
+
+Exanple:
+
+```python
+from pdflinkcheck.report import run_report
+from pdflinkcheck.analysis_pymupdf import extract_links_pymupdf, extract_toc_pymupdf                                                                          130 from pdflinkcheck.analysis_pymupdf import extract_links_pynupdf, extract_toc_pymupdf
+from pdflinkcheck.analysis_pypdf import extract_links_pypdf, extract_toc_pypdf
+
+file = "document1.pdf"
+report_data = run_report(file)
+links_pymupdf = extract_links_pymupdf(file)
+links_pypdf = extract_links_pypdf(file)
+```
+
+-----
+
+## ✨ 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.
+  * **Structural TOC:** Extracts the PDF's internal Table of Contents (bookmarks/outline).
+
+-----
+
+## 🥚 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.
+
+### Another Easter Egg
+
+```bash
+DEV_TYPER_HELP_TREE=1 pdflinkcheck help-tree
+```
+
+This `help-tree` feature has not yet been submitted for inclusion into Typer.
+
+-----
+
+## ⚠️ Compatibility Notes
+
+#### Termux Compatibility as a Key Goal
+A key goal of City-of-Memphis-Wastewater is to release all software as Termux-compatible.
+
+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. 
+
+While using `PyMuPDF` in Python dependency resolution on Termux simply isn't possible, we are proud to have achieved a work-around by implementing a parallel solution in `pypdf`! 
+Now, there is PDF Engine selection in both the CLI and the GUI. 
+`pypdf` is the default in pdflinkcheck.report.run_report(); PyMuPDF can be explicitly requested in the CLI and is the default in the TKinter GUI.
+
+Now that `pdflinkcheck` can run on Termux, we may find a work-around and be able to drop the PyMuPDF dependency. 
+- Build `pypdf`-only artifacts, to reduce size.
+- Build a web-stack GUI as an alternative to the Tkinter GUI, to be compatible with Termux.
+
+Because it works, we plan to keep the `PyMuPDF` portion of the codebase.
+
+### Document Compatibility: 
+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.
+
+-----
+
+## PDF Library Selection
+At long last, `PyMuPDF` is an optional dependency. The default is `pypdf`. All testing has shown identical performance, though the `analyze_pymupdf.py` is faster and more direct and robust than `analyze_pypdf.py`, which requires a lot of intentional parsing. 
+
+Binaries and artifacts are expected to contain PyMuPDF, unless they are build on Android. The GUI and CLI interfaces both allow selection of the library; if PyMuPDF is selected but is not available, the user will be warned.
+
+To install the complete version use one of these options:
+
+```bash
+pip install "pdflinkcheck[full]"
+pipx install "pdflinkcheck[full]"
+uv tool install "pdflinkcheck[full]"
+uv add "pdflinkcheck[full]"
+```
+
+-----
+
+## Run from Source (Developers)
+
+```bash
+git clone http://github.com/city-of-memphis-wastewater/pdflinkcheck.git
+cd pdflinkcheck
+
+# To include the PyMuPDF dependency in the installation:
+uv sync --extras full
+
+# On Termux, to not include PyMuPDF:
+uv sync
+
+# To include developer depedecies:
+uv sync --all-extras --group dev
+
+# Run the CLI
+uv run python src/pdflinkcheck/cli.py --help
+
+# Run a basic webapp and Termux-facing browser-based interface
+uv run  python -m pdflinkcheck.stdlib_server
+```
+
+-----
+
+## 📜 License Implications (AGPLv3+)
+
+**`pdflinkcheck` is licensed under the `GNU Affero General Public License` version 3 or later (`AGPLv3+`).**
+
+The `AGPL3+` is required for portions of this codebase because `pdflinkcheck` uses `PyMuPDF`, which is licensed under the `AGPL3`.
+
+To stay in compliance, the AGPL3 license text is readily available in the CLI and the GUI, and it is included in the build artifacts.
+The `AGPL3` appears as the primary license file in the source code. While this infers that the entire project is AGPL3-licensed, this is not true - portions of the codebase are MIT-licensed.
+
+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.**
+
+Links:
+- Source code: https://github.com/City-of-Memphis-Wastewater/pdflinkcheck/  
+- Official AGPLv3 Text (FSF): https://www.gnu.org/licenses/agpl-3.0.html
+
+Copyright © 2025 George Clayton Bennett

pdflinkcheck/data/pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "pdflinkcheck"
+version = "1.1.72"
+description = "A purpose-built PDF link analysis and reporting tool with GUI and CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pyhabitat>=1.0.53",
+    "pypdf>=6.4.2",
+    "rich>=14.2.0",
+    "typer>=0.20.0",
+]
+license-files = ["LICENSE"]
+classifiers=[
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Operating System :: OS Independent",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers", # library and documentation
+    "Intended Audience :: Science/Research", # Technical manuals, engineering
+    "Intended Audience :: Other Audience", # Government/engineering docs
+    "Topic :: File Formats",
+    "Topic :: Office/Business",
+    "Topic :: Text Processing :: General",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Environment :: Win32 (MS Windows)",
+    "Typing :: Typed",
+    "Development Status :: 4 - Beta",
+    #"Development Status :: 5 - Production/Stable",
+]
+authors = [
+    { name = "George Clayton Bennett", email = "george.bennett@memphistn.gov" },
+]
+maintainers = [
+    { name = "George Clayton Bennett", email = "george.bennett@memphistn.gov" },
+]
+
+[project.urls]
+Homepage = "https://github.com/city-of-memphis-wastewater/pdflinkcheck"
+Repository = "https://github.com/city-of-memphis-wastewater/pdflinkcheck"
+
+[project.scripts]
+pdflinkcheck = "pdflinkcheck.cli:app"
+
+[project.optional-dependencies]
+# This allows users to do: pip install pdflinkcheck[full]
+full = [
+    #"pymupdf>=1.26.7 ; platform_system == 'Linux' and platform_machine != 'aarch64'" # to avoid on termux
+    "pymupdf>=1.26.7"  # let them try
+]
+gui = [
+    "sv-ttk>=2.6.1",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.3.0",
+    "pyinstaller>=6.17.0",
+    "shiv>=1.0.8",
+    "ruff>=0.7.0 ; platform_system == 'Linux' and platform_machine != 'aarch64'", # to avoid on termux
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "sv-ttk>=2.6.1",
+]
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+#[tool.hatch.build.targets.wheel]
+#packages = ["src/pdflinkcheck"]
+#artifacts = [
+#    "src/pdflinkcheck/data/LICENSE",
+#    "src/pdflinkcheck/data/README.md"
+#    ]
+    
+#[tool.uv.build-backend.data]
+#data = ["src/pdflinkcheck/data"]
+
+#[tool.hatch.build.targets.wheel.force-include]
+#"pyproject.toml" = "pdflinkcheck/data/pyproject.toml"
+
+#[tool.hatch.build.targets.sdist]
+#include = [
+#    "pyproject.toml",
+#    "src/pdflinkcheck/data/LICENSE",
+#    "src/pdflinkcheck/data/README.md",
+#]
+
+

pdflinkcheck/datacopy.py

@@ -0,0 +1,60 @@
+# src/pdflinkcheck/datacopy.py
+import shutil
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+
+
+# --- COPY LICENSE FILE TO PACKAGE DATA ---
+def ensure_package_pyproject(source_root_path: Path, package_data_path: Path):
+    """Copies the root puyproject.toml file into the expected package data path."""
+    source = source_root_path / "pyproject.toml"
+    destination = package_data_path / "src" / "pdflinkcheck" / "data" / "pyproject.toml"
+
+    if not source.exists():
+        print(f"FATAL: Root pyproject.toml file not found at {source}!", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Ensuring package pyproject.toml is copied to: {destination}")
+    destination.parent.mkdir(parents=True, exist_ok=True) # Ensure data dir exists
+    shutil.copy2(source, destination) # copy2 preserves metadata
+
+
+# --- COPY LICENSE FILE TO PACKAGE DATA ---
+def ensure_package_license(source_root_path: Path, package_data_path: Path):
+    """Copies the root LICENSE file into the expected package data path."""
+    source = source_root_path / "LICENSE"
+    destination = package_data_path / "src" / "pdflinkcheck" / "data" / "LICENSE"
+
+    if not source.exists():
+        print(f"FATAL: Root license file not found at {source}!", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Ensuring package license is copied to: {destination}")
+    destination.parent.mkdir(parents=True, exist_ok=True) # Ensure data dir exists
+    shutil.copy2(source, destination) # copy2 preserves metadata
+
+# --- COPY README FILE TO PACKAGE DATA ---
+def ensure_package_readme(source_root_path: Path, package_data_path: Path):
+    """Copies the root README.md file into the expected package data path."""
+    source = source_root_path / "README.md"
+    destination = package_data_path / "src" / "pdflinkcheck" / "data" / "README.md"
+
+    if not source.exists():
+        print(f"FATAL: Root README file not found at {source}!", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Ensuring package README is copied to: {destination}")
+    destination.parent.mkdir(parents=True, exist_ok=True) # Ensure data dir exists
+    shutil.copy2(source, destination) # copy2 preserves metadata
+
+
+def ensure_data_files_for_build():
+    print(f"PROJECT_ROOT = {PROJECT_ROOT}")
+    ensure_package_license(PROJECT_ROOT, PROJECT_ROOT)
+    ensure_package_readme(PROJECT_ROOT, PROJECT_ROOT)
+    ensure_package_pyproject(PROJECT_ROOT, PROJECT_ROOT)
+
+if __name__ == "__main__":
+    ensure_data_files_for_build()

pdflinkcheck/dev.py

@@ -0,0 +1,109 @@
+# pdflinkcheck/dev.py
+
+"""
+Experiemental developer-facing function(s).
+
+help_tree_command() used click and typer internals which might change version to version.
+
+This portion of the codebase is MIT licensed. It does not rely on any AGPL-licensed code.
+
+---
+
+MIT License
+
+Copyright (c) 2025 George Clayton Bennett <george.bennett@memphistn.gov>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+"""
+
+import typer
+from rich.tree import Tree 
+from rich.panel import Panel
+import click
+
+from pdflinkcheck.version_info import get_version_from_pyproject # change to import from pyhabitat
+
+def add_typer_help_tree(app,
+                  console):
+    @app.command(name="help-tree",
+                 #envvar="PDF_ENGINE",
+                 help="Show all commands and options in a tree structure.")
+    def help_tree_command(ctx: typer.Context):
+        """
+        Fragile developer-facing function.
+        Generates and prints a tree view of the CLI structure (commands and flags).
+        """
+        root_app_command = ctx.parent.command 
+        
+        # 1. Start the Rich Tree structure
+        app_tree = Tree(
+            f"[bold blue]{root_app_command.name}[/bold blue] (v{get_version_from_pyproject()})",
+            guide_style="cyan"
+        )
+
+        # 2. Iterate through all subcommands of the main app
+        for command_name in sorted(root_app_command.commands.keys()):
+            command = root_app_command.commands[command_name]
+            
+            if command.name == "tree-help":
+                continue
+
+            help_text = command.help.splitlines()[0].strip() if command.help else "No help available."
+
+            command_branch = app_tree.add(f"[bold white]{command.name}[/bold white] - [dim]{help_text}[/dim]")
+
+            # 3. Add Arguments and Options (Flags)
+            params_branch = command_branch.add("[yellow]Parameters[/yellow]:")
+            
+            if not command.params:
+                params_branch.add("[dim]None[/dim]")
+            
+            for param in command.params:
+                # New, safer check: Check if param is an Option by looking for opts attribute 
+                # and ensuring it has a flag declaration (starts with '-')
+                is_option = hasattr(param, 'opts') and param.opts and param.opts[0].startswith('-')
+                
+                if is_option:
+                    # This is an Option/Flag
+                    flag_names = " / ".join(param.opts)
+                    
+                    # Filter out the default Typer/Click flags like --help
+                    if flag_names in ("-h", "--help"):
+                        continue
+                    
+                    # Handling default value safely
+                    # Check for None explicitly, as well as the Typer/Click internal sentinel value for not provided.
+                    default_value = getattr(param, 'default', None)
+
+                    # This is the sentinel value used by the Click/Typer internals
+                    if default_value not in (None, click.core.UNSET):
+                        default = f"[dim] (default: {default_value})[/dim]"
+                    else:
+                        default = ""
+                    
+                    params_branch.add(f"[green]{flag_names}[/green]: [dim]{param.help}[/dim]{default}")
+                else:
+                    # This is an Argument (Positional)
+                    # Arguments have a single name property, not an opts list.
+                    arg_name = param.human_readable_name.upper()
+                    params_branch.add(f"[magenta]ARG: {arg_name}[/magenta]: [dim]{param.help}[/dim]")
+
+        # 4. Print the final Panel containing the tree
+        console.print(Panel(app_tree, title=f"[bold]{root_app_command.name} CLI Tree Help[/bold]", border_style="blue"))