feat: Add --dry-run, --fail-if-exists, build in temp dir

Also prep `--create-from` (coming up)

Author: dannyadair

docs/configuration.md

@@ -32,7 +32,7 @@ At least `documents` has to be specified.
 | `documents` **required**        | array   | `[]`                                 | List of document configurations. A simple string specifies the name of a directory under `directories.documents`. A directory needs to contain a `config.yaml` file. You can also specify `path` and `name` to a specific directory or configuration YAML file.         |
 | `directories`                   | mapping | see the following settings           | You can override default directories with the `directories` mapping, just re-define one or more with one of the following settings.                                                                                                                                     |
 | `directories.base` **readonly** | string  | directory containing the config file | If directories are not absolute paths they will be relative to this base directory.                                                                                                                                                                                     |
-| `directories.build`             | string  | `"build"`                            | Intermediary SVG and PDF files are written here. Deleted unless you specified `--keep-build`.                                                                                                                                                                           |
+| `directories.build`             | string  |                                      | Intermediary SVG and PDF files are written here. If not set, will be a temporary directory. Deleted unless you specified `--keep-build`.                                                                                                                                |
 | `directories.dist`              | string  | `"dist"`                             | Final PDF files are written here.                                                                                                                                                                                                                                       |
 | `directories.documents`         | string  | `"."`                                | Location of document configurations.                                                                                                                                                                                                                                    |
 | `directories.images`            | string  | `"images"`                           | Location of image files.                                                                                                                                                                                                                                                |

src/pdfbaker/__main__.py

@@ -17,32 +17,51 @@
 @click.version_option(version=__version__, prog_name="pdfbaker")
 @click.argument(
     "config_file",
-    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    type=click.Path(exists=False, dir_okay=False, path_type=Path),
 )
-@click.argument("documents", nargs=-1)
-@click.option("-q", "--quiet", is_flag=True, help="Show errors only")
-@click.option("-v", "--verbose", is_flag=True, help="Show debug information")
+@click.argument("document_names", nargs=-1)
+@click.option("-q", "--quiet", is_flag=True, help="Show errors only.")
+@click.option("-v", "--verbose", is_flag=True, help="Show debug information.")
 @click.option(
     "-t",
     "--trace",
     is_flag=True,
-    help="Show trace information (even more detailed than --verbose)",
+    help="Show trace information (maximum details).",
+)
+@click.option(
+    "--keep-build", is_flag=True, help="Keep rendered SVGs and single-page PDFs."
+)
+@click.option(
+    "--debug", is_flag=True, help="Debug mode (implies --verbose and --keep-build)."
+)
+@click.option(
+    "--fail-if-exists",
+    is_flag=True,
+    help="Abort if a target PDF already exists.",
+)
+@click.option("--dry-run", is_flag=True, help="Do not write any files.")
+@click.option(
+    "--create-from",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    metavar="SVG_FILE",
+    help="Scaffold CONFIG_FILE and supporting files for your existing SVG.",
 )
-@click.option("--keep-build", is_flag=True, help="Keep build artifacts")
-@click.option("--debug", is_flag=True, help="Debug mode (--verbose and --keep-build)")
 # pylint: disable=too-many-arguments,too-many-positional-arguments
 def cli(
     config_file: Path,
-    documents: tuple[str, ...],
+    document_names: tuple[str, ...],
     quiet: bool,
     verbose: bool,
     trace: bool,
     keep_build: bool,
     debug: bool,
+    fail_if_exists: bool,
+    dry_run: bool,
+    create_from: Path | None,
 ) -> None:
     """Generate PDF documents from YAML-configured SVG templates.
 
-    Optionally specify one or more document names to only process those documents.
+    Specify one or more document names to only process those.
     """
     if debug:
         verbose = True
@@ -54,10 +73,16 @@ def cli(
             verbose=verbose,
             trace=trace,
             keep_build=keep_build,
+            fail_if_exists=fail_if_exists,
+            dry_run=dry_run,
+            create_from=create_from,
         )
         baker = Baker(config_file, options=options)
-        success = baker.bake(document_names=documents if documents else None)
+        success = baker.bake(document_names=document_names)
         sys.exit(0 if success else 1)
+    except FileNotFoundError as exc:
+        logger.error("❌ %s", str(exc))
+        sys.exit(2)
     except DocumentNotFoundError as exc:
         logger.error("❌ %s", str(exc))
         sys.exit(2)

src/pdfbaker/baker.py

@@ -27,14 +27,18 @@ class BakerOptions(BaseModel):
         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
