Make a start at new Pydantic config models

I intend to bring this in parallel to functioning previous code.

Author: dannyadair

.pre-commit-config.yaml

@@ -49,6 +49,8 @@ repos:
           - "cairosvg"
           - "click"
           - "jinja2"
+          - "pydantic"
           - "pypdf"
           - "pytest"
-          - "pyyaml"
+          - "pyyaml" # FIXME: remove once fully migrated to ruamel
+          - "ruamel.yaml"

examples/examples.yaml

@@ -4,3 +4,8 @@ documents:
   - variants
   - ./custom_locations/your_directory
   - custom_processing
+
+custom_stuff:
+  - year: 2025
+  - nested:
+      - anything: really

pyproject.toml

@@ -9,8 +9,10 @@ dependencies = [
     "cairosvg",
     "click",
     "jinja2",
+    "pydantic",
     "pypdf",
-    "pyyaml",
+    "pyyaml",   # FIXME: remove once fully migrated to ruamel
+    "ruamel.yaml",
 ]
 readme = "README.md"
 requires-python = ">= 3.11"

src/pdfbaker/__main__.py

@@ -7,7 +7,8 @@
 import click
 
 from pdfbaker import __version__
-from pdfbaker.baker import PDFBaker, PDFBakerOptions
+from pdfbaker.baker import PDFBaker
+from pdfbaker.config import BakerOptions
 from pdfbaker.errors import DocumentNotFoundError, PDFBakerError
 
 logger = logging.getLogger(__name__)
