pymd2pdf 0.1.0__py3-none-any.whl

md2pdf/__init__.py

@@ -0,0 +1,52 @@
+"""md2pdf: Programmatic Markdown-to-PDF typesetting engine."""
+
+from __future__ import annotations
+
+from md2pdf.core.config import Config
+from md2pdf.core.errors import (
+    ConfigError,
+    Md2PdfError,
+    ParseError,
+    RenderError,
+    ValidationIssue,
+)
+from md2pdf.core.pipeline import Pipeline
+from md2pdf.core.registry import HandlerRegistry
+
+__version__ = "0.1.0"
+__all__ = [
+    "Config",
+    "Pipeline",
+    "HandlerRegistry",
+    "convert",
+    "ValidationIssue",
+    "Md2PdfError",
+    "ParseError",
+    "RenderError",
+    "ConfigError",
+]
+
+
+def convert(
+    src: str,
+    dst: str,
+    config: Config | None = None,
+    registry: HandlerRegistry | None = None,
+) -> None:
+    """High-level API: convert a Markdown file to a PDF.
+
+    Args:
+        src: Path to the input Markdown file.
+        dst: Path to the output PDF file.
+        config: Optional Config instance. If omitted, defaults are used.
+        registry: Optional custom HandlerRegistry instance.
+    """
+    if config is None:
+        config = Config(input_file=src, output_file=dst)
+    else:
+        config.input_file = src
+        config.output_file = dst
+
+    pipeline = Pipeline(config, registry)
+    raw_md = open(src, encoding="utf-8").read()  # noqa: WPS515
+    pipeline.run(raw_md)

md2pdf/assets/__init__.py

@@ -0,0 +1 @@
+"""md2pdf.assets — diagram rendering helpers (Kroki API, disk cache, fallback)."""

md2pdf/assets/cache.py

