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

pdflinkcheck-1.1.72.dist-info/METADATA

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: pdflinkcheck
+Version: 1.1.72
+Summary: A purpose-built PDF link analysis and reporting tool with GUI and CLI.
+Author: George Clayton Bennett
+Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
+License-File: LICENSE
+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-Dist: pyhabitat>=1.0.53
+Requires-Dist: pypdf>=6.4.2
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.0
+Requires-Dist: pymupdf>=1.26.7 ; extra == 'full'
+Requires-Dist: sv-ttk>=2.6.1 ; extra == 'gui'
+Maintainer: George Clayton Bennett
+Maintainer-email: George Clayton Bennett <george.bennett@memphistn.gov>
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/pdflinkcheck
+Project-URL: Repository, https://github.com/city-of-memphis-wastewater/pdflinkcheck
+Provides-Extra: full
+Provides-Extra: gui
+Description-Content-Type: text/markdown
+
+# 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-1.1.72.dist-info/RECORD

@@ -0,0 +1,21 @@
+pdflinkcheck/__init__.py,sha256=KyoFlScM3kPrp1HjcxHDFEf4YflsoYclVF99-rerl3E,2510
+pdflinkcheck/analyze_pymupdf.py,sha256=Be17KJQnTX9OoAluoE2GzPXC3mDCo7VGCNuwc9ilosc,12452
+pdflinkcheck/analyze_pypdf.py,sha256=gHF9o6EY4sie727vS6YjTCQSzw_XWZape4xEk-l4lRI,6397
+pdflinkcheck/analyze_pypdf_v2.py,sha256=dAvq2OoiN1MjptWSgOrAlArg0A98Hvpr105BKXJBrjE,7563
+pdflinkcheck/cli.py,sha256=8PTkbK4msbhYB2NUCkUv8DWU7lO2qYg8qQKT_cB2U6w,12634
+pdflinkcheck/data/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+pdflinkcheck/data/README.md,sha256=9tM77vu5jTpFQplL2A-ysyVyOQg8QZISsmtcmEfQXZM,11650
+pdflinkcheck/data/pyproject.toml,sha256=nsh5tK1V_MD7iPTXjxcPjWPi5xXEbmUW7iWn-MfxxJo,2955
+pdflinkcheck/datacopy.py,sha256=pZysPvfsvRe3qvA-du8XJvwZFxEOB_1ygEvhEj_Zj2Y,2503
+pdflinkcheck/dev.py,sha256=e-0353spmVPPQGB2aJ_QbEDtJQGQFBSLrrfSccJGwII,4783
+pdflinkcheck/gui.py,sha256=TYjP0vCDtuyRYMi6-c2JdCgif4FWNKyrwdye13FTv_8,24434
+pdflinkcheck/io.py,sha256=ZdvKUumFIR8Ql89WToaVDqnosAo43H6sCRnbqwspE80,7943
+pdflinkcheck/report.py,sha256=MmUs2Cftm6sbT__uCzgU-v6lsSQ1IjzsvoM385Xxl8g,11777
+pdflinkcheck/stdlib_server.py,sha256=NKDPi-cfrBnYtG7mIxSI1eR1XSt8bxyan9YpdDAwhEU,6138
+pdflinkcheck/validate.py,sha256=AtROBUZ6EmXxsx0xmqcSTYSlaippnkymp8s5eN4qN3o,14391
+pdflinkcheck/version_info.py,sha256=dRVbs9U97YKisB1cLqVC2IoNrHCYw3z9TG8aldqTVOk,3211
+pdflinkcheck-1.1.72.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+pdflinkcheck-1.1.72.dist-info/WHEEL,sha256=ZyFSCYkV2BrxH6-HRVRg3R9Fo7MALzer9KiPYqNxSbo,79
+pdflinkcheck-1.1.72.dist-info/entry_points.txt,sha256=OJs4WkAziNGSoZ2KP0FgYOj2JdL6EW8UphJebWJnz3c,55
+pdflinkcheck-1.1.72.dist-info/METADATA,sha256=HORgjln1UF9Zdx3BwHfrKBR1OZSV7WwfDi2s6z8JNnM,13568
+pdflinkcheck-1.1.72.dist-info/RECORD,,

pdflinkcheck-1.1.72.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.18
+Root-Is-Purelib: true
+Tag: py3-none-any

{pdflinkcheck-1.1.7.dist-info → pdflinkcheck-1.1.72.dist-info}/entry_points.txt

@@ -1,3 +1,3 @@
 [console_scripts]
 pdflinkcheck = pdflinkcheck.cli:app
-pdflinkcheck-gui = pdflinkcheck.gui:start_gui
+