typoprint 0.1.0__py3-none-any.whl

typoprint/__init__.py

@@ -0,0 +1,40 @@
+"""Typoprint: offline Markdown-to-PDF for Python applications and the CLI."""
+
+from typoprint.config import load_settings
+from typoprint.models import (
+    Chapter,
+    ConfigurationError,
+    Document,
+    PlannedFile,
+    PrintPlan,
+    RenderError,
+    RenderResult,
+    RuleError,
+    Settings,
+    Transform,
+    TypoprintError,
+    Validator,
+)
+from typoprint.output import write_pdf
+from typoprint.planning import plan_files
+from typoprint.rendering import render, render_files
+
+__all__ = [
+    "Chapter",
+    "ConfigurationError",
+    "Document",
+    "PlannedFile",
+    "PrintPlan",
+    "RenderError",
+    "RenderResult",
+    "RuleError",
+    "Settings",
+    "Transform",
+    "TypoprintError",
+    "Validator",
+    "load_settings",
+    "plan_files",
+    "render",
+    "render_files",
+    "write_pdf",
+]

typoprint/__main__.py

@@ -0,0 +1,3 @@
+from typoprint.cli import main
+
+raise SystemExit(main())

typoprint/_ordering.py

@@ -0,0 +1,215 @@
+"""Tables of contents: one Markdown file fixing the order and parts of printed Markdown.
+
+The order is a pure function of the file's text and the files found under its folder:
+the file comes first, each `##` heading opens a part whose links place pages in reading
+order, a folder link adds the rest of that folder in natural order, and files placed
+nowhere come last.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+import unicodedata
+from collections.abc import Iterable, Sequence
+from pathlib import Path, PurePosixPath
+from typing import NamedTuple
+from urllib.parse import unquote
+
+from typoprint.models import Language as Language
+from typoprint.models import RenderError as RenderError
+
+UNPLACED_TITLE: dict[Language, str] = {"fr": "Autres pages", "en": "Other pages"}
+_DIGITS = re.compile(r"([0-9]+)")
+_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+_PART = re.compile(r"^ {0,3}##[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$")
+_CODE_SPAN = re.compile(r"(`+).+?\1")
+# Inline links and images: `[text](target "title")`; the leading `!` marks an image.
+_LINK = re.compile(r"(!?)\[[^\]]*\]\(\s*<?([^\s)>]*)>?[^)]*\)")
+_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+NaturalKey = tuple[tuple[tuple[int, int, str], ...], str]
+ReadingKey = tuple[tuple[int, int, NaturalKey], ...]
+
+
+class TocPart(NamedTuple):
+    title: str
+    # Link targets in reading order, as written.
+    targets: tuple[str, ...]
+
+
+class PlannedGroup(NamedTuple):
+    title: str
+    pages: tuple[PurePosixPath, ...]
+
+
+class OrderedMap(NamedTuple):
+    root: Path
+    # The table of contents itself, unless excluded.
+    intro: PurePosixPath | None
+    groups: tuple[PlannedGroup, ...]
+    # Found under the root but placed nowhere: printed last, in natural order.
+    unplaced: tuple[PurePosixPath, ...]
+
+    def chapters(self, lang: Language) -> list[tuple[Path, str | None]]:
+        """Files to print with the part each one opens."""
+        chapters: list[tuple[Path, str | None]] = []
+        if self.intro is not None:
+            chapters.append((self.root / self.intro, None))
+        for title, pages in (*self.groups, (UNPLACED_TITLE[lang], self.unplaced)):
+            chapters.extend(
+                (self.root / path, title if index == 0 else None)
+                for index, path in enumerate(pages)
+            )
+        return chapters
+
+
+def natural_key(name: str) -> NaturalKey:
+    """Numbers by value, text without case, after NFC; the exact name breaks ties."""
+    text = unicodedata.normalize("NFC", name)
+    chunks = tuple(
+        (0, int(chunk), "") if index % 2 else (1, 0, chunk.casefold())
+        for index, chunk in enumerate(_DIGITS.split(text))
+        if chunk
+    )
+    return chunks, text
+
+
+def reading_order(relative: PurePosixPath) -> ReadingKey:
+    # In each folder: README.md, the other files, then the subfolders.
+    *folders, name = relative.parts
+    return tuple((1, 0, natural_key(folder)) for folder in folders) + (
+        (0, 0 if name.casefold() == "readme.md" else 1, natural_key(name)),
+    )
+
+
+def exclusion_patterns(patterns: Iterable[str]) -> list[str]:
+    return [pattern.replace("\\", "/").strip("/") for pattern in patterns]
+
+
+def excluded(relative: PurePosixPath, patterns: Sequence[str]) -> bool:
+    # A pattern names a file or one of its folders, relative to the given directory.
+    candidates = [relative, *relative.parents[:-1]]
+    return any(
+        candidate.full_match(pattern)
+        for pattern in patterns
+        for candidate in candidates
+    )
+
+
+def read_toc(text: str) -> tuple[TocPart, ...]:
+    """`##` headings and the link targets under them, outside code, in reading order."""
+    parts: list[TocPart] = []
+    fence: str | None = None
+    for line in text.splitlines():
+        marker = _FENCE.match(line)
+        if fence is not None:
+            # A fence closes on the same character, at least as long, alone on its line.
+            if (
+                marker
+                and marker[1][0] == fence[0]
+                and len(marker[1]) >= len(fence)
+                and not marker[2].strip()
+            ):
+                fence = None
+            continue
+        if marker:
+            fence = marker[1]
+        elif heading := _PART.match(line):
+            parts.append(TocPart(heading[1], ()))
+        elif parts:
+            targets = tuple(
+                target
+                for image, target in _LINK.findall(_CODE_SPAN.sub("", line))
+                if not image
+            )
+            parts[-1] = parts[-1]._replace(targets=parts[-1].targets + targets)
+    return tuple(parts)
+
+
+def _key(text: str) -> PurePosixPath:
+    # Paths compare in NFC with `/`; files keep their on-disk spelling for reading.
+    return PurePosixPath(unicodedata.normalize("NFC", text.replace("\\", "/")))
+
+
+def _local_target(target: str) -> PurePosixPath | None:
+    """The path a link names under the table's folder, else None: web, anchor, outside."""
+    if _SCHEME.match(target) or target.startswith(("#", "/")):
+        return None
+    path = unquote(target.split("#", 1)[0].split("?", 1)[0])
+    if not path:
+        return None
+    normalized = posixpath.normpath(path.replace("\\", "/"))
+    if normalized == ".." or normalized.startswith("../"):
+        return None
+    return _key(normalized)
+
+
+def plan_order(path: Path, exclude: Sequence[str] = ()) -> OrderedMap:
+    """Resolve a Markdown table of contents against the files found under its folder."""
+    try:
+        text = path.read_text(encoding="utf-8").removeprefix("")
+    except (OSError, UnicodeDecodeError) as error:
+        raise RenderError(f"{path} : cannot read contents map ({error})") from error
+    toc = read_toc(text)
+    root = path.resolve().parent
+    patterns = exclusion_patterns(exclude)
+    found = {
+        _key(relative.as_posix()): PurePosixPath(relative.as_posix())
+        for relative in (
+            child.relative_to(root)
+            for child in root.rglob("*.md")
+            if child.is_file() and child.suffix == ".md"
+        )
+    }
+    printable = sorted(
+        (actual for key, actual in found.items() if not excluded(key, patterns)),
+        key=reading_order,
+    )
+    available = {_key(actual.as_posix()) for actual in printable}
+    intro_key = _key(path.resolve().name)
+    intro = found[intro_key] if intro_key in available else None
+    placed: set[PurePosixPath] = {intro_key}
+
+    def missing(target: str, what: str) -> RenderError:
+        return RenderError(
+            f"{path} : {target} ne désigne aucun {what} under {root} "
+            "(exact spelling and case required)"
+        )
+
+    groups: list[PlannedGroup] = []
+    for part in toc:
+        pages: list[PurePosixPath] = []
+        for target in part.targets:
+            key = _local_target(target)
+            if key is None:
+                continue
+            if key.suffix == ".md":
+                if key in available:
+                    matches = [found[key]]
+                elif excluded(key, patterns):
+                    # Listed for the map only: the exclusions keep it out of the PDF.
+                    continue
+                else:
+                    raise missing(target, "printable Markdown file")
+            elif (root / key).is_dir() or target.split("#", 1)[0].endswith("/"):
+                # A folder brings its pages not yet placed, in reading order.
+                inside = key == PurePosixPath(".")
+                if not inside and not any(key in other.parents for other in found):
+                    raise missing(target, "Markdown folder")
+                matches = [
+                    actual
+                    for actual in printable
+                    if inside or key in _key(actual.as_posix()).parents
+                ]
+            else:
+                continue
+            for actual in matches:
+                if _key(actual.as_posix()) not in placed:
+                    placed.add(_key(actual.as_posix()))
+                    pages.append(actual)
+        groups.append(PlannedGroup(part.title, tuple(pages)))
+    unplaced = tuple(
+        actual for actual in printable if _key(actual.as_posix()) not in placed
+    )
+    return OrderedMap(root, intro, tuple(groups), unplaced)

