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

pdflinkcheck/__init__.py

@@ -19,9 +19,7 @@ import os as _os
 # Library functions
 from pdflinkcheck.analyze_pymupdf import extract_links_pymupdf, extract_toc_pymupdf
 from pdflinkcheck.analyze_pypdf import extract_links_pypdf, extract_toc_pypdf
-#from pdflinkcheck import analyze_pypdf
-from pdflinkcheck.report import run_report
-from pdflinkcheck.report import run_report as run_analysis # for backwards compatibility with previos versions
+from pdflinkcheck.report import run_report_and_call_exports as run_report
 #from pdflinkcheck import dev
 
 # For the kids. This is what I wanted when learning Python in a mysterious new REPL.
@@ -48,13 +46,12 @@ else:
 # Define __all__ such that the library functions are self documenting.
 __all__ = [
     "run_report",
-    "run_analysis",
     "extract_links_pymupdf", 
     "extract_toc_pymupdf", 
     "extract_links_pypdf", 
     "extract_toc_pypdf", 
     #"start_gui" if _load_gui_func else None,
-    #"dev", 
+    "dev", 
 ]
 if _load_gui_func:
     __all__.append("start_gui")

pdflinkcheck/analyze_pymupdf.py

@@ -1,3 +1,7 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
+# pdflinkcheck/analyze_pymupdf.py
+
 import sys
 from pathlib import Path
 import logging
@@ -5,14 +9,15 @@ from typing import Dict, Any, Optional, List
 
 logging.getLogger("fitz").setLevel(logging.ERROR) 
 
+from pdflinkcheck.environment import pymupdf_is_available
 try:
-    import fitz  # PyMuPDF
+    if pymupdf_is_available():
+        import fitz  # PyMuPDF
+    else:
+        fitz = None
 except ImportError:
     fitz = None
 
-from pdflinkcheck.report import run_report
-#from pdflinkcheck.validate import run_validation
-
 """
 Inspect target PDF for both URI links and for GoTo links.
 """
@@ -331,8 +336,9 @@ def call_stable():
     Note: This requires defining PROJECT_NAME, CLI_MAIN_FILE, etc., or 
     passing them as arguments to run_report.
     """
-    run_report(pdf_library = "pymupdf")
-    #run_validation(pdf_library = "pymupdf")
+    from pdflinkcheck.report import run_report_and_call_exports
+    
+    run_report_and_call_exports(pdf_library = "pymupdf")
 
 if __name__ == "__main__":
     call_stable()

pdflinkcheck/analyze_pypdf.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
 # src/pdflinkcheck/analyze_pypdf.py
 import sys
 from pathlib import Path
@@ -9,8 +11,6 @@ from pypdf.generic import Destination, NameObject, ArrayObject, IndirectObject
 
 
 from pdflinkcheck.io import error_logger, export_report_data, get_first_pdf_in_cwd, LOG_FILE_PATH
-from pdflinkcheck.report import run_report
-#from pdflinkcheck.validate import run_validation
 
 """
 Inspect target PDF for both URI links and for GoTo links, using only pypdf, not Fitz
@@ -51,7 +51,23 @@ def get_anchor_text_pypdf(page, rect) -> str:
     
     return cleaned if cleaned else "Graphic/Empty Link"
 
-def resolve_pypdf_destination(reader: PdfReader, dest, obj_id_to_page: dict) -> str:
+def resolve_pypdf_destination(reader: PdfReader, dest, obj_id_to_page: dict) -> Optional[int]:
+    try:
+        if isinstance(dest, Destination):
+            return dest.page_number + 1  # Return int directly
+
+        if isinstance(dest, IndirectObject):
+            return obj_id_to_page.get(dest.idnum)
+
+        if isinstance(dest, ArrayObject) and len(dest) > 0:
+            if isinstance(dest[0], IndirectObject):
+                return obj_id_to_page.get(dest[0].idnum)
+
+        return None  # Unresolved → None
+    except Exception:
+        return None
+        
+def resolve_pypdf_destination_(reader: PdfReader, dest, obj_id_to_page: dict) -> str:
     """
     Resolves a Destination object or IndirectObject to a 1-based page number string.
     """
