Add typehints

Author: dannyadair

src/pdfbaker/__init__.py

@@ -1,38 +1,39 @@
-"""Core functionality for document generation."""
+"""PDF document generator."""
 
 import logging
 
 from .common import (
+    # Exceptions
     PDFBakeError,
     PDFCombineError,
     PDFCompressionError,
     SVGConversionError,
+    # Functions
     combine_pdfs,
     compress_pdf,
     convert_svg_to_pdf,
     deep_merge,
     load_pages,
 )
-from .render import (
-    create_env,
-    process_template_data,
-)
+from .render import create_env, process_template_data
 
 logger = logging.getLogger(__name__)
 
 __all__ = [
+    # Logger
     "logger",
-    # common
+    # Exceptions
     "PDFBakeError",
     "PDFCombineError",
     "PDFCompressionError",
     "SVGConversionError",
+    # Common functions
     "combine_pdfs",
     "compress_pdf",
     "convert_svg_to_pdf",
     "deep_merge",
     "load_pages",
-    # render
+    # Render functions
     "create_env",
     "process_template_data",
 ]

src/pdfbaker/__main__.py

@@ -5,6 +5,7 @@
 import os
 import sys
 from pathlib import Path
+from typing import Any
 
 import click
 import yaml
@@ -17,7 +18,7 @@
 
 
 @click.group()
-def cli():
+def cli() -> None:
     """Generate PDF documents from YAML-configured SVG templates."""
 
 
@@ -33,7 +34,9 @@ def cli():
     is_flag=True,
     help="Debug mode (implies --verbose, keeps build files)",
 )
-def bake(config_file, verbose=False, quiet=False, debug=False):
+def bake(
+    config_file: Path, verbose: bool = False, quiet: bool = False, debug: bool = False
+) -> int:
     """Parse config file and bake PDFs."""
     if debug:
         verbose = True
@@ -59,13 +62,13 @@ def bake(config_file, verbose=False, quiet=False, debug=False):
     return 0
 
 
-def _load_config(config_file):
+def _load_config(config_file: Path) -> dict[str, Any]:
     """Load configuration from a YAML file."""
     with open(config_file, encoding="utf-8") as f:
         return yaml.safe_load(f)
 
 
-def _setup_output_directories(base_dir):
+def _setup_output_directories(base_dir: Path) -> tuple[Path, Path]:
     """Create and return build and dist directories."""
     build_dir = base_dir / "build"
     dist_dir = base_dir / "dist"
@@ -74,9 +77,11 @@ def _setup_output_directories(base_dir):
     return build_dir, dist_dir
 
 
-def _get_document_paths(base_dir, documents):
+def _get_document_paths(
+    base_dir: Path, documents: list[dict[str, str] | str]
+) -> dict[str, Path]:
     """Resolve document paths to absolute paths."""
-    document_paths = {}
+    document_paths: dict[str, Path] = {}
 
     for doc_name in documents:
         if isinstance(doc_name, dict):
@@ -92,7 +97,7 @@ def _get_document_paths(base_dir, documents):
     return document_paths
 
 
-def _validate_document_path(doc_name, doc_path):
+def _validate_document_path(doc_name: str, doc_path: Path) -> tuple[Path, Path] | bool:
     """Validate that a document has all required files."""
     if not doc_path.is_dir():
         logger.warning('Directory missing for document "%s" at %s', doc_name, doc_path)
@@ -111,7 +116,13 @@ def _validate_document_path(doc_name, doc_path):
     return bake_path, config_yml_path
 
 
-def _process_document(doc_name, doc_path, config, build_dir, dist_dir):
+def _process_document(
+    doc_name: str,
+    doc_path: Path,
+    config: dict[str, Any],
+    build_dir: Path,
+    dist_dir: Path,
+) -> None:
     """Process an individual document."""
     validation_result = _validate_document_path(doc_name, doc_path)
     if not validation_result:
@@ -143,7 +154,7 @@ def _process_document(doc_name, doc_path, config, build_dir, dist_dir):
     )
 
 