typoprint/cli.py

@@ -0,0 +1,242 @@
+"""Thin command-line adapter over the public library."""
+
+import argparse
+import json
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from typoprint.config import load_settings
+from typoprint.models import (
+    Chapter,
+    ConfigurationError,
+    Document,
+    Settings,
+    TypoprintError,
+)
+from typoprint.output import write_pdf
+from typoprint.planning import plan_files
+from typoprint.rendering import (
+    document_from_plan,
+    inspect_document,
+    render,
+    render_files,
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="typoprint",
+        description=f"Typoprint {version('typoprint')} — Markdown in. Beautiful PDFs out.",
+    )
+    parser.add_argument(
+        "paths", nargs="*", help="Markdown files or folders; '-' reads UTF-8 stdin"
+    )
+    parser.add_argument("--version", action="version", version=version("typoprint"))
+    parser.add_argument(
+        "-o", "--output", help="PDF destination; '-' writes binary PDF to stdout"
+    )
+    parser.add_argument(
+        "--order", type=Path, help="Markdown contents map; ## headings define parts"
+    )
+    parser.add_argument(
+        "-r", "--recursive", action="store_true", help="Include subfolders"
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="Exclude a relative path or directory (repeatable)",
+    )
+    parser.add_argument(
+        "--by-folder", action="store_true", help="Open a part for each folder"
+    )
+    parser.add_argument(
+        "--strict", action="store_true", help="With --order, refuse unplaced pages"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print JSON with input order and resolved settings, without a PDF",
+    )
+    config = parser.add_mutually_exclusive_group()
+    config.add_argument(
+        "--config",
+        type=Path,
+        help="Project TOML file (default: ./typoprint.toml if present)",
+    )
+    config.add_argument(
+        "--no-config", action="store_true", help="Ignore the project configuration"
+    )
+    parser.add_argument("--preset", help="Named preset in the selected configuration")
+    parser.add_argument(
+        "--template", help="editorial, report, or a directory containing template.typ"
+    )
+    for name in ("title", "subtitle", "author"):
+        parser.add_argument(
+            f"--{name}", help=f"Document {name}; overrides front matter"
+        )
+    parser.add_argument(
+        "--meta",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="Set title, subtitle, author, date, or version (repeatable)",
+    )
+    parser.add_argument(
+        "--lang", choices=("fr", "en"), help="Typography language (default: fr)"
+    )
+    parser.add_argument(
+        "--paper", choices=("a4", "us-letter"), help="Paper format (default: a4)"
+    )
+    for name in ("cover", "toc"):
+        parser.add_argument(
+            f"--{name}", action=argparse.BooleanOptionalAction, default=None
+        )
+    parser.add_argument(
+        "--toc-depth",
+        type=int,
+        choices=range(1, 7),
+        help="Contents levels (default: 2)",
+    )
+    parser.add_argument(
+        "--link-base", help="HTTP(S) folder URL publishing the current directory"
+    )
+    parser.add_argument(
+        "--font-path",
+        type=Path,
+        action="append",
+        help="Additional local font directory (repeatable)",
+    )
+    parser.add_argument(
+        "--template-option",
+        action="append",
+        default=[],
+        metavar="KEY=JSON",
+        help="Namespaced template option (repeatable)",
+    )
+    return parser
+
+
+def _settings(args: argparse.Namespace) -> Settings:
+    path = args.config
+    if path is None and not args.no_config and Path("typoprint.toml").is_file():
+        path = Path("typoprint.toml")
+    if args.preset is not None and (path is None or args.no_config):
+        raise ConfigurationError("--preset requires a project configuration")
+    base = load_settings(path, preset=args.preset) if path is not None else Settings()
+    data = {
+        key: value
+        for key, value in vars(args).items()
+        if key in Settings.model_fields and value is not None
+    }
+    for item in args.meta:
+        key, separator, value = item.partition("=")
+        if (
+            not separator
+            or key not in ("title", "subtitle", "author", "date", "version")
+            or not value.strip()
+        ):
+            raise ConfigurationError("--meta expects a supported KEY=VALUE")
+        if key in data:
+            raise ConfigurationError(f"Metadata field supplied twice: {key}")
+        data[key] = value
+    if args.font_path is not None:
+        data["font_paths"] = args.font_path
+    if args.template_option:
+        options = {}
+        for item in args.template_option:
+            key, separator, value = item.partition("=")
+            if not separator or not key or key in options:
+                raise ConfigurationError("--template-option expects a unique KEY=JSON")
+            try:
+                options[key] = json.loads(value)
+            except ValueError as error:
+                raise ConfigurationError(
+                    f"Invalid JSON for template option {key}"
+                ) from error
+        data["template_options"] = options
+    return base.with_overrides(Settings.model_validate(data))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        settings = _settings(args)
+        if "-" in args.paths:
+            if (
+                args.paths != ["-"]
+                or args.order is not None
+                or args.recursive
+                or args.exclude
+                or args.by_folder
+                or args.strict
+            ):
+                raise ConfigurationError(
+                    "stdin cannot be combined with file discovery options"
+                )
+            document = Document(
+                chapters=(
+                    Chapter(markdown=sys.stdin.buffer.read().decode("utf-8-sig")),
+                )
+            )
+            plan = None
+            default_name = "document"
+        else:
+            plan = plan_files(
+                args.paths,
+                order=args.order,
+                recursive=args.recursive,
+                exclude=args.exclude,
+                by_folder=args.by_folder,
+                strict=args.strict,
+                lang=settings.lang,
+            )
+            document = document_from_plan(plan)
+            first = Path(args.paths[0]) if args.paths else plan.root
+            default_name = first.name if first.is_dir() else first.stem
+        if args.dry_run:
+            resolved = inspect_document(document, settings)
+            resolved.pop("toc-depth", None)
+            resolved.pop("chapter-level", None)
+            print(
+                json.dumps(
+                    {
+                        "files": [
+                            {"name": chapter.name, "part": chapter.part}
+                            for chapter in document.chapters
+                        ],
+                        "settings": resolved,
+                        "warnings": list(plan.warnings) if plan is not None else [],
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+            return 0
+        output = args.output or f"{default_name}.pdf"
+        if output != "-" and plan is not None:
+            destination = Path(output).resolve()
+            if destination in {entry.path.resolve() for entry in plan.files}:
+                raise ConfigurationError("PDF output would overwrite an input file")
+        result = (
+            render(document, settings=settings)
+            if plan is None
+            else render_files(plan, settings=settings)
+        )
+        for warning in result.warnings:
+            print(f"Warning: {warning}", file=sys.stderr)
+        if output == "-":
+            sys.stdout.buffer.write(result.content)
+            sys.stdout.buffer.flush()
+        else:
+            destination = write_pdf(result, output)
+            print(destination, file=sys.stderr)
+        return 0
+    except (TypoprintError, ValidationError, OSError, UnicodeError) as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 2

typoprint/config.py

@@ -0,0 +1,45 @@
+"""Explicit project settings and named presets; no process-wide configuration."""
+
+import tomllib
+from pathlib import Path
+
+from pydantic import Field, ValidationError
+
+from typoprint.models import ConfigurationError, FrozenModel, Settings
+
+
+class ProjectConfig(FrozenModel):
+    defaults: Settings = Field(default_factory=Settings)
+    presets: dict[str, Settings] = Field(default_factory=dict)
+
+
+def _relative_paths(settings: Settings, directory: Path) -> Settings:
+    data = settings.model_dump(exclude_unset=True)
+    if settings.template not in ("editorial", "report"):
+        data["template"] = str((directory / settings.template).resolve())
+    if "font_paths" in data:
+        data["font_paths"] = tuple(
+            (directory / path).resolve() for path in settings.font_paths
+        )
+    return Settings.model_validate(data)
+
+
+def load_settings(path: str | Path, *, preset: str | None = None) -> Settings:
+    """Load defaults and one preset. Relative resources belong to the TOML file."""
+    source = Path(path).resolve()
+    try:
+        config = ProjectConfig.model_validate(
+            tomllib.loads(source.read_text(encoding="utf-8-sig"))
+        )
+    except (OSError, ValueError, ValidationError) as error:
+        raise ConfigurationError(
+            f"Cannot load settings from {source}: {error}"
+        ) from error
+    settings = _relative_paths(config.defaults, source.parent)
+    if preset is not None:
+        if preset not in config.presets:
+            raise ConfigurationError(f"Unknown preset: {preset}")
+        settings = settings.with_overrides(
+            _relative_paths(config.presets[preset], source.parent)
+        )
+    return settings

typoprint/models.py

@@ -0,0 +1,139 @@
+"""Public values for planning, configuration, and rendering."""
+
+from collections.abc import Callable
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
+
+Language = Literal["fr", "en"]
+Paper = Literal["a4", "us-letter"]
+METADATA_FIELDS = ("title", "subtitle", "author", "date", "version")
+
+
+class TypoprintError(ValueError):
+    """Base error safe to catch at a transport boundary."""
+
+
+class ConfigurationError(TypoprintError):
+    """Invalid settings, template bundle, or configuration file."""
+
+
+class RenderError(TypoprintError):
+    """Invalid inputs or a failed PDF compilation.
+
+    Compiler diagnostics may quote source text. Applications decide whether
+    to expose these details; the library never logs document contents.
+    """
+
+
+class RuleError(TypoprintError):
+    """A developer-supplied transformation or validation rule refused input."""
+
+
+class FrozenModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+def relative_name(value: str) -> str:
+    """A portable, non-traversing resource path, never a host filesystem path."""
+    if (
+        not isinstance(value, str)
+        or not value
+        or "\\" in value
+        or ":" in value
+        or "\x00" in value
+        or value.startswith("/")
+        or any(part in ("", ".", "..") for part in value.split("/"))
+    ):
+        raise ValueError("Expected a relative POSIX path without '.', '..', or a drive")
+    return PurePosixPath(value).as_posix()
+
+
+class Chapter(FrozenModel):
+    name: str = "document.md"
+    markdown: str
+    part: str | None = None
+
+    _name = field_validator("name")(relative_name)
+
+
+class Document(FrozenModel):
+    chapters: tuple[Chapter, ...] = Field(min_length=1)
+
+    @field_validator("chapters")
+    @classmethod
+    def unique_names(cls, chapters: tuple[Chapter, ...]) -> tuple[Chapter, ...]:
+        if len({chapter.name for chapter in chapters}) != len(chapters):
+            raise ValueError("Chapter names must be unique")
+        return chapters
+
+
+class Settings(FrozenModel):
+    """Rendering settings. Fields explicitly set survive layered merging.
+
+    None for an optional metadata field means inherit front matter. False
+    disables automatic cover/contents choices explicitly.
+    """
+
+    template: str = "editorial"
+    title: str | None = None
+    subtitle: str | None = None
+    author: str | None = None
+    date: str | None = None
+    version: str | None = None
+    lang: Language = "fr"
+    paper: Paper = "a4"
+    toc: bool | None = None
+    toc_depth: int = Field(default=2, ge=1, le=6)
+    cover: bool = False
+    link_base: str | None = None
+    font_paths: tuple[Path, ...] = ()
+    template_options: dict[str, JsonValue] = Field(default_factory=dict)
+
+    @field_validator("template")
+    @classmethod
+    def nonempty_template(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError(
+                "Template must name a built-in layout or a bundle directory"
+            )
+        return value
+
+    @field_validator("link_base")
+    @classmethod
+    def web_folder(cls, value: str | None) -> str | None:
+        if value is not None:
+            if not value.startswith(("https://", "http://")) or any(
+                char.isspace() for char in value
+            ):
+                raise ValueError("link_base must be an HTTP(S) folder URL")
+            return value.rstrip("/") + "/"
+        return None
+
+    def with_overrides(self, overrides: "Settings") -> "Settings":
+        """Merge only explicitly supplied fields; nested options replace as a unit."""
+        return Settings.model_validate(
+            self.model_dump(exclude_unset=True)
+            | overrides.model_dump(exclude_unset=True)
+        )
+
+
+class RenderResult(FrozenModel):
+    content: bytes
+    warnings: tuple[str, ...] = ()
+
+
+class PlannedFile(FrozenModel):
+    path: Path
+    part: str | None = None
+
+
+class PrintPlan(FrozenModel):
+    root: Path
+    files: tuple[PlannedFile, ...] = Field(min_length=1)
+    warnings: tuple[str, ...] = ()
+
+
+Transform = Callable[[str], str]
+Validator = Callable[[str], None]