pdflinkcheck 1.1.73__py3-none-any.whl → 1.2.29__py3-none-any.whl

pdflinkcheck/data/README.md

@@ -4,7 +4,7 @@ A purpose-built tool for comprehensive analysis of hyperlinks and GoTo links wit
 
 -----
 
-![Screenshot of the pdflinkcheck GUI](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_gui_v1.1.58.png)
+![Screenshot of the pdflinkcheck GUI](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_gui_v1.1.97.png)
 
 -----
 
@@ -19,7 +19,7 @@ For the most user-typical experience, download the single-file binary matching y
 | **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` |
+| **PYZ (Python Zip App)** | **CLI** or **GUI** | Run using your system's `python` command: `python pdflinkcheck-VERSION.pyz --help` | 
 
 ### Installation via pipx
 
@@ -42,20 +42,9 @@ 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`).
+Ways to launch the GUI interface:
+1.  **Implicit Launch:** Run the tool or file with no arguments, subcommands, or flags. (Note: PyInstaller builds use the --windowed (or -noconsole) flag, except for on Termux.)
 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.
 
 -----
 
@@ -63,20 +52,30 @@ We are actively working on the following enhancements:
 
 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)
+![Screenshot of the pdflinkcheck CLI Tree Help](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_cli_v1.1.97.png)
+
+
+See the Help Tree by unlocking the help-tree CLI command, using the DEV_TYPER_HELP_TREE env var.
+
+```
+DEV_TYPER_HELP_TREE=1 pdflinkcheck help-tree` # bash
+$env:DEV_TYPER_HELP_TREE = "1"; pdflinkcheck help-tree` # PowerShell
+```
+
+![Screenshot of the pdflinkcheck CLI Tree Help](https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/assets/pdflinkcheck_cli_v1.1.97_tree_help.png)
+
 
 
 ### Available Commands
 
 |**Command**|**Description**|
 |---|---|
-|`pdflinkcheck analyze`|Analyzes a PDF file for links |
+|`pdflinkcheck analyze`|Analyzes a PDF file for links and validates their reasonableness.|
 |`pdflinkcheck gui`|Explicitly launch the Graphical User Interface.|
 |`pdflinkcheck docs`|Access documentation, including the README and AGPLv3+ license.|
+|`pdflinkcheck serve`|Serve a basic local web app which uses only the Python standard library.|
+|`pdflinkcheck tools`|Access additional tools, like `--clear-cache`.|
 
 ### `analyze` Command Options
 
@@ -85,7 +84,6 @@ The core functionality is accessed via the `analyze` command.
 |`<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
 
@@ -99,9 +97,6 @@ The core functionality is accessed via the `analyze` command.
 # 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 
 
@@ -113,22 +108,23 @@ 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:
+For developers importing `pdflinkcheck` into other Python projects, the core analysis functions are exposed directly in the root namespace. The various `analysis_pdf_*` functions each use a different library to extract the target PDF's internal TOC, external links, and metadata.
 
-|**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.|
+|**Function**|**Library**|**Description**|
+|---|---|---|
+|`run_report()`|pdflinkcheck | **(Primary function)** Performs the full analysis, prints to console, and handles file export.|
+|`analyze_pdf_pdfium()`| pypdfium2 | Fast, ~10 mb, Permissively licensed |
+|`analyze_pdf_pymupdf()`| PyMuPDF | Fast, ~30 mb, AGPL3+ licensed |
+|`analyze_pdf_pypdf()`| pypdf library | Slow, ~2 mb, Permissively licensed |
 
 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
+from pdflinkcheck import ( run_report,
+                          analyze_pdf_pymupdf, 
+                          analyze_pdf_pypdf, 
+                          analyze_pdf_pdfium, 
+                          )
 
 file = "document1.pdf"
 report_data = run_report(file)
@@ -188,22 +184,34 @@ This `help-tree` feature has not yet been submitted for inclusion into Typer.
 
 ## ⚠️ Compatibility Notes
 
-#### Termux Compatibility as a Key Goal
+### 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. 
+Termux compatibility is important in the modern age, because 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 `pdflinkcheck` can run on Termux by using the `pypdf` engine and the `pdfium` engine. 
+Benefits:
+- `pypdf`-only artifacts, to reduce size to about 6% compared to artifacts that include `PyMuPDF`.
+- Web-stack GUI as an alternative to the Tkinter GUI, which can be run locally on Termux or as a web app.
+
 
-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.
+### PDF Library Selection
+At long last, `PyMuPDF` is an optional dependency. All testing comparing `pypdf` and `PyMuPDF` has shown identical validation performance. However `PyMuPDF` is much faster. The benfit of `pypdf` is small size of packages and cross-platform compatibility. We have recently added a PDFium option, which circumvents the AGPL3+.
 
-Because it works, we plan to keep the `PyMuPDF` portion of the codebase.
+Expecte that all binaries and artifacts contain PyMuPDF, unlss they are built 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[mupdf]"
+pipx install "pdflinkcheck[pdfium]"
+uv tool install "pdflinkcheck[pdfium]"
+uv add "pdflinkcheck[pdfium]"
+```
+
+---
 
 ### Document Compatibility: 
 Not all PDF files can be processed successfully. This tool is designed primarily for digitally generated (vector-based) PDFs.
