feat: Improve logging and console UI with rich formatting

* Use rich and rich-click - colors, panels etc.
* Proper syntax highlighting for SVG and YAML
* Show directory tree after --create-from
* Don't repeat identical subprocess log messages, count them

Author: dannyadair

.pre-commit-config.yaml

@@ -46,9 +46,9 @@ repos:
       - id: pylint
         additional_dependencies:
           - "cairosvg"
-          - "click"
           - "jinja2"
           - "pydantic"
           - "pypdf"
           - "pytest"
+          - "rich_click"
           - "ruamel.yaml"

pyproject.toml

@@ -7,7 +7,7 @@ authors = [
 ]
 dependencies = [
     "cairosvg",
-    "click",
+    "rich-click",
     "jinja2",
     "pydantic",
     "pypdf",

src/pdfbaker/__main__.py

@@ -4,10 +4,11 @@
 import sys
 from pathlib import Path
 
-import click
+import rich_click as click
 
 from pdfbaker import __version__
 from pdfbaker.baker import Baker, BakerOptions
+from pdfbaker.console import HELP_CONFIG
 from pdfbaker.errors import (
     DocumentNotFoundError,
     DryRunCreateFromCompleted,
@@ -50,6 +51,7 @@
     metavar="SVG_FILE",
     help="Scaffold CONFIG_FILE and supporting files for your existing SVG.",
 )
+@click.rich_config(help_config=HELP_CONFIG)
 # pylint: disable=too-many-arguments,too-many-positional-arguments
 def cli(
     config_file: Path,

src/pdfbaker/baker.py

@@ -6,19 +6,30 @@
 bake() delegates to its documents and reports back the end result.
 """
 
+import logging
 import shutil
 from pathlib import Path
+from typing import NamedTuple
 
 from pydantic import BaseModel, ValidationError
 from ruamel.yaml import YAML
 
 from .config import PathSpec
 from .config.baker import BakerConfig
+from .console import build_create_from_panel, build_outcome_panel, stdout_console
 from .document import Document
 from .errors import DocumentNotFoundError, DryRunCreateFromCompleted
 from .logging import LoggingMixin, setup_logging
 
-__all__ = ["Baker", "BakerOptions"]
+__all__ = ["Baker", "BakerOptions", "ProcessedDoc"]
+
+
+class ProcessedDoc(NamedTuple):
+    """The outcome of processing a document, for reporting back to the user."""
+
+    document: Document
+    pdf_files: list[Path] | None
+    error_message: str | None
 
 
 class BakerOptions(BaseModel):
@@ -57,7 +68,7 @@ def __init__(
         setup_logging(quiet=options.quiet, trace=options.trace, verbose=options.verbose)
 
         if options.create_from:
-            self.create_from(
+            project_dir = self.create_from(
                 svg_path=options.create_from,
                 config_path=config_file,
                 dry_run=options.dry_run,
@@ -66,6 +77,10 @@ def __init__(
                 # Dry run creations don't continue with dry run processing
                 raise DryRunCreateFromCompleted()
 
+            if self.logger.getEffectiveLevel() <= logging.INFO:
+                panel = build_create_from_panel(options.create_from, project_dir)
+                stdout_console.print(panel)
+
         self.log_debug_section("Loading main configuration: %s", config_file)
         self.config = BakerConfig(
             config_file=config_file,
@@ -74,53 +89,32 @@ def __init__(
             dry_run=options.dry_run,
             **kwargs,
         )
-        self.log_trace(self.config.readable())
+        self.log_trace_preview(self.config.readable(), syntax="yaml")
         self.log_debug("Build directory: %s", self.config.directories.build)
 
     def bake(self, document_names: tuple[str, ...] | None = None) -> None:
         """Bake the documents."""
         docs = self._get_selected_documents(document_names)
+
+        if self.config.dry_run:
+            self.log_info("[DRY RUN] No files will be created.")
         self.log_debug_subsection("Documents to process:")
         self.log_debug(docs)
 
-        pdfs_created, failed_docs = self._process_documents(docs)
-
-        self.log_info("─" * 80)
-        if pdfs_created:
-            if self.config.dry_run:
-                self.log_info("👀 [DRY RUN] Would have created PDFs:")
-            else:
-                self.log_info("Successfully created PDFs:")
-            for pdf in pdfs_created:
-                self.log_info("  %s %s", "🟨" if self.config.dry_run else "✅", pdf)
-        else:
-            self.log_warning("No PDFs were created.")
+        processed_docs = self._process_documents(docs)
+        if not self.config.keep_build:
+            self.teardown()
 
-        if failed_docs:
-            self.log_warning(
-                "Failed to process %d document%s:",
-                len(failed_docs),
-                "" if len(failed_docs) == 1 else "s",
+        if self.logger.getEffectiveLevel() <= logging.INFO:
+            outcome_panel = build_outcome_panel(
+                processed_docs,
+                dry_run=self.config.dry_run,
+                keep_build=self.config.keep_build,
+                build_dir=self.config.directories.build,
             )
-            for failed_doc, error_message in failed_docs:
-                name = failed_doc.config.name
-                if isinstance(failed_doc, Document) and failed_doc.config.is_variant:
-                    name += f' variant "{failed_doc.config.variant["name"]}"'
-                self.log_error("  %s: %s", name, error_message)
-                if hasattr(failed_doc, "config"):
-                    self.log_debug(
-                        'Build directory for "%s": %s',
-                        name,
-                        failed_doc.config.directories.build,
-                    )
-
-        if self.config.keep_build:
-            if not self.config.dry_run:
-                self.log_info("Build files kept in: %s", self.config.directories.build)
-        else:
-            self.teardown()
+            stdout_console.print(outcome_panel)
 
-        return not failed_docs
+        return all(not d.error_message for d in processed_docs)
 
     def _get_selected_documents(
         self, selected_names: tuple[str, ...] | None = None
@@ -144,12 +138,8 @@ def _get_selected_documents(
 
         return [doc for doc in self.config.documents if doc.name in selected_names]
 
-    def _process_documents(
-        self, docs: list[PathSpec]
-    ) -> tuple[list[Path], list[tuple[PathSpec, str]]]:
-        pdfs_created: list[Path] = []
-        failed_docs: list[tuple[PathSpec, str]] = []
-
+    def _process_documents(self, docs: list[PathSpec]) -> list[ProcessedDoc]:
+        processed_docs: list[ProcessedDoc] = []
         for config_path in docs:
             try:
                 document = Document(
@@ -158,7 +148,7 @@ def _process_documents(
             except ValidationError as e:
                 error_message = f'Invalid config for document "{config_path.name}": {e}'
                 self.log_error(error_message)
-                failed_docs.append((config_path, error_message))
+                processed_docs.append(ProcessedDoc(config_path, None, error_message))
                 continue
 
             pdf_files, error_message = document.process_document()
@@ -169,15 +159,14 @@ def _process_documents(
                     document.config.name,
                     error_message,
                 )
-                failed_docs.append((document, error_message))
+                processed_docs.append(ProcessedDoc(document, None, error_message))
             else:
                 if isinstance(pdf_files, Path):
                     pdf_files = [pdf_files]
-                pdfs_created.extend(pdf_files)
+                processed_docs.append(ProcessedDoc(document, pdf_files, None))
             if not self.config.keep_build:
                 document.teardown()
-
-        return pdfs_created, failed_docs
+        return processed_docs
 
     def teardown(self) -> None:
         """Clean up (top-level) build directory after processing."""
@@ -190,7 +179,8 @@ def teardown(self) -> None:
                 self.log_debug("Removing top-level build directory...")
                 if self.config.dry_run:
                     self.log_debug(
-                        "👀 [DRY RUN] Not removing top-level build directory"
+                        ":no_entry_sign:"
+                        " [DRY RUN] Not removing top-level build directory"
                     )
                 else:
                     build_dir.rmdir()
@@ -202,8 +192,11 @@ def teardown(self) -> None:
     def create_from(
         self, svg_path: Path, config_path: Path, dry_run: bool = False
     ) -> None:
-        """Create a minimal project structure from an SVG and config path."""
+        """Create a scaffold for templating from an SVG and config path."""
         project_dir = config_path.parent
+        self.log_debug_section(
+            "Creating from %s in: %s", svg_path.resolve(), project_dir.resolve()
+        )
         doc_name = svg_path.stem
         doc_dir = project_dir / doc_name
         template_file = doc_dir / "templates" / "main.svg.j2"
@@ -218,22 +211,24 @@ def create_from(
 
         for f in files_to_create:
             if f.exists():
-                raise FileExistsError(f"File already exists: {f}")
+                raise FileExistsError(f"File already exists: {f.resolve()}")
 
         if dry_run:
             for d in dirs_to_create:
-                self.log_info("👀 [DRY RUN] Would create directory: %s", d)
+                self.log_info(":no_entry_sign: [DRY RUN] Would create directory: %s", d)
             for f in files_to_create:
-                self.log_info("👀 [DRY RUN] Would create file:      %s", f)
-            self.log_info("👀 [DRY RUN] No files created.")
+                self.log_info(":no_entry_sign: [DRY RUN] Would create file:      %s", f)
+            self.log_info(":no_entry_sign: [DRY RUN] No files created.")
             raise DryRunCreateFromCompleted()
 
         for d in dirs_to_create:
+            self.log_debug_subsection("Ensuring directory exists: %s", d.resolve())
             d.mkdir(parents=True, exist_ok=True)
 
         yaml = YAML()
         yaml.indent(mapping=2, sequence=4, offset=2)
 
+        self.log_debug_subsection("Writing main config: %s", config_path.resolve())
         with open(config_path, "w", encoding="utf-8") as f:
             f.write("# PDFBaker main config\n\n")
             yaml.dump({"documents": [doc_name]}, f)
@@ -262,8 +257,15 @@ def create_from(
                 "#   font: Arial\n"
                 "#   color: black\n"
             )
+        self.log_trace_preview(
+            config_path.read_text(encoding="utf-8"),
+            syntax="yaml",
+        )
         self.log_info("Created main config: %s", config_path)
 
+        self.log_debug_subsection(
+            "Writing document config: %s", doc_config_file.resolve()
+        )
         with open(doc_config_file, "w", encoding="utf-8") as f:
             f.write("# Document config\n\n")
             yaml.dump({"filename": doc_name, "pages": ["main"]}, f)
@@ -280,8 +282,13 @@ def create_from(
                 "#   font: Arial\n"
                 "#   color: black\n"
             )
+        self.log_trace_preview(
+            doc_config_file.read_text(encoding="utf-8"),
+            syntax="yaml",
+        )
         self.log_info("Created document config: %s", doc_config_file)
 
+        self.log_debug_subsection("Writing page config: %s", page_file.resolve())
         with open(page_file, "w", encoding="utf-8") as f:
             f.write("# Page config\n\n")
             yaml.dump({"template": "main.svg.j2", "name": "main"}, f)
@@ -293,7 +300,20 @@ def create_from(
                 "# title: My Document\n"
                 "# date: 2025-05-19\n"
             )
-        self.log_info("Created page: %s", page_file)
+        self.log_trace_preview(
+            page_file.read_text(encoding="utf-8"),
+            syntax="yaml",
+        )
+        self.log_info("Created page config: %s", page_file)
 
+        self.log_debug_subsection(
+            "Copying SVG to template: %s", template_file.resolve()
+        )
         shutil.copy(svg_path, template_file)
+        self.log_trace_preview(
+            template_file.read_text(encoding="utf-8"),
+            syntax="xml",
+        )
         self.log_info("Created template: %s", template_file)
+
+        return project_dir

src/pdfbaker/config/__init__.py

@@ -177,7 +177,7 @@ def truncating_representer(representer, data):
 
         stream = io.StringIO()
         yaml.dump(self.model_dump(), stream)
-        return f"\n{stream.getvalue()}"
+        return stream.getvalue()
 
     def resolve_path(self, path: Path) -> Path:
         """Resolve relative paths relative to the base directory."""