@@ -105,7 +121,7 @@ def extract_links_pypdf(pdf_path):
                 'type': 'Other Action',
                 'target': 'Unknown'
             }
-
+            
             # Handle URI (External)
             if "/A" in obj and "/URI" in obj["/A"]:
                 uri = obj["/A"]["/URI"]
@@ -114,11 +130,12 @@ def extract_links_pypdf(pdf_path):
                     'url': uri,
                     'target': uri
                 })
-
+            
             # Handle GoTo (Internal)
             elif "/Dest" in obj or ("/A" in obj and "/D" in obj["/A"]):
                 dest = obj.get("/Dest") or obj["/A"].get("/D")
                 target_page = resolve_pypdf_destination(reader, dest, obj_id_to_page)
+                # print(f"DEBUG: resolved target_page = {target_page} (type: {type(target_page)})")
                 link_dict.update({
                     'type': 'Internal (GoTo/Dest)',
                     'destination_page': target_page,
@@ -177,8 +194,9 @@ def call_stable():
     Note: This requires defining PROJECT_NAME, CLI_MAIN_FILE, etc., or 
     passing them as arguments to run_report.
     """
-    run_report(pdf_library = "pypdf")
-    #run_validation(pdf_library = "pypdf")
+    from pdflinkcheck.report import run_report_and_call_exports
+
+    run_report_and_call_exports(pdf_library = "pypdf")
 
 if __name__ == "__main__":
     call_stable()

pdflinkcheck/analyze_pypdf_v2.py

@@ -1,4 +1,6 @@
-# src/pdflinkcheck/analyze_pypdf.py
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
+# src/pdflinkcheck/analyze_pypdf_v2.py
 import sys
 from pathlib import Path
 import logging
@@ -7,9 +9,6 @@ from typing import Dict, Any, List
 from pypdf import PdfReader
 from pypdf.generic import Destination, NameObject, IndirectObject
 
-from pdflinkcheck.report import run_report
-#from pdflinkcheck.validate import run_validation
-
 """
 Inspect target PDF for both URI links and GoTo links, using only pypdf (no PyMuPDF/Fitz).
 Fully fixed and improved version as of December 2025 (compatible with pypdf >= 4.0).
@@ -209,9 +208,9 @@ def call_stable():
     """
     Entry point for command-line execution or integration with reporting module.
     """
-    run_report(library_pdf="pypdf")
-    # run_validation(library_pdf="pypdf")  # Uncomment if validation step is needed
+    from pdflinkcheck.report import run_report_and_call_exports
     
+    run_report_and_call_exports(pdf_library="pypdf")
 
 if __name__ == "__main__":
     call_stable()

pdflinkcheck/cli.py

@@ -1,10 +1,12 @@
+#!/usr/bin/env python3 
+# SPDX-License-Identifier: MIT
 # src/pdflinkcheck/cli.py
 import typer
 from typing import Literal
 from typer.models import OptionInfo
 from rich.console import Console
 from pathlib import Path
-from pdflinkcheck.report import run_report # Assuming core logic moves here
+from pdflinkcheck.report import run_report_and_call_exports # Assuming core logic moves here
 from typing import Dict, Optional, Union, List
 import pyhabitat
 import sys
@@ -13,7 +15,8 @@ from importlib.resources import files
 
 from pdflinkcheck.version_info import get_version_from_pyproject
 from pdflinkcheck.validate import run_validation 
-
+from pdflinkcheck.environment import is_in_git_repo, assess_default_pdf_library
+from pdflinkcheck.io import get_first_pdf_in_cwd
 
 console = Console() # to be above the tkinter check, in case of console.print
 
@@ -25,13 +28,19 @@ app = typer.Typer(
     no_args_is_help = False,
 )
 
-
 @app.callback()
-def main(ctx: typer.Context):
+def main(ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+    None, "--version", is_flag=True, help="Show the version."
+    )
+    ):
     """
     If no subcommand is provided, launch the GUI.
     """
-    
+    if version:
+        typer.echo(get_version_from_pyproject())
+        raise typer.Exit(code=0)
+        
     if ctx.invoked_subcommand is None:
         gui_command()
         raise typer.Exit(code=0)
@@ -54,10 +63,10 @@ if os.environ.get('DEV_TYPER_HELP_TREE',0) in ('true','1'):
 @app.command(name="docs", help="Show the docs for this software.")
 def docs_command(
     license: Optional[bool] = typer.Option(
-        None, "--license", "-l", help="Show the full AGPLv3 license text."
+        None, "--license", "-l", help="Show the LICENSE text."
     ),
     readme: Optional[bool] = typer.Option(
-        None, "--readme", "-r", help="Show the full README.md content."
+        None, "--readme", "-r", help="Show the README.md content."
     ),
 ):
     """
@@ -70,6 +79,11 @@ def docs_command(
         console.print("[yellow]Please use either the --license or --readme flag.[/yellow]")
         return # Typer will automatically show the help message.
 
+    if is_in_git_repo():
+        """This is too aggressive. But we don't expect it often. Probably worth it."""
+        from pdflinkcheck.datacopy import ensure_data_files_for_build
+        ensure_data_files_for_build()
+
     # --- Handle --license flag ---
     if license:
         try:
@@ -100,19 +114,50 @@ def docs_command(
     # Exit successfully if any flag was processed
     raise typer.Exit(code=0)
 
+@app.command(name="tools", help= "Additional features, hamburger menu.")
+def tools_command(
+    clear_cache: bool = typer.Option(
+        False,
+        "--clear-cache",
+        is_flag=True,
+        help="Clear the environment caches. \n - pymupdf_is_available() \n - is_in_git_repo() \nMain purpose: Run after adding PyMuPDF to an existing installation where it was previously missing, because pymupdf_is_available() would have been cached as False."
+    )
+    ):
+    from pdflinkcheck.environment import clear_all_caches
+    if clear_cache:
+        clear_all_caches()
+
+"""
+def validate_pdf_commands(
+    pdf_path: Optional[Path] = typer.Argument(
+        None,
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help="Path to the PDF file to validate. If omitted, searches current directory."
+    ),
+    pdf_library: Literal["pypdf", "pymupdf"] = typer.Option(
+        "pypdf",
+        "--library", "-l",
+        envvar="PDF_ENGINE",
+        help="PDF parsing engine: pypdf (pure Python) or pymupdf (faster, if available)"
+    ),
+    """
 @app.command(name="analyze") # Added a command name 'analyze' for clarity
 def analyze_pdf( # Renamed function for clarity
-    pdf_path: Path = typer.Argument(
-        ..., 
+    pdf_path: Optional[Path] = typer.Argument(
+        None, 
         exists=True, 
         file_okay=True, 
         dir_okay=False, 
         readable=True,
         resolve_path=True,
-        help="The path to the PDF file to analyze."
+        help="Path to the PDF file to analyze. If omitted, searches current directory."
     ), 
     export_format: Optional[Literal["JSON", "TXT", "JSON,TXT", "NONE"]] = typer.Option(
-        "JSON", 
+        "JSON,TXT", 
         "--export-format","-e",
         case_sensitive=False, 
         help="Export format. Use 'None' to suppress file export.",
@@ -125,10 +170,10 @@ def analyze_pdf( # Renamed function for clarity
     ),
 
     pdf_library: Literal["pypdf", "pymupdf"] = typer.Option(
-        "pypdf",#"pymupdf",
+        assess_default_pdf_library(),
         "--pdf-library","-p",
         envvar="PDF_ENGINE",
-        help="Select PDF parsing library, pymupdf or pypdf.",
+        help="PDF parsing library. pypdf (pure Python) or pymupdf (faster, if available).",
     )
 ):
     """
@@ -138,6 +183,11 @@ def analyze_pdf( # Renamed function for clarity
     • Internal GoTo links point to valid pages
     • Remote GoToR links point to existing files
     • TOC bookmarks target valid pages
+
+    Validates:
+    • Are referenced files available?
+    • Are the page numbers referenced by GoTo links within the length of the document?
+
     """
 
     """
@@ -149,110 +199,51 @@ def analyze_pdf( # Renamed function for clarity
 
     Env Var: If no flag is present, it checks PDF_ENGINE.
 
-    Code Default: (Lowest priority) It falls back to "pypdf" as defined in your typer.Option.
+    Code Default: (Lowest priority) It falls back to "pypdf" as defined in typer.Option.
     """
 
+    if pdf_path is None:
+        pdf_path = get_first_pdf_in_cwd()
+        if pdf_path is None:
+            console.print("[red]Error: No PDF file provided and none found in current directory.[/red]")
+            raise typer.Exit(code=1)
+        console.print(f"[dim]No file specified — using: {Path(pdf_path).name}[/dim]")
+
+    pdf_path_str = str(pdf_path)
+
     VALID_FORMATS = ("JSON") # extend later
     requested_formats = [fmt.strip().upper() for fmt in export_format.split(",")]
     if "NONE" in requested_formats or not export_format.strip() or export_format == "0":
         export_formats = ""
     else:
         # Filter for valid ones: ("JSON", "TXT")
-        # This allows "JSON,TXT" to become "JSONTXT" which your run_report logic can handle
+        # This allows "JSON,TXT" to become "JSONTXT" which run_report logic can handle
         valid = [f for f in requested_formats if f in ("JSON", "TXT")]
         export_formats = "".join(valid)
 
         if not valid and "NONE" not in requested_formats:
             typer.echo(f"Warning: No valid formats found in '{export_format}'. Supported: JSON, TXT.")
 
-    run_report(
+    # The meat and potatoes
+    report_results = run_report_and_call_exports(
         pdf_path=str(pdf_path), 
         max_links=max_links,
         export_format = export_formats,
         pdf_library = pdf_library,
     )
 
-@app.command(name="validate")
-def validate_pdf(
-    pdf_path: Optional[Path] = typer.Argument(
-        None,
-        exists=True,
-        file_okay=True,
-        dir_okay=False,
-        readable=True,
-        resolve_path=True,
-        help="Path to the PDF file to validate. If omitted, searches current directory."
-    ),
-    export: bool = typer.Option(
-        True,
-        "--export",#"--no-export",
-        help = "JSON export for validation check."
-    ),
-    pdf_library: Literal["pypdf", "pymupdf"] = typer.Option(
-        "pypdf",
-        "--library", "-l",
-        envvar="PDF_ENGINE",
-        help="PDF parsing engine: pypdf (pure Python) or pymupdf (faster, if available)"
-    ),
-    fail_on_broken: bool = typer.Option(
-        False,
-        "--fail",
-        help="Exit with code 1 if any broken links are found (useful for CI)"
-    )
-):
-    """
-    Validate internal, remote, and TOC links in a PDF.
-
-    1. Call the run_report() function, like calling the 'analyze' CLI command.
-    2. Inspects the results from 'run_report():
-        - Are referenced files available?
-        - Are the page numbers referenced by GoTo links within the length of the document?
-    """
-    from pdflinkcheck.io import get_first_pdf_in_cwd
-
-    if pdf_path is None:
-        pdf_path = get_first_pdf_in_cwd()
-        if pdf_path is None:
-            console.print("[red]Error: No PDF file provided and none found in current directory.[/red]")
-            raise typer.Exit(code=1)
-        console.print(f"[dim]No file specified — using: {pdf_path.name}[/dim]")
-
-    pdf_path_str = str(pdf_path)
-
-    console.print(f"[bold]Validating links in:[/bold] {pdf_path.name}")
-    console.print(f"[bold]Using engine:[/bold] {pdf_library}\n")
-
-    # Step 1: Run analysis (quietly)
-    report = run_report(
-        pdf_path=pdf_path_str,
-        max_links=0,
-        export_format="",
-        pdf_library=pdf_library,
-        print_bool=False
-    )
-
-    if not report or not report.get("data"):
+    if not report_results or not report_results.get("data"):
         console.print("[yellow]No links or TOC found — nothing to validate.[/yellow]")
         raise typer.Exit(code=0)
 
-    # Step 2: Run validation
-    validation_results = run_validation(
-        report_results=report,
-        pdf_path=pdf_path_str,
-        pdf_library=pdf_library,
-        export_json=export,
-        print_bool=True
-    )
-
+    validation_results = report_results["data"]["validation"]
     # Optional: fail on broken links
     broken_count = validation_results["summary-stats"]["broken-page"] + validation_results["summary-stats"]["broken-file"]
-    if fail_on_broken and broken_count > 0:
-        console.print(f"\n[bold red]Validation failed:[/bold red] {broken_count} broken link(s) found.")
-        raise typer.Exit(code=1)
-    elif broken_count > 0:
+    
+    if broken_count > 0:
         console.print(f"\n[bold yellow]Warning:[/bold yellow] {broken_count} broken link(s) found.")
     else:
-        console.print(f"\n[bold green]Success:[/bold green] No broken links or TOC issues!")
+        console.print(f"\n[bold green]Success:[/bold green] No broken links or TOC issues!\n")
 
     raise typer.Exit(code=0 if broken_count == 0 else 1)
 
@@ -260,7 +251,7 @@ def validate_pdf(
 def serve(
     host: str = typer.Option("0.0.0.0", "--host", "-h", help="Host to bind (use 0.0.0.0 for network access)"),
     port: int = typer.Option(8000, "--port", "-p", help="Port to listen on"),
-    reload: bool = typer.Option(False, "--reload", help="Auto-reload on code changes (dev only)"),
+    reload: bool = typer.Option(False, "--reload", is_flag=True, help="Auto-reload on code changes (dev only)"),
 ):
     """
     Start the built-in web server for uploading and analyzing PDFs in the browser.

pdflinkcheck/data/I Have Questions.md

@@ -0,0 +1,51 @@
+# I Have Questions.md
+
+## Subject matter: 
+How to create a graphical user interface.
+
+## Body: 
+When I was about 10 years old I dug through 'C:/Program Files/' repeatedly in a hope to discover how to make a pop-up window.
+What defined the edges of an interface? 
+Why do some windows look different than others?
+How can I add buttons? 
+
+I was excited. I wanted to make something.
+
+Could I mimick code from a software that was installed on my computer?
+I checked each folder in 'C:/Program Files/' looking for clues.
+
+As I searched, the questions changed.
+What is a DLL?
+Mostly, the only files I could open and inspect were little icons and fuzzy images - Why?
+
+I gave up.
+Wait - No I didn't. I am here now.
+
+Honestly, I still don't understand where the edges of the window come from.
+The easy answer is: **libraries**.
+Many people have done a lot of work to build various GUI libraries, to help people like me (and you) build software.
+
+For this package, the application window is built with Tkinter, which is included in Python's standard library.
+You can see how the graphical user interface (GUI) is defined at: https://raw.githubusercontent.com/City-of-Memphis-Wastewater/pdflinkcheck/main/src/pdflinkheck/gui.py
+
+This gui.py file isn't perfect, but exploring it will be far more illuminating than trying to open a DLL file in Notepad.
+
+This is not a recomendation to use Tkinter. I would recommend learning how to build a basic web-stack GUI which can be served locally. 
+
+You might not want to make classic interfaces. 
+It is what I grew up with, so I get a tickle when I participate in the tradition of local programs, but web and mobile are super valid.
+If you want to make classic interfaces, you should learn about Tauri.
+If you write core logic and then expose it in a way that’s friendly to the web, you can then use Tauri to wrap that web interface into something that feels native on your machine.
+This sounds wild, to go from native core to web tech back to native distribution, but it makes sense when you figure that: 
+- Web stack interfaces (HTML, CSS, TS/JS) offers the most control and best portability of graphics, with lots of people having built tools that you can leverage.
+- Making your code accessible via web requests and/or an API will help it have the widest possible reach.
+
+Personally, I get really excited when my Python code can run smoothly on Windows, iOS, Linux, and mostly importantly, as Linux on Android via Termux. Yes, sure, if Android is a target, the same core can be packaged as an Android app and be more accessible. Why do I want Termux? Because it's more about leveraging the machine. Basically, with code that can run on Termux, I can take any old android phone in a drawer and use it like I might use a Raspberry Pi. Tkinter will not run from Termux, not without proot. It is better to start a server on Termux, and then vew the app on localhost through your browser.
+
+Links:
+- https://docs.python.org/3/library/tkinter.html
+- https://v2.tauri.app/start/
+- https://pyo3.rs/main/doc/pyo3_ffi/index.html
+- https://bheisler.github.io/post/calling-rust-in-python/
+
+Copyright © 2025 George Clayton Bennett