-def _load_document_bake_module(doc_name, bake_path):
+def _load_document_bake_module(doc_name: str, bake_path: Path) -> Any:
     """Load the document's bake.py module."""
     doc_bake = importlib.util.spec_from_file_location(
         f"documents.{doc_name}.bake", bake_path
@@ -153,7 +164,9 @@ def _load_document_bake_module(doc_name, bake_path):
     return module
 
 
-def _setup_document_output_directories(build_dir, dist_dir, doc_name):
+def _setup_document_output_directories(
+    build_dir: Path, dist_dir: Path, doc_name: str
+) -> tuple[Path, Path]:
     """Set up and clean document-specific build and dist directories."""
     doc_build_dir = build_dir / doc_name
     doc_dist_dir = dist_dir / doc_name
@@ -169,7 +182,7 @@ def _setup_document_output_directories(build_dir, dist_dir, doc_name):
     return doc_build_dir, doc_dist_dir
 
 
-def _teardown_build_directories(build_dir, doc_names):
+def _teardown_build_directories(build_dir: Path, doc_names: list[str]) -> None:
     """Clean up build directories after successful processing.
 
     Args:

src/pdfbaker/common.py

@@ -4,11 +4,16 @@
 import os
 import select
 import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
 
 import pypdf
 import yaml
 from cairosvg import svg2pdf
 
+from .types import PageConfig
+
 logger = logging.getLogger(__name__)
 
 
@@ -19,7 +24,9 @@ class PDFBakeError(Exception):
 class SVGConversionError(PDFBakeError):
     """Failed to convert SVG to PDF."""
 
-    def __init__(self, svg_path, backend, cause=None):
+    def __init__(
+        self, svg_path: str | Path, backend: str, cause: str | None = None
+    ) -> None:
         self.svg_path = svg_path
         self.backend = backend
         self.cause = cause
@@ -34,7 +41,7 @@ class PDFCompressionError(PDFBakeError):
     """Failed to compress PDF."""
 
 
-def deep_merge(base, update):
+def deep_merge(base: dict[str, Any], update: dict[str, Any]) -> dict[str, Any]:
     """Recursively merge two dictionaries.
 
     Values in update will override those in base, except for dictionaries
@@ -49,22 +56,24 @@ def deep_merge(base, update):
     return merged
 
 
-def load_pages(pages_dir):
+def load_pages(pages_dir: Path) -> dict[str, dict[str, Any]]:
     """Load page configurations from a specific subdirectory."""
-    pages = {}
+    pages: dict[str, dict[str, Any]] = {}
 
     if pages_dir.exists():
         for page in pages_dir.iterdir():
             if not page.name.endswith(".yml"):
                 continue
             with open(page, encoding="utf-8") as f:
-                yaml_config = yaml.safe_load(f)
+                yaml_config: PageConfig = yaml.safe_load(f)
                 pages[yaml_config["name"]] = yaml_config["config"]
 
     return pages
 
 
-def combine_pdfs(pdf_files, output_file):
+def combine_pdfs(
+    pdf_files: Sequence[Path], output_file: Path
+) -> Path | PDFCombineError:
     """Combine multiple PDF files into a single PDF.
 
     Args:
@@ -108,7 +117,7 @@ def combine_pdfs(pdf_files, output_file):
     return output_file
 
 
-def _run_subprocess_logged(cmd, env=None):
+def _run_subprocess_logged(cmd: list[str], env: dict[str, str] | None = None) -> int:
     """Run a subprocess with output redirected to logging.
 
     Args:
@@ -157,7 +166,9 @@ def _run_subprocess_logged(cmd, env=None):
     return 0
 
 
-def compress_pdf(input_pdf, output_pdf, dpi=300):
+def compress_pdf(
+    input_pdf: Path, output_pdf: Path, dpi: int = 300
+) -> Path | PDFCompressionError:
     """Compress a PDF file using Ghostscript.
 
     Args:
@@ -183,15 +194,19 @@ def compress_pdf(input_pdf, output_pdf, dpi=300):
                 "-dQUIET",
                 "-dBATCH",
                 f"-sOutputFile={output_pdf}",
-                input_pdf,
+                str(input_pdf),
             ]
         )
         return output_pdf
     except subprocess.SubprocessError as exc:
         raise PDFCompressionError(f"Ghostscript compression failed: {exc}") from exc
 
 
-def convert_svg_to_pdf(svg_path, pdf_path, backend="cairosvg"):
+def convert_svg_to_pdf(
+    svg_path: Path,
+    pdf_path: Path,
+    backend: str = "cairosvg",
+) -> Path | SVGConversionError:
     """Convert an SVG file to PDF.
 
     Args:
@@ -213,7 +228,7 @@ def convert_svg_to_pdf(svg_path, pdf_path, backend="cairosvg"):
                     [
                         "inkscape",
                         f"--export-filename={pdf_path}",
-                        svg_path,
+                        str(svg_path),
                     ]
                 )
             except subprocess.SubprocessError as exc: