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

pdflinkcheck/validate.py

@@ -1,29 +1,30 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
 # src/pdflinkcheck/validate.py
 
 import sys
 from pathlib import Path
 from typing import Dict, Any
 
-from pdflinkcheck.report import run_report
-from pdflinkcheck.io import get_friendly_path, export_validation_json
+from pdflinkcheck.io import get_friendly_path
+from pdflinkcheck.environment import pymupdf_is_available
+
+SEP_COUNT=28
 
 def run_validation(
     report_results: Dict[str, Any],
     pdf_path: str,
     pdf_library: str = "pypdf",
-    check_external: bool = False,
-    export_json: bool = True,
-    print_bool: bool = True
+    check_external: bool = False
 ) -> Dict[str, Any]:
     """
-    Validates links using the output from run_report().
+    Validates links during run_report() using a partial completion of the data dict.
 
     Args:
-        report_results: The dict returned by run_report()
+        report_results: The dict returned by run_report_and_call_exports()
         pdf_path: Path to the original PDF (needed for relative file checks and page count)
         pdf_library: Engine used ("pypdf" or "pymupdf")
         check_external: Whether to validate HTTP URLs (requires network + requests)
-        print_bool: Whether to print results to console
 
     Returns:
         Validation summary stats with valid/broken counts and detailed issues
@@ -35,13 +36,12 @@ def run_validation(
     toc = data.get("toc", [])
 
     if not all_links and not toc:
-        if print_bool:
-            print("No links or TOC to validate.")
+        print("No links or TOC to validate.")
         return {"summary-stats": {"valid": 0, "broken": 0}, "issues": []}
 
     # Get total page count (critical for internal validation)
     try:
-        if pdf_library == "pymupdf":
+        if pymupdf_is_available() and pdf_library == "pymupdf":
             import fitz
             doc = fitz.open(pdf_path)
             total_pages = doc.page_count
@@ -51,44 +51,54 @@ def run_validation(
             reader = PdfReader(pdf_path)
             total_pages = len(reader.pages)
     except Exception as e:
-        if print_bool:
-            print(f"Could not determine page count: {e}")
+        print(f"Could not determine page count: {e}")
         total_pages = None
 
     pdf_dir = Path(pdf_path).parent
 
     issues = []
     valid_count = 0
+    file_found_count = 0
     broken_file_count = 0
     broken_page_count = 0
-    file_found_count = 0
+    no_destination_page_count = 0
     unknown_web_count = 0
     unknown_reasonableness_count = 0
     unknown_link_count = 0
 
     # Validate active links
+    #print("DEBUG validate: entering loop with", len(all_links), "links")
     for i, link in enumerate(all_links):
         link_type = link.get("type")
         status = "valid"
         reason = None
         if link_type in ("Internal (GoTo/Dest)", "Internal (Resolved Action)"):
-            target_page = int(link.get("destination_page"))
-            if not isinstance(target_page, int):
-                status = "broken-page"
-                reason = f"Target page not a number: {target_page}"
-            elif (1 <= target_page) and total_pages is None:
-                status = "unknown-reasonableness"
-                reason = "Total page count unavailable, but the page number is reasonable"
-            elif (1 <= target_page <= total_pages):
-                status = "valid"
-                reason = f"Page {target_page} within range (1–{total_pages})"
-            elif target_page < 1:
-                status = "broken-page"
-                reason = f"TOC targets page negative {target_page}."
-            elif not (1 <= target_page <= total_pages):
-                status = "broken-page"
-                reason = f"Page {target_page} out of range (1–{total_pages})"
-            
+            dest_page_raw = link.get("destination_page")
+            if dest_page_raw is None:
+                status = "no-destinstion-page"
+                reason = "No destination page resolved"
+            else:
+                try:
+                    target_page = int(dest_page_raw)
+                    #target_page = int(link.get("destination_page"))
+                    if not isinstance(target_page, int):
+                        status = "broken-page"
+                        reason = f"Target page not a number: {target_page}"
+                    elif (1 <= target_page) and total_pages is None:
+                        status = "unknown-reasonableness"
+                        reason = "Total page count unavailable, but the page number is reasonable"
+                    elif (1 <= target_page <= total_pages):
+                        status = "valid"
+                        reason = f"Page {target_page} within range (1–{total_pages})"
+                    elif target_page < 1:
+                        status = "broken-page"
+                        reason = f"TOC targets page negative {target_page}."
+                    elif not (1 <= target_page <= total_pages):
+                        status = "broken-page"
+                        reason = f"Page {target_page} out of range (1–{total_pages})"
+                except (ValueError, TypeError):
+                    status = "broken-page"
+                    reason = f"Invalid page value: {dest_page_raw}"
         elif link_type == "Remote (GoToR)":
             remote_file = link.get("remote_file")
             if not remote_file:
@@ -130,13 +140,15 @@ def run_validation(
             unknown_reasonableness_count += 1
         elif status == "unknown-link":
             unknown_link_count += 1
-        elif status == "broken-file":
+        elif status == "broken-page":
             broken_page_count += 1
             issues.append(link_with_val)
         elif status == "broken-file":
-            broken_page_count += 1
+            broken_file_count += 1
+            issues.append(link_with_val)
+        elif status == "no-destinstion-page":
+            no_destination_page_count += 1
             issues.append(link_with_val)
-
     # Validate TOC entries
     for entry in toc:
         target_page = int(entry.get("target_page"))
@@ -154,7 +166,7 @@ def run_validation(
                 continue
             else:
                 status = "broken-page"
-                reason = f"TOC targets page {page} (out of 1–{total_pages})"
+                reason = f"TOC targets page {target_page} (out of 1–{total_pages})"
                 broken_count += 1
         else:
             status = "broken-page"
@@ -175,6 +187,7 @@ def run_validation(
         "file-found": file_found_count,
         "broken-page": broken_page_count,
         "broken-file": broken_file_count,
+        "no_destination_page_count": no_destination_page_count,
         "unknown-web": unknown_web_count,
         "unknown-reasonableness": unknown_reasonableness_count,
         "unknown-link": unknown_link_count,
@@ -192,23 +205,23 @@ def run_validation(
         def log(msg: str):
             validation_buffer.append(msg)
     
-        log("\n" + "=" * 70)
+        log("\n" + "=" * SEP_COUNT)
         log("## Validation Results")
-        log("=" * 70)
+        log("=" * SEP_COUNT)
         log(f"PDF Path = {get_friendly_path(pdf_path)}")
         log(f"Total items checked: {summary_stats['total_checked']}")
         log(f"✅ Valid: {summary_stats['valid']}")
         log(f"🌐 Web Addresses (Not Checked): {summary_stats['unknown-web']}")
         log(f"⚠️ Unknown Page Reasonableness (Due to Missing Total Page Count): {summary_stats['unknown-reasonableness']}")
         log(f"⚠️ Unsupported PDF Links: {summary_stats['unknown-link']}")
-        log(f"❌ Broken Page Reference: {summary_stats['broken-page']}")
-        log(f"❌ Broken File Reference: {summary_stats['broken-file']}")
-        log("=" * 70)
+        log(f"❌ Broken Page Reference (Page number beyond scope of availability): {summary_stats['broken-page']}")
+        log(f"❌ Broken File Reference (File not available): {summary_stats['broken-file']}")
+        log("=" * SEP_COUNT)
 
         if issues:
             log("\n## Issues Found")
             log("{:<5} | {:<12} | {:<30} | {}".format("Idx", "Type", "Text", "Problem"))
-            log("-" * 70)
+            log("-" * SEP_COUNT)
             for i, issue in enumerate(issues[:25], 1):
                 link_type = issue.get("type", "Link")
                 text = issue.get("link_text", "") or issue.get("title", "") or "N/A"
@@ -218,7 +231,7 @@ def run_validation(
             if len(issues) > 25:
                 log(f"... and {len(issues) - 25} more issues")
         else:
-            log("No issues found — all links and TOC entries are valid!")
+            log("Success: No broken links or TOC issues!")
 
         # Final aggregation of the buffer into one string
         validation_buffer_str = "\n".join(validation_buffer)
@@ -226,8 +239,6 @@ def run_validation(
         return validation_buffer_str
     
     summary_txt = generate_validation_summary_txt_buffer(summary_stats, issues, pdf_path)
-    if print_bool:
-        print(summary_txt)
 
     validation_results = {
         "pdf_path" : pdf_path,
@@ -237,9 +248,6 @@ def run_validation(
         "total_pages": total_pages
     }
 
-    # Have export run interally so that the logic need not happen in an interface
-
-    export_validation_json(validation_results,  pdf_path, pdf_library)
     return validation_results
 
 
@@ -254,7 +262,7 @@ def run_validation_more_readable_slop(pdf_path: str = None, pdf_library: str = "
     if check_external_links:
         import requests
 
-    # 1. Setup Library Engine (Reuse your logic)
+    # 1. Setup Library Engine (Reuse logic)
     pdf_library = pdf_library.lower()
     if pdf_library == "pypdf":
         from pdflinkcheck.analyze_pypdf import extract_links_pypdf as extract_links
@@ -330,18 +338,18 @@ def run_validation_more_readable_slop(pdf_path: str = None, pdf_library: str = "
         else:
             results['broken'].append(link)
 
-    print("\n" + "=" * 70)
+    print("\n" + "=" * SEP_COUNT)
     print(f"--- Validation Summary Stats for {Path(pdf_path).name} ---")
     print(f"Total Checked: {total_links}")
     print(f"✅ Valid:  {len(results['valid'])}")
     print(f"❌ Broken: {len(results['broken'])}")
-    print("=" * 70)
+    print("=" * SEP_COUNT)
 
     # 4. Print Detail Report for Broken Links
     if results['broken']:
         print("\n## ❌ Broken Links Found:")
         print("{:<5} | {:<5} | {:<30} | {}".format("Idx", "Page", "Reason", "Target"))
-        print("-" * 70)
+        print("-" * SEP_COUNT)
         for i, link in enumerate(results['broken'], 1):
             target = link.get('url') or link.get('destination_page') or link.get('remote_file')
             print("{:<5} | {:<5} | {:<30} | {}".format(
@@ -349,32 +357,3 @@ def run_validation_more_readable_slop(pdf_path: str = None, pdf_library: str = "
             ))
     
     return results
-
-
-if __name__ == "__main__":
-
-    from pdflinkcheck.io import get_first_pdf_in_cwd
-    pdf_path = get_first_pdf_in_cwd()
-    # Run analysis first
-    report = run_report(
-        pdf_path=pdf_path,
-        max_links=0,
-        export_format="",
-        pdf_library="pypdf",
-        print_bool=False  # We handle printing in validation
-    )
-
-    if not report or not report.get("data"):
-        print("No data extracted — nothing to validate.")
-        sys.exit(1)
-
-    # Then validate
-    validation_results = run_validation(
-        report_results=report,
-        pdf_path=pdf_path,
-        pdf_library="pypdf",
-        export_json=True,
-        print_bool=True
-    )
-
-    export_validation_results()

pdflinkcheck/version_info.py

@@ -1,4 +1,7 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
 # src/pdflinkcheck/version_info.py
+
 import re
 from pathlib import Path
 import sys
@@ -11,7 +14,7 @@ This portion of the codebase is MIT licensed. It does not rely on any AGPL-licen
 
 MIT License
 
-Copyright (c) 2025 George Clayton Bennett <george.bennett@memphistn.gov>
+Copyright © 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
@@ -52,7 +55,7 @@ def find_pyproject(start: Path) -> Path | None:
         if candidate.exists():
             return candidate
         
-    # 3. Handle Installed / Wheel / Shiv state (using your force-include path)
+    # 3. Handle Installed / Wheel / Shiv state (using force-include path)
     internal_path = Path(__file__).parent / "data" / "pyproject.toml"
     if internal_path.exists():
         return internal_path

{pdflinkcheck-1.1.72.dist-info → pdflinkcheck-1.1.94.dist-info}/METADATA

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: pdflinkcheck
-Version: 1.1.72
+Version: 1.1.94
 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-Expression: MIT AND AGPL-3.0-or-later
 License-File: LICENSE
+License-File: LICENSE-AGPL3
+License-File: LICENSE-MIT
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
@@ -13,6 +16,7 @@ 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: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Intended Audience :: Developers
@@ -32,14 +36,12 @@ 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
@@ -48,7 +50,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.92.png)
 
 -----
 
@@ -86,20 +88,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.
 
 -----
 
@@ -107,20 +98,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.92.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.92_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
 
@@ -232,37 +233,23 @@ 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 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.
+Now `pdflinkcheck` can run on Termux by using the `pypdf` 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.
 
------
 
-## 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. 
+### PDF Library Selection
+At long last, `PyMuPDF` is an optional dependency. All testing comparing `pyp df` 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.
 
-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.
+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:
 
@@ -273,6 +260,16 @@ uv tool install "pdflinkcheck[full]"
 uv add "pdflinkcheck[full]"
 ```
 
+---
+
+### 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.
+
 -----
 
 ## Run from Source (Developers)
@@ -301,22 +298,27 @@ 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/
+- 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