WIP Complete refactoring to pydantic models

Still cleaning up but it's definitely a much better approach.
Less code (and will shrink more).
Improved logging with YAML (not Python dict pprint) and emojis.

* Examples all render fine
* Variants broken if pages not defined in document just variants
* Need to fix all tests for new class structures
* Review all TODO/FIXME before merging (esp. for variants, clumsy/messy)
* Tidy up, check __all__, try/except, customize pydantic error messages

Author: dannyadair

.pre-commit-config.yaml

@@ -52,5 +52,4 @@ repos:
           - "pydantic"
           - "pypdf"
           - "pytest"
-          - "pyyaml" # FIXME: remove once fully migrated to ruamel
           - "ruamel.yaml"

examples/custom_locations/other_pages/custom_page.yaml

@@ -1,8 +1,6 @@
 title: "Custom Location Example"
 description: "This page uses custom directory structure"
 template:
-  # If you just wrote this directly it would be relative to the templates directory
-  # We want it to be relative to the config file, so use path:
   path: "../other_templates/custom_page.svg.j2"
 detailed_description:
   "This example demonstrates custom file locations in pdfbaker. The template file is in

examples/custom_processing/bake.py

@@ -5,12 +5,12 @@
 import urllib.request
 from datetime import datetime
 
-from pdfbaker.document import PDFBakerDocument
+from pdfbaker.document import Document
 from pdfbaker.errors import PDFBakerError
 from pdfbaker.processing import wordwrap
 
 
-def process_document(document: PDFBakerDocument) -> None:
+def process_document(document: Document) -> None:
     """Process document with live XKCD comic."""
     try:
         # Fetch latest XKCD
@@ -29,7 +29,7 @@ def process_document(document: PDFBakerDocument) -> None:
         wrapped_alt_text = wordwrap(data["alt"], max_chars=60)
 
         # Update config/template context with XKCD info
-        document.config["xkcd"] = {
+        document.config.xkcd = {
             "title": data["title"],
             "alt_text": data["alt"],
             "alt_text_lines": wrapped_alt_text,

examples/examples.yaml

@@ -2,7 +2,8 @@ documents:
   - minimal
   - regular
   - variants
-  - ./custom_locations/your_directory
+  - path: ./custom_locations/your_directory
+    name: custom_locations
   - custom_processing
 
 custom_stuff:

pyproject.toml

@@ -11,7 +11,6 @@ dependencies = [
     "jinja2",
     "pydantic",
     "pypdf",
-    "pyyaml",   # FIXME: remove once fully migrated to ruamel
     "ruamel.yaml",
 ]
 readme = "README.md"

src/pdfbaker/__main__.py

@@ -7,8 +7,7 @@
 import click
 
 from pdfbaker import __version__
-from pdfbaker.baker import PDFBaker
-from pdfbaker.config import BakerOptions
+from pdfbaker.baker import Baker, BakerOptions
 from pdfbaker.errors import DocumentNotFoundError, PDFBakerError
 
 logger = logging.getLogger(__name__)
@@ -61,14 +60,14 @@ def bake(
             trace=trace,
             keep_build=keep_build,
         )
-        baker = PDFBaker(config_file, options=options)
+        baker = Baker(config_file, options=options)
         success = baker.bake(document_names=documents if documents else None)
         sys.exit(0 if success else 1)
     except DocumentNotFoundError as exc:
-        logger.error(str(exc))
+        logger.error("❌ %s", str(exc))
         sys.exit(2)
     except PDFBakerError as exc:
-        logger.error(str(exc))
+        logger.error("❌ %s", str(exc))
         sys.exit(1)
 
 

src/pdfbaker/baker.py

@@ -1,4 +1,4 @@
-"""PDFBaker class.
+"""Baker class.
 
 Overall orchestration and logging.
 
@@ -7,87 +7,61 @@
 """
 
 from pathlib import Path
-from typing import Any
 
-from .config import BakerOptions, PDFBakerConfiguration, deep_merge
-from .document import PDFBakerDocument
-from .errors import ConfigurationError, DocumentNotFoundError
+from pydantic import BaseModel, ValidationError
+
+from .config import (
+    BakerConfig,
+    PathSpec,
+)
+from .document import Document
+from .errors import DocumentNotFoundError
 from .logging import LoggingMixin, setup_logging
 
-__all__ = ["PDFBaker"]
-
-
-DEFAULT_BAKER_CONFIG = {
-    # Default to directories relative to the config file
-    "directories": {
-        "documents": ".",
-        "build": "build",
-        "dist": "dist",
-    },
-    # Highlighting support enabled by default
-    "template_renderers": ["render_highlight"],
-    # Make all filters available by default
-    "template_filters": ["wordwrap"],
-}
-
-
-class PDFBaker(LoggingMixin):
-    """Main class for PDF document generation."""
-
-    class Configuration(PDFBakerConfiguration):
-        """PDFBaker configuration."""
-
-        def __init__(
-            self, baker: "PDFBaker", base_config: dict[str, Any], config_file: Path
-        ) -> None:
-            """Initialize baker configuration (needs documents)."""
-            self.baker = baker
-            self.name = config_file.name
-            self.baker.log_debug_section("Loading main configuration: %s", config_file)
-            super().__init__(base_config, config_file)
-            self.baker.log_trace(self.pretty())
-            if "documents" not in self:
-                raise ConfigurationError(
-                    'Key "documents" missing - is this the main configuration file?'
-                )
-            self.build_dir = self["directories"]["build"]
-            self.documents = []
-            for doc_spec in self["documents"]:
-                doc_path = self.resolve_path(
-                    doc_spec, directory=self["directories"]["documents"]
-                )
-                self.documents.append({"name": doc_path.name, "path": doc_path})
+__all__ = ["Baker", "BakerOptions"]
+
+
+class BakerOptions(BaseModel):
+    """Options for controlling PDFBaker behavior.
+
+    Attributes:
+        quiet: Show errors only
+        verbose: Show debug information
+        trace: Show trace information (even more detailed than debug)
+        keep_build: Keep build artifacts after processing
+        default_config_overrides: Dictionary of values to override the built-in defaults
+            before loading the main configuration
+    """
+
+    quiet: bool = False
+    verbose: bool = False
+    trace: bool = False
+    keep_build: bool = False
+
+
+class Baker(LoggingMixin):
+    """Baker class."""
 
     def __init__(
         self,
         config_file: Path,
         options: BakerOptions | None = None,
+        **kwargs,
     ) -> None:
-        """Initialize PDFBaker with config file path. Set logging level.
-
-        Args:
-            config_file: Path to config file
-            options: Optional options for logging and build behavior
-        """
-        super().__init__()
+        """Set up logging and load configuration."""
         options = options or BakerOptions()
         setup_logging(quiet=options.quiet, trace=options.trace, verbose=options.verbose)
-        self.keep_build = options.keep_build
-
-        base_config = DEFAULT_BAKER_CONFIG.copy()
-        if options and options.default_config_overrides:
-            base_config = deep_merge(base_config, options.default_config_overrides)
-        base_config["directories"]["config"] = config_file.parent.resolve()
-
-        self.config = self.Configuration(
-            baker=self,
-            base_config=base_config,
+        self.log_debug_section("Loading main configuration: %s", config_file)
+        self.config = BakerConfig(
             config_file=config_file,
+            keep_build=options and options.keep_build or False,
+            **kwargs,
         )
+        self.log_trace(self.config.readable())
 
     def _get_documents_to_process(
         self, selected_document_names: tuple[str, ...] | None = None
-    ) -> list[Path]:
+    ) -> list[PathSpec]:
         """Get the document paths to process based on optional filtering.
 
         Args:
@@ -99,61 +73,57 @@ def _get_documents_to_process(
         if not selected_document_names:
             return self.config.documents
 
-        available_doc_names = [doc["name"] for doc in self.config.documents]
+        available_doc_names = [doc.name for doc in self.config.documents]
         missing_docs = [
             name for name in selected_document_names if name not in available_doc_names
         ]
         if missing_docs:
             available_str = ", ".join([f'"{name}"' for name in available_doc_names])
-            self.log_info(f"Documents in {self.config.name}: {available_str}")
+            self.log_info(
+                f"Documents in {self.config.config_file.name}: {available_str}"
+            )
             missing_str = ", ".join([f'"{name}"' for name in missing_docs])
             raise DocumentNotFoundError(
                 f"Document{'s' if len(missing_docs) != 1 else ''} not found "
                 f"in configuration: {missing_str}."
             )
 
         return [
-            doc
-            for doc in self.config.documents
-            if doc["name"] in selected_document_names
+            doc for doc in self.config.documents if doc.name in selected_document_names
         ]
 
-    def bake(self, document_names: tuple[str, ...] | None = None) -> bool:
-        """Create PDFs for all documents or only the specified ones.
-
-        Args:
-            document_names: Optional tuple of document names to process
-
-        Returns:
-        bool: True if all documents were processed successfully, False if any failed
-        """
+    def bake(self, document_names: tuple[str, ...] | None = None) -> None:
+        """Bake the documents."""
         pdfs_created: list[Path] = []
-        failed_docs: list[tuple[str, str]] = []
+        failed_docs: list[tuple[PathSpec, str]] = []
 
-        documents = self._get_documents_to_process(document_names)
+        doc_configs = self._get_documents_to_process(document_names)
 
         self.log_debug_subsection("Documents to process:")
-        self.log_debug(documents)
-        for doc_config in documents:
-            doc = PDFBakerDocument(
-                baker=self,
-                base_config=self.config,
-                config_path=doc_config["path"],
-            )
-            pdf_files, error_message = doc.process_document()
+        self.log_debug(doc_configs)
+        for doc_config in doc_configs:
+            try:
+                document = Document(
+                    config_path=doc_config, **self.config.document_settings
+                )
+            except ValidationError as e:
+                self.log_error(f'Invalid config for document "{doc_config.name}": {e}')
+                continue
+
+            pdf_files, error_message = document.process_document()
             if error_message:
                 self.log_error(
                     "Failed to process document '%s': %s",
-                    doc.config.name,
+                    document.config.name,
                     error_message,
                 )
-                failed_docs.append((doc.config.name, error_message))
+                failed_docs.append((document, error_message))
             else:
                 if isinstance(pdf_files, Path):
                     pdf_files = [pdf_files]
                 pdfs_created.extend(pdf_files)
-            if not self.keep_build:
-                doc.teardown()
+            if not self.config.keep_build:
+                document.teardown()
 
         if pdfs_created:
             self.log_info("Successfully created PDFs:")
@@ -171,19 +141,20 @@ def bake(self, document_names: tuple[str, ...] | None = None) -> bool:
             for doc_name, error in failed_docs:
                 self.log_error("  %s: %s", doc_name, error)
 
-        if not self.keep_build:
+        if not self.config.keep_build:
             self.teardown()
 
         return not failed_docs
 
     def teardown(self) -> None:
         """Clean up (top-level) build directory after processing."""
+        build_dir = self.config.directories.build
         self.log_debug_subsection(
-            "Tearing down top-level build directory: %s", self.config.build_dir
+            "Tearing down top-level build directory: %s", build_dir
         )
-        if self.config.build_dir.exists():
+        if build_dir.exists():
             try:
                 self.log_debug("Removing top-level build directory...")
-                self.config.build_dir.rmdir()
+                build_dir.rmdir()
             except OSError:
                 self.log_warning("Top-level build directory not empty - not removing")