+        dry_run: Do not write any files, just log actions
+        fail_if_exists: Abort if a file already exists in the dist directory
+        create_from: Path to SVG file for populating a (new) project
     """
 
     quiet: bool = False
     verbose: bool = False
     trace: bool = False
     keep_build: bool = False
+    fail_if_exists: bool = False
+    dry_run: bool = False
+    create_from: Path | None = None
 
 
 class Baker(LoggingMixin):
@@ -49,13 +53,18 @@ def __init__(
         """Set up logging and load configuration."""
         options = options or BakerOptions()
         setup_logging(quiet=options.quiet, trace=options.trace, verbose=options.verbose)
+        self.create_from = options.create_from
+        # FIXME: use create_from to create a new config file
         self.log_debug_section("Loading main configuration: %s", config_file)
         self.config = BakerConfig(
             config_file=config_file,
             keep_build=options.keep_build,
+            fail_if_exists=options.fail_if_exists,
+            dry_run=options.dry_run,
             **kwargs,
         )
         self.log_trace(self.config.readable())
+        self.log_debug("Build directory: %s", self.config.directories.build)
 
     def bake(self, document_names: tuple[str, ...] | None = None) -> None:
         """Bake the documents."""
@@ -65,27 +74,39 @@ def bake(self, document_names: tuple[str, ...] | None = None) -> None:
 
         pdfs_created, failed_docs = self._process_documents(docs)
 
+        self.log_info("─" * 80)
         if pdfs_created:
-            self.log_info("Successfully created PDFs:")
+            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", pdf)
+                self.log_info("  %s %s", "🟨" if self.config.dry_run else "✅", pdf)
         else:
             self.log_warning("No PDFs were created.")
 
-        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",
             )
             for failed_doc, error_message in failed_docs:
-                name = failed_doc.name
-                if isinstance(failed_doc, Document) and failed_doc.is_variant:
-                    name += f' variant "{failed_doc.variant["name"]}"'
+                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:
+            self.log_info("Build files kept in: %s", self.config.directories.build)
+        else:
+            self.teardown()
 
         return not failed_docs
 
@@ -155,6 +176,13 @@ def teardown(self) -> None:
         if build_dir.exists():
             try:
                 self.log_debug("Removing top-level build directory...")
-                build_dir.rmdir()
+                if self.config.dry_run:
+                    self.log_debug(
+                        "👀 [DRY RUN] Not removing top-level build directory"
+                    )
+                else:
+                    build_dir.rmdir()
             except OSError:
                 self.log_warning("Top-level build directory not empty - not removing")
+        else:
+            self.log_debug("Top-level build directory does not exist")

src/pdfbaker/config/__init__.py

@@ -119,6 +119,8 @@ class BaseConfig(BaseModel, LoggingMixin):
     svg2pdf_backend: SVG2PDFBackend | None = SVG2PDFBackend.CAIROSVG
     compress_pdf: bool = False
     keep_build: bool = False
+    dry_run: bool = False
+    fail_if_exists: bool = False
 
     model_config = ConfigDict(
         strict=True,  # don't try to coerce values

src/pdfbaker/config/baker.py

@@ -1,5 +1,6 @@
 """Baker configuration for pdfbaker."""
 
+import tempfile
 from pathlib import Path
 from typing import Any
 
@@ -9,7 +10,7 @@
 from . import BaseConfig, PathSpec
 
 DEFAULT_DIRECTORIES = {
-    "build": "build",
+    "build": None,
     "dist": "dist",
     "documents": ".",
     "pages": "pages",
@@ -48,6 +49,10 @@ def load_config(cls, data: Any) -> Any:
             for key, default in DEFAULT_DIRECTORIES.items():
                 directories.setdefault(key, default)
 
+            # If build dir is not set, use a temp dir
+            if not directories.get("build"):
+                directories["build"] = tempfile.mkdtemp(prefix="pdfbaker-")
+
             if "documents" not in data:
                 raise ValueError(
                     'Key "documents" missing - is this the main configuration file?'

src/pdfbaker/document.py

@@ -7,7 +7,7 @@
 """
 
 import importlib
-import os
+import shutil
 from pathlib import Path
 
 from .config import PathSpec
@@ -49,14 +49,22 @@ def process_document(self) -> tuple[Path | list[Path] | None, str | None]:
         self.config.directories.dist /= self.config.name
 
         self.log_info_section('Processing document "%s"...', self.config.name)
+
         self.log_debug(
             "Ensuring build directory exists: %s", self.config.directories.build
         )
-        self.config.directories.build.mkdir(parents=True, exist_ok=True)
+        if self.config.dry_run:
+            self.log_debug("👀 [DRY RUN] Not creating build directory")
+        else:
+            self.config.directories.build.mkdir(parents=True, exist_ok=True)
+
         self.log_debug(
             "Ensuring dist directory exists: %s", self.config.directories.dist
         )
-        self.config.directories.dist.mkdir(parents=True, exist_ok=True)
+        if self.config.dry_run:
+            self.log_debug("👀 [DRY RUN] Not creating dist directory")
+        else:
+            self.config.directories.dist.mkdir(parents=True, exist_ok=True)
 
         try:
             if self.config.custom_bake:
@@ -150,31 +158,45 @@ def _finalize(self, pdf_files: list[Path], doc_config: DocumentConfig) -> Path:
         """Combine PDF pages and optionally compress."""
         self.log_debug_subsection("Finalizing document...")
         self.log_debug("Combining PDF pages...")
-        try:
-            combined_pdf = combine_pdfs(
-                pdf_files,
-                self.config.directories.build / f"{doc_config.filename}.pdf",
-            )
-        except PDFCombineError as exc:
-            raise PDFBakerError(f"Failed to combine PDFs: {exc}") from exc
+
+        if self.config.dry_run:
+            self.log_debug("👀 [DRY RUN] Not combining PDF pages")
+        else:
+            try:
+                combined_pdf = combine_pdfs(
+                    pdf_files,
+                    self.config.directories.build / f"{doc_config.filename}.pdf",
+                )
+            except PDFCombineError as exc:
+                raise PDFBakerError(f"Failed to combine PDFs: {exc}") from exc
 
         output_path = self.config.directories.dist / f"{doc_config.filename}.pdf"
 
+        if self.config.fail_if_exists and output_path.exists():
+            raise PDFBakerError(f"File already exists: {output_path}")
+
         if doc_config.compress_pdf:
             self.log_debug("Compressing PDF document...")
-            try:
-                compress_pdf(combined_pdf, output_path)
-                self.log_info("PDF compressed successfully")
-            except PDFCompressionError as exc:
-                self.log_warning(
-                    "Compression failed, using uncompressed PDF: %s",
-                    exc,
-                )
-                os.rename(combined_pdf, output_path)
+            if self.config.dry_run:
+                self.log_debug("👀 [DRY RUN] Not compressing PDF document")
+            else:
+                try:
+                    compress_pdf(combined_pdf, output_path)
+                    self.log_info("PDF compressed successfully")
+                except PDFCompressionError as exc:
+                    self.log_warning(
+                        "Compression failed, using uncompressed PDF: %s",
+                        exc,
+                    )
+                    shutil.move(combined_pdf, output_path)
         else:
-            os.rename(combined_pdf, output_path)
+            if not self.config.dry_run:
+                shutil.move(combined_pdf, output_path)
 
-        self.log_info("Created %s", output_path.name)
+        if self.config.dry_run:
+            self.log_info("👀 [DRY RUN] Did not create %s", output_path.name)
+        else:
+            self.log_info("Created %s", output_path.name)
         return output_path
 
     def teardown(self) -> None:
@@ -183,12 +205,21 @@ def teardown(self) -> None:
         self.log_debug_subsection("Tearing down build directory: %s", build_dir)
         if build_dir.exists():
             self.log_debug("Removing files in build directory...")
-            for file_path in build_dir.iterdir():
-                if file_path.is_file():
-                    file_path.unlink()
+
+            if self.config.dry_run:
+                self.log_debug("👀 [DRY RUN] Not removing files in build directory")
+            else:
+                for file_path in build_dir.iterdir():
+                    if file_path.is_file():
+                        file_path.unlink()
 
             try:
                 self.log_debug("Removing build directory...")
-                build_dir.rmdir()
+                if self.config.dry_run:
+                    self.log_debug("👀 [DRY RUN] Not removing build directory")
+                else:
+                    build_dir.rmdir()
             except OSError:
                 self.log_warning("Build directory not empty - not removing")
+        else:
+            self.log_debug("Build directory does not exist")

src/pdfbaker/page.py

@@ -85,8 +85,13 @@ def process(self) -> Path:
                     renderer.value for renderer in self.config.template_renderers
                 ],
             )
-            with open(output_svg, "w", encoding="utf-8") as f:
-                f.write(rendered_template)
+            if self.config.dry_run:
+                self.log_debug(
+                    "👀 [DRY RUN] Not writing rendered template to %s", output_svg
+                )
+            else:
+                with open(output_svg, "w", encoding="utf-8") as f:
+                    f.write(rendered_template)
         except TemplateError as exc:
             raise SVGTemplateError(
                 "Failed to render page "
@@ -95,6 +100,9 @@ def process(self) -> Path:
         self.log_trace_preview(rendered_template)
 
         self.log_debug("Converting SVG to PDF: %s", output_svg)
+        if self.config.dry_run:
+            self.log_debug("👀 [DRY RUN] Not converting SVG to PDF")
+            return None
         try:
             return convert_svg_to_pdf(
                 output_svg,