@@ -215,22 +223,6 @@ Processing may fail or yield incomplete results for:
 
 -----
 
-## 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
@@ -257,22 +249,28 @@ 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`.
+The `AGPL3-or-later` is required for binaries of `pdflinkcheck` which include `PyMuPDF`, which is licensed under the `AGPL3`.
+The source code itself for `pdflinkcheck` is licensed under the `MIT`. 
 
-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:
+The AGPL3-or-later 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.**
 
+Because the AGPLv3 is a strong copyleft license, any version of `pdflinkcheck` that includes AGPL‑licensed components (such as `PyMuPDF`) must be distributed as a whole under AGPLv3+. This means that for those versions, anyone who distributes the application — or makes a modified version available over a network — must also provide the complete corresponding source code under the same terms.
+
+The source code of pdflinkcheck itself remains licensed under the **MIT License**; only the distributed binary becomes AGPL‑licensed when PyMuPDF is included.
+
+
 Links:
 - Source code: https://github.com/City-of-Memphis-Wastewater/pdflinkcheck/  
-- Official AGPLv3 Text (FSF): https://www.gnu.org/licenses/agpl-3.0.html
+- PyMuPDF source code: https://github.com/pymupdf/PyMuPDF/
+- pypdfium2 source code: https://github.com/pypdfium2-team/pypdfium2
+- pypdf source code: https://github.com/py-pdf/pypdf/
+- AGPLv3 text (FSF): https://www.gnu.org/licenses/agpl-3.0.html  
+- MIT License text: https://opensource.org/license/mit  
 
 Copyright © 2025 George Clayton Bennett

pdflinkcheck/data/pyproject.toml

@@ -1,25 +1,28 @@
 [project]
 name = "pdflinkcheck"
-version = "1.1.73"
+version = "1.2.29"
 description = "A purpose-built PDF link analysis and reporting tool with GUI and CLI."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 dependencies = [
-    "pyhabitat>=1.0.53",
+    "pyhabitat>=1.1.5",
     "pypdf>=6.4.2",
     "rich>=14.2.0",
     "typer>=0.20.0",
 ]
-license-files = ["LICENSE"]
+
+license = "MIT AND AGPL-3.0-or-later"
+license-files = ["LICENSE", "LICENSE-MIT", "LICENSE-AGPL3"]
+
 classifiers=[
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
     "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
@@ -50,49 +53,34 @@ 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",
-]
+# If you choose to include PyMuPDF, you must comply with the AGPL3
+mupdf = ["pymupdf>=1.24.0,<2.0.0"] # fails on termux
+pdfium = ["pypdfium2>=5.2.0,<6.0.0"]
+full = ["pymupdf>=1.24.0,<2.0.0", "pypdfium2>=5.2.0,<6.0.0"]
+
+#rust = [
+#    "pdflinkcheck-rust>=0.1.13"
+#]
 
 [dependency-groups]
 dev = [
     "build>=1.3.0",
-    "pyinstaller>=6.17.0",
+    "pyinstaller>=6.17.0 ; platform_system == 'Linux' and platform_machine != 'aarch64'", # to avoid on termux
     "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"
 [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",
-#]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
 
+[tool.uv.sources]
+pdflinkcheck = { path = "src/pdflinkcheck" }