@@ -54,7 +55,7 @@ def bake(
         keep_build = True
 
     try:
-        options = PDFBakerOptions(
+        options = BakerOptions(
             quiet=quiet,
             verbose=verbose,
             trace=trace,

src/pdfbaker/baker.py

@@ -6,16 +6,15 @@
 bake() delegates to its documents and reports back the end result.
 """
 
-from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from .config import PDFBakerConfiguration, deep_merge
+from .config import BakerOptions, PDFBakerConfiguration, deep_merge
 from .document import PDFBakerDocument
 from .errors import ConfigurationError, DocumentNotFoundError
 from .logging import LoggingMixin, setup_logging
 
-__all__ = ["PDFBaker", "PDFBakerOptions"]
+__all__ = ["PDFBaker"]
 
 
 DEFAULT_BAKER_CONFIG = {
@@ -32,26 +31,6 @@
 }
 
 
-@dataclass
-class PDFBakerOptions:
-    """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
-    default_config_overrides: dict[str, Any] | None = None
-
-
 class PDFBaker(LoggingMixin):
     """Main class for PDF document generation."""
 
@@ -82,7 +61,7 @@ def __init__(
     def __init__(
         self,
         config_file: Path,
-        options: PDFBakerOptions | None = None,
+        options: BakerOptions | None = None,
     ) -> None:
         """Initialize PDFBaker with config file path. Set logging level.
 
@@ -91,7 +70,7 @@ def __init__(
             options: Optional options for logging and build behavior
         """
         super().__init__()
-        options = options or PDFBakerOptions()
+        options = options or BakerOptions()
         setup_logging(quiet=options.quiet, trace=options.trace, verbose=options.verbose)
         self.keep_build = options.keep_build
 

src/pdfbaker/config.py

@@ -2,21 +2,212 @@
 
 import logging
 import pprint
+from enum import Enum
 from pathlib import Path
 from typing import Any
 
 import yaml
 from jinja2 import Template
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    model_validator,
+)
+from ruamel.yaml import YAML
 
 from .errors import ConfigurationError
-from .logging import truncate_strings
+from .logging import LoggingMixin, truncate_strings
 from .types import PathSpec
 
 __all__ = ["PDFBakerConfiguration", "deep_merge", "render_config"]
 
 logger = logging.getLogger(__name__)
 
 
+# #####################################################################
+# New Pydantic models
+# #####################################################################
+
+# TODO: show names instead of index numbers for error locations
+#       https://docs.pydantic.dev/latest/errors/errors/#customize-error-messages
+
+
+class NewPathSpec(BaseModel):
+    """File/Directory location in YAML config."""
+
+    # Relative paths may not exist until resolved against root,
+    # so we have to check existence later
+    # path: FilePath | DirectoryPath
+    path: Path
+    name: str = Field(default_factory=lambda data: data["path"].stem)
+
+    @model_validator(mode="before")
+    @classmethod
+    def ensure_pathspec(cls, data: Any) -> Any:
+        """Coerce what was given"""
+        if isinstance(data, str):
+            data = {"name": data}
+        if isinstance(data, dict) and "path" not in data:
+            data["path"] = Path(data["name"])
+        return data
+
+
+class ImageSpec(NewPathSpec):
+    """Image specification."""
+
+    type: str | None = None
+    data: str | None = None
+
+
+class StyleDict(BaseModel):
+    """Style configuration."""
+
+    highlight_color: str | None = None
+
+
+class DirectoriesConfig(BaseModel):
+    """Directories configuration."""
+
+    root: NewPathSpec
+    build: NewPathSpec
+    dist: NewPathSpec
+    documents: NewPathSpec
+    pages: NewPathSpec
+    templates: NewPathSpec
+    images: NewPathSpec
+
+    @model_validator(mode="after")
+    def resolve_paths(self) -> Any:
+        """Resolve all paths relative to the root directory."""
+        self.root.path = self.root.path.resolve()
+        for field_name, value in self.__dict__.items():
+            if field_name != "root" and isinstance(value, NewPathSpec):
+                value.path = (self.root.path / value.path).resolve()
+        return self
+
+
+class PageConfig(BaseModel, LoggingMixin):
+    """Page configuration."""
+
+    directories: DirectoriesConfig
+    template: NewPathSpec
+    model_config = ConfigDict(
+        strict=True,  # don't try to coerce values
+        extra="allow",  # will go in __pydantic_extra__ dict
+    )
+
+
+class DocumentConfig(BaseModel, LoggingMixin):
+    """Document configuration.
+
+    Lazy-loads page configs.
+    """
+
+    directories: DirectoriesConfig
+    pages: list[Path | PageConfig]
+    model_config = ConfigDict(
+        strict=True,  # don't try to coerce values
+        extra="allow",  # will go in __pydantic_extra__ dict
+    )
+
+
+class DocumentVariantConfig(DocumentConfig):
+    """Document variant configuration."""
+
+
+class TemplateRenderer(Enum):
+    """Possible values for template_renderers."""
+
+    RENDER_HIGHLIGHT = "render_highlight"
+
+
+class TemplateFilter(Enum):
+    """Possible values for template_filters."""
+
+    WORDWRAP = "wordwrap"
+
+
+class SVG2PDFBackend(Enum):
+    """Possible values for svg2pdf_backend."""
+
+    CAIROSVG = "cairosvg"
+    INKSCAPE = "inkscape"
+
+
+class BakerConfig(BaseModel, LoggingMixin):
+    """Baker configuration.
+
+    Lazy-loads document configs.
+    """
+
+    directories: DirectoriesConfig
+    # TODO: lazy/forgiving documents parsing
+    # documents: list[Path | DocumentConfig]
+    documents: list[str]
+    template_renderers: list[TemplateRenderer] = [TemplateRenderer.RENDER_HIGHLIGHT]
+    template_filters: list[TemplateFilter] = [TemplateFilter.WORDWRAP]
+    svg2pdf_backend: SVG2PDFBackend | None = SVG2PDFBackend.CAIROSVG
+    compress_pdf: bool = False
+    model_config = ConfigDict(
+        strict=True,  # don't try to coerce values
+        extra="allow",  # will go in __pydantic_extra__ dict
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def load_config(cls, data: Any) -> Any:
+        """Load documents from YAML file."""
+        if isinstance(data, dict) and "config_file" in data:
+            config_file = data.pop("config_file")
+            config_data = YAML().load(config_file.read_text())
+            config_data.update(data)  # let kwargs override values from YAML
+            return config_data
+        return data
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_default_directories(cls, data: Any) -> Any:
+        """Set default directories."""
+        if isinstance(data, dict):
+            directories = data.setdefault("directories", {})
+            directories.setdefault("root", ".")
+            directories.setdefault("build", "build")
+            directories.setdefault("dist", "dist")
+            directories.setdefault("documents", ".")
+            directories.setdefault("pages", "pages")
+            directories.setdefault("templates", "templates")
+            directories.setdefault("images", "images")
+        return data
+
+    @property
+    def custom_config(self) -> dict[str, Any]:
+        """Dictionary of all custom user-defined configuration."""
+        return self.__pydantic_extra__
+
+
+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
+    default_config_overrides: dict[str, Any] | None = None
+
+
+# #####################################################################
+
+
 def deep_merge(base: dict[str, Any], update: dict[str, Any]) -> dict[str, Any]:
     """Deep merge two dictionaries."""
     result = base.copy()

src/test_config.py

@@ -0,0 +1,58 @@
+"""Test the new Pydantic config models."""
+
+import sys
+from pathlib import Path
+
+import ruamel.yaml
+from pydantic import ValidationError
+
+from pdfbaker import config
+
+CONFIG_FILE = Path("/home/danny/src/pdfbaker/examples/examples.yaml")
+
+
+def simple_representer(tag):
+    """Represent object as a string."""
+    return lambda representer, data: representer.represent_scalar(tag, str(data))
+
+
+def register_representers(yaml_instance, class_tag_map, use_multi_for=()):
+    """Register representer..
+
+    If a class is in use_multi_for, subclasses will also be covered.
+    (like PosixPath is a subclass of Path)
+    """
+    for cls, tag in class_tag_map.items():
+        func = simple_representer(tag)
+        if cls in use_multi_for:
+            # Add a representer for the class and all subclasses.
+            yaml_instance.representer.add_multi_representer(cls, func)
+        else:
+            # Add a representer for this exact class only.
+            yaml_instance.representer.add_representer(cls, func)
+
+
+yaml = ruamel.yaml.YAML()
+yaml.indent(offset=4)
+yaml.default_flow_style = False
+register_representers(
+    yaml,
+    {
+        Path: "!path",
+        config.SVG2PDFBackend: "!svg2pdf_backend",
+        config.TemplateRenderer: "!template_renderer",
+        config.TemplateFilter: "!template_filter",
+    },
+    use_multi_for=(Path,),
+)
+
+try:
+    baker_config = config.BakerConfig(config_file=CONFIG_FILE)
+    baker_config_dict = baker_config.model_dump()
+    print("*** Full config after parsing: ***")
+    yaml.dump(baker_config_dict, sys.stdout)
+    print()
+    print("*** Custom config values only: ***")
+    yaml.dump(baker_config.custom_config, sys.stdout)
+except ValidationError as e:
+    print(e)