@@ -0,0 +1,72 @@
+"""Disk-based asset cache for rendered diagram images.
+
+Cache key is SHA-256(``{diagram_type}:{source_text}``), stored as
+``{cache_dir}/{key}.png``.  Because the key is derived from the content,
+changing the source automatically produces a new key — no explicit
+invalidation is needed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class AssetCache:
+    """Hash-keyed disk cache for PNG diagram images.
+
+    Args:
+        cache_dir: Directory to store cached PNG files.  Created on first use
+            if it does not already exist.  Defaults to ``.md2pdf_cache``.
+    """
+
+    def __init__(self, cache_dir: str = ".md2pdf_cache") -> None:
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get(self, diagram_type: str, source: str) -> bytes | None:
+        """Return cached PNG bytes, or ``None`` if not cached.
+
+        Args:
+            diagram_type: Kroki diagram type string (e.g. ``"mermaid"``).
+            source: Raw diagram source text.
+
+        Returns:
+            PNG bytes if the entry exists in the cache, otherwise ``None``.
+        """
+        path = self._path(diagram_type, source)
+        if path.exists():
+            logger.debug("Cache hit: %s", path.name)
+            return path.read_bytes()
+        logger.debug("Cache miss: %s", path.name)
+        return None
+
+    def put(self, diagram_type: str, source: str, data: bytes) -> None:
+        """Store *data* in the cache under the key for (*diagram_type*, *source*).
+
+        Args:
+            diagram_type: Kroki diagram type string.
+            source: Raw diagram source text.
+            data: PNG bytes to cache.
+        """
+        path = self._path(diagram_type, source)
+        path.write_bytes(data)
+        logger.debug("Cached %d bytes → %s", len(data), path.name)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _key(self, diagram_type: str, source: str) -> str:
+        raw = f"{diagram_type}:{source}"
+        return hashlib.sha256(raw.encode()).hexdigest()
+
+    def _path(self, diagram_type: str, source: str) -> Path:
+        return self.cache_dir / f"{self._key(diagram_type, source)}.png"

md2pdf/assets/fallback.py

@@ -0,0 +1,79 @@
+"""Offline / error fallback renderer for diagram blocks.
+
+When ``Config.offline=True`` or a network/render error occurs,
+:class:`PlaceholderBox` is returned instead of crashing the conversion run.
+"""
+
+from __future__ import annotations
+
+from reportlab.lib import colors
+from reportlab.platypus import Flowable
+
+_BORDER_COLOR = colors.HexColor("#aaaaaa")
+_BG_COLOR = colors.HexColor("#f9f9f9")
+_LABEL_COLOR = colors.HexColor("#888888")
+_SOURCE_COLOR = colors.HexColor("#555555")
+
+_LABEL_FONT = "Helvetica-Oblique"
+_SOURCE_FONT = "Courier"
+
+_LABEL_SIZE = 8
+_SOURCE_SIZE = 7
+_PADDING = 6
+_LINE_HEIGHT = 14
+
+
+class PlaceholderBox(Flowable):
+    """A grey bordered box displayed when diagram rendering is unavailable.
+
+    Shows the diagram type and a truncated preview of the source so readers
+    know something was not rendered rather than silently missing content.
+
+    Args:
+        diagram_type: Kroki diagram type string (e.g. ``"mermaid"``).
+        source: Raw diagram source.  Truncated to 120 characters in the box.
+        width: Box width in ReportLab points.  Defaults to ``400``.
+        height: Box height in ReportLab points.  Defaults to ``80``.
+    """
+
+    _MAX_SOURCE_PREVIEW = 120
+
+    def __init__(
+        self,
+        diagram_type: str,
+        source: str,
+        width: float = 400,
+        height: float = 80,
+    ) -> None:
+        super().__init__()
+        self.diagram_type = diagram_type
+        self.source_preview = source[: self._MAX_SOURCE_PREVIEW] + (
+            "..." if len(source) > self._MAX_SOURCE_PREVIEW else ""
+        )
+        self.width = width
+        self.height = height
+
+    # ReportLab calls wrap() to query our dimensions before draw().
+    def wrap(
+        self, available_width: float, available_height: float
+    ) -> tuple[float, float]:  # noqa: ARG002
+        return self.width, self.height
+
+    def draw(self) -> None:
+        c = self.canv
+
+        # Background + border
+        c.setStrokeColor(_BORDER_COLOR)
+        c.setFillColor(_BG_COLOR)
+        c.rect(0, 0, self.width, self.height, fill=1)
+
+        # Label line: "[mermaid diagram — offline / render failed]"
+        c.setFillColor(_LABEL_COLOR)
+        c.setFont(_LABEL_FONT, _LABEL_SIZE)
+        label = f"[{self.diagram_type} diagram — offline / render failed]"
+        c.drawString(_PADDING, self.height - _LINE_HEIGHT, label)
+
+        # Source preview line
+        c.setFillColor(_SOURCE_COLOR)
+        c.setFont(_SOURCE_FONT, _SOURCE_SIZE)
+        c.drawString(_PADDING, self.height - _LINE_HEIGHT * 2, self.source_preview)

md2pdf/assets/kroki.py

@@ -0,0 +1,70 @@
+"""HTTP client for the Kroki.io diagram-rendering API.
+
+Kroki accepts a diagram type and source text, and returns a PNG image.
+
+Endpoint (POST form used here to avoid URL-length limits on large diagrams)::
+
+    POST https://kroki.io/{diagram_type}/png
+    Content-Type: text/plain
+    Body: <diagram source>
+
+Supported diagram type strings used by md2pdf:
+
++---------------+------------------+--------------------------------------+
+| Token type    | Kroki type       | Notes                                |
++===============+==================+======================================+
+| ``Mermaid``   | ``"mermaid"``    | Flowcharts, sequence, Gantt, etc.    |
++---------------+------------------+--------------------------------------+
+| ``LatexBlock``| ``"tikz"``       | Requires ``\\documentclass`` wrapper  |
++---------------+------------------+--------------------------------------+
+"""
+
+from __future__ import annotations
+
+import logging
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+KROKI_BASE = "https://kroki.io"
+
+
+class KrokiClient:
+    """Thin wrapper around the Kroki.io HTTP API.
+
+    Args:
+        base_url: Base URL of the Kroki server.  Override in tests or for
+            self-hosted Kroki instances.
+        timeout: Request timeout in seconds.  Defaults to ``15``.
+    """
+
+    def __init__(self, base_url: str = KROKI_BASE, timeout: int = 15) -> None:
+        self.base_url = base_url
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    def render(self, diagram_type: str, source: str) -> bytes:
+        """Fetch PNG bytes from Kroki for the given *diagram_type* and *source*.
+
+        Args:
+            diagram_type: Kroki diagram type string (e.g. ``"mermaid"``).
+            source: Raw diagram source text.
+
+        Returns:
+            Raw PNG bytes returned by the Kroki API.
+
+        Raises:
+            requests.HTTPError: If the server returns a non-2xx status code.
+            requests.RequestException: On any connection/timeout error.
+        """
+        url = f"{self.base_url}/{diagram_type}/png"
+        resp = self._session.post(
+            url,
+            data=source.encode("utf-8"),
+            headers={"Content-Type": "text/plain"},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        logger.debug("Kroki rendered %s (%d bytes)", diagram_type, len(resp.content))
+        return resp.content

md2pdf/cli.py

@@ -0,0 +1,114 @@
+"""CLI entry point for md2pdf."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(
+    name="md2pdf",
+    help="Convert structured Markdown files to print-ready PDFs.",
+    add_completion=False,
+)
+
+
+def _setup_logging(verbose: bool) -> None:
+    level = logging.DEBUG if verbose else logging.WARNING
+    # Clean standard logging configuration directed to stderr
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s  %(name)s: %(message)s",
+        stream=sys.stderr,
+        force=True,  # Override any existing configuration
+    )
+
+
+def _report_issues(issues: list) -> None:
+    for issue in issues:
+        icon = "✗" if issue.severity == "error" else "⚠"
+        line_str = f"Line {issue.line}" if issue.line is not None else "Line ?"
+        typer.echo(f"{icon} {line_str}: [{issue.code}] {issue.message}")
+
+
+@app.command()
+def convert(
+    input: Path = typer.Argument(..., help="Path to input .md file"),  # noqa: B008
+    output: Path = typer.Option(  # noqa: B008
+        Path("output.pdf"), "-o", "--output", help="Output PDF path"
+    ),
+    config_file: Path = typer.Option(  # noqa: B008
+        None, "-c", "--config", help="Path to md2pdf.toml"
+    ),
+    theme: str = typer.Option("default", "-t", "--theme", help="Theme name"),  # noqa: B008
+    offline: bool = typer.Option(  # noqa: B008
+        False, "--offline", help="Skip external API calls; use placeholders instead"
+    ),
+    verbose: bool = typer.Option(  # noqa: B008
+        False, "-v", "--verbose", help="Enable debug logging to stderr"
+    ),
+    validate_only: bool = typer.Option(  # noqa: B008
+        False, "--validate-only", help="Run validation but do not render"
+    ),
+    min_image_scale: float = typer.Option(  # noqa: B008
+        None,
+        "--min-image-scale",
+        help="Minimum scale factor for resizing images before deferring to a new page (e.g. 0.8)",
+    ),
+) -> None:
+    """Convert a Markdown file to a print-ready PDF."""
+    _setup_logging(verbose)
+
+    # Defer heavy imports so --help is instant even without all deps installed.
+    from md2pdf.core.config import Config
+    from md2pdf.core.pipeline import Pipeline
+    from md2pdf.core.registry import HandlerRegistry
+
+    if not input.exists():
+        typer.echo(f"✗ Input file not found: {input}", err=True)
+        raise typer.Exit(code=1)
+
+    cfg = Config(
+        input_file=str(input),
+        output_file=str(output),
+        theme=theme,
+        offline=offline,
+    )
+    if min_image_scale is not None:
+        cfg.min_image_scale = min_image_scale
+
+    if config_file is not None:
+        if not config_file.exists():
+            typer.echo(f"✗ Config file not found: {config_file}", err=True)
+            raise typer.Exit(code=1)
+        cfg = Config.from_toml(str(config_file))
+        # CLI arguments take precedence over config file values.
+        cfg.input_file = str(input)
+        cfg.output_file = str(output)
+        if theme != "default":
+            cfg.theme = theme
+        if offline:
+            cfg.offline = True
+        if min_image_scale is not None:
+            cfg.min_image_scale = min_image_scale
+
+    registry = HandlerRegistry()
+    pipeline = Pipeline(cfg, registry)
+
+    raw_md = input.read_text(encoding="utf-8")
+
+    if validate_only:
+        issues = pipeline.validate(raw_md)
+        _report_issues(issues)
+        has_errors = any(i.severity == "error" for i in issues)
+        raise typer.Exit(code=1 if has_errors else 0)
+
+    try:
+        pipeline.run(raw_md)
+        typer.echo(f"✓ PDF written to: {output}")
+    except Exception as exc:
+        logging.exception("Conversion failed")
+        typer.echo(f"✗ Conversion failed: {exc}", err=True)
+        raise typer.Exit(code=1) from exc

md2pdf/core/__init__.py

@@ -0,0 +1 @@
+"""Core sub-package for md2pdf."""

md2pdf/core/config.py

@@ -0,0 +1,86 @@
+"""Configuration dataclass for md2pdf."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field, fields
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class Config:
+    """Runtime configuration for the md2pdf pipeline.
+
+    All fields map 1:1 to entries in the ``[md2pdf]`` section of
+    ``md2pdf.toml``.  Unknown keys in the TOML file are silently ignored
+    so that future fields can be introduced without breaking existing
+    config files.
+
+    The ``theme_config`` attribute is populated from the optional ``[theme]``
+    section and is **not** a direct TOML field — it is excluded from the
+    known-fields filter in :meth:`from_toml`.
+
+    ``plugins_dict`` is populated from the ``[plugins]`` TOML section and
+    contains three optional keys: ``handlers``, ``preprocessors``, and
+    ``postprocessors``, each a list of fully-qualified class paths.
+    """
+
+    input_file: str = ""
+    output_file: str = "output.pdf"
+    theme: str = "default"
+    offline: bool = False
+    cache_dir: str = ".md2pdf_cache"
+    min_image_scale: float = 0.8
+
+    # Structured plugin config from [plugins] TOML section.
+    # Keys: "handlers", "preprocessors", "postprocessors" → list[str]
+    plugins_dict: dict = field(default_factory=dict)
+
+    # Populated from the [theme] TOML section; None means "use ThemeConfig defaults".
+    theme_config: Any = field(default=None, repr=False)
+
+    @classmethod
+    def from_toml(cls, path: str) -> Config:
+        """Load configuration from a TOML file.
+
+        Reads the ``[md2pdf]`` table for core settings, the ``[theme]``
+        table (if present) to build a :class:`~md2pdf.styles.theme.ThemeConfig`,
+        and the ``[plugins]`` table for plugin class paths.
+
+        Args:
+            path: Filesystem path to the TOML config file.
+
+        Returns:
+            A populated Config instance.
+
+        Raises:
+            FileNotFoundError: If *path* does not exist.
+            tomllib.TOMLDecodeError: If the file is not valid TOML.
+        """
+        with open(path, "rb") as fh:
+            data = tomllib.load(fh)
+
+        md2pdf_section: dict = data.get("md2pdf", {})
+        # ``theme_config`` and ``plugins_dict`` are not direct TOML fields.
+        known: set[str] = {f.name for f in fields(cls)} - {"theme_config", "plugins_dict"}
+        filtered = {k: v for k, v in md2pdf_section.items() if k in known}
+
+        cfg = cls(**filtered)
+
+        # Load [theme] section into a ThemeConfig (import here to avoid
+        # circular imports / hard reportlab dependency at module load time).
+        try:
+            from md2pdf.styles.theme import ThemeConfig  # noqa: PLC0415
+
+            theme_data: dict = data.get("theme", {})
+            cfg.theme_config = ThemeConfig.from_dict(theme_data)
+        except Exception:
+            cfg.theme_config = None
+
+        # Load [plugins] section into plugins_dict.
+        cfg.plugins_dict = data.get("plugins", {})
+
+        return cfg

md2pdf/core/errors.py

@@ -0,0 +1,33 @@
+"""Structured error and validation issue types for md2pdf."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class ValidationIssue:
+    """Represents a warning or error discovered during pre-render validation."""
+
+    severity: Literal["error", "warning"]
+    code: str  # e.g. "UNSUPPORTED_ELEMENT", "EMPTY_TABLE", "NESTED_TABLE"
+    message: str
+    line: int | None = None
+    element_type: str | None = None
+
+
+class Md2PdfError(Exception):
+    """Base exception for all md2pdf errors."""
+
+
+class ParseError(Md2PdfError):
+    """Raised when the markdown cannot be parsed."""
+
+
+class RenderError(Md2PdfError):
+    """Raised when PDF generation fails."""
+
+
+class ConfigError(Md2PdfError):
+    """Raised for invalid configuration."""

md2pdf/core/flowables.py

@@ -0,0 +1,156 @@
+"""Custom ReportLab flowables for md2pdf typesetting safeguards."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from reportlab.lib import colors
+from reportlab.platypus import Flowable, Image
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from reportlab.lib.colors import Color
+
+
+class BlockQuoteBar(Flowable):
+    """A custom Flowable wrapping an inner flowable with a left vertical accent bar.
+
+    This ensures that the accent bar spans the exact height of the nested content,
+    and cleanly delegates wrapping, drawing, and splitting so the blockquote
+    can break across page boundaries without formatting errors.
+    """
+
+    def __init__(
+        self,
+        inner_flowable: Flowable,
+        bar_color: Color | None = None,
+        bar_width: float = 3.0,
+        padding: float = 8.0,
+    ) -> None:
+        super().__init__()
+        self.inner = inner_flowable
+        self.bar_color = bar_color or colors.HexColor("#cccccc")
+        self.bar_width = bar_width
+        self.padding = padding
+        self.width = 0.0
+        self.height = 0.0
+
+    def wrap(self, availWidth: float, availHeight: float) -> tuple[float, float]:
+        inner_avail_width = max(0.0, availWidth - (self.bar_width + self.padding))
+        w_inner, h_inner = self.inner.wrap(inner_avail_width, availHeight)
+        self.width = w_inner + self.bar_width + self.padding
+        self.height = h_inner
+        return self.width, self.height
+
+    def draw(self) -> None:
+        c = self.canv
+        c.saveState()
+        c.setFillColor(self.bar_color)
+        c.rect(0, 0, self.bar_width, self.height, fill=1, stroke=0)
+        c.restoreState()
+        self.inner.drawOn(c, self.bar_width + self.padding, 0)
+
+    def split(self, availWidth: float, availHeight: float) -> list[Flowable]:
+        inner_avail_width = max(0.0, availWidth - (self.bar_width + self.padding))
+        splits = self.inner.split(inner_avail_width, availHeight)
+        if not splits:
+            return []
+        return [
+            BlockQuoteBar(
+                s,
+                bar_color=self.bar_color,
+                bar_width=self.bar_width,
+                padding=self.padding,
+            )
+            for s in splits
+        ]
+
+
+class BookmarkFlowable(Flowable):
+    """A custom flowable that registers a PDF bookmark anchor on the current page.
+
+    This is an invisible, zero-size flowable inserted just before heading flowables
+    to serve as anchor destinations for Table of Contents links.
+    """
+
+    def __init__(self, key: str) -> None:
+        super().__init__()
+        self.key = key
+
+    def wrap(self, availWidth: float, availHeight: float) -> tuple[float, float]:
+        return 0.0, 0.0
+
+    def draw(self) -> None:
+        self.canv.bookmarkPage(self.key)
+
+
+class ResizableImage(Image):
+    """An Image subclass that dynamically fits itself into available page space.
+
+    If the image does not fit within the remaining vertical space on the current page,
+    and we are not yet on a fresh page (i.e., we have room to defer), it triggers a
+    deferral by returning its original dimensions. ReportLab will then push it to
+    the next page.
+
+    On a fresh page, or if we have already deferred once, it scales down proportionally
+    to fit the remaining page height/width (down to a minimum scale if needed to
+    prevent layout overflows).
+    """
+
+    # Track the maximum available height seen in the current rendering pass.
+    # Updated dynamically on each wrap call to learn the printable page frame height.
+    max_avail_height: float = 0.0
+
+    # Minimum scale factor before deferring rendering to the next page.
+    min_scale: float = 0.8
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._deferred: bool = False
+        # Capture the initial target width and height to serve as our scaling baseline.
+        # ReportLab's Image stores these in self.drawWidth and self.drawHeight.
+        self.orig_width: float = float(self.drawWidth)
+        self.orig_height: float = float(self.drawHeight)
+
+    def wrap(self, availWidth: float, availHeight: float) -> tuple[float, float]:
+        # Update the class-level maximum seen height
+        ResizableImage.max_avail_height = max(ResizableImage.max_avail_height, availHeight)
+
+        # Calculate the scale factor required to fit the remaining space
+        s = max(0.01, min(1.0, availWidth / self.orig_width, availHeight / self.orig_height))
+
+        # We are on a fresh page (or as close to it as possible with preceding block elements
+        # in KeepTogether like heading/bookmark) if the available height is close to the max.
+        # We allow a margin of 120 points for preceding titles/headings.
+        is_fresh_page = availHeight >= ResizableImage.max_avail_height - 120.0
+
+        # Scale limit check using min_scale setting
+        if s >= ResizableImage.min_scale or is_fresh_page or self._deferred:
+            # We scale the image to fit
+            self.drawWidth = self.orig_width * s
+            self.drawHeight = self.orig_height * s
+            logger.debug(
+                "ResizableImage.wrap: fit. original=(%.2fx%.2f), scale=%.2f, new=(%.2fx%.2f), is_fresh=%s",
+                self.orig_width,
+                self.orig_height,
+                s,
+                self.drawWidth,
+                self.drawHeight,
+                is_fresh_page,
+            )
+            return self.drawWidth, self.drawHeight
+        else:
+            # Defer to the next page by returning original dimensions
+            # ReportLab will find this too large for the current page and push it to the next
+            self._deferred = True
+            logger.debug(
+                "ResizableImage.wrap: defer. original=(%.2fx%.2f), availHeight=%.2f, scale=%.2f, max_avail=%.2f",
+                self.orig_width,
+                self.orig_height,
+                availHeight,
+                s,
+                ResizableImage.max_avail_height,
+            )
+            return self.orig_width, self.orig_height