proof-pdf 0.3.2__tar.gz → 0.3.3__tar.gz

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proof-pdf
-Version: 0.3.2
+Version: 0.3.3
 Summary: Hold print PDFs to PDF/X-4 and PDF/A: veraPDF, page boxes, geometry, ink and image resolution.
 Keywords: pdf,pdf/x-4,pdf/a,verapdf,prepress,print,preflight,ghostscript,lualatex
 Author-Email: Ilja Orlovs <ilja@release.art>
@@ -79,6 +79,12 @@ so nothing blocks the event loop.
 As a library the API is async: `await proof_pdf.core.verify_file(path, profile)` returns a `FileReport` of `Finding`s, and
 `await proof_pdf.core.verify_files(paths, profile, jobs=4)` returns one report per path in order. See `proof_pdf.models.Profile`.
 
+A job's config file works from Python too. `proof_pdf.load_profile(path=None, *, profile=None)` reads it like the CLI does (the nearest
+`proof-pdf.toml`, `PROOF_PDF_CONFIG`, `PROOF_PDF_PROFILE`) and returns a `LoadedConfig`: the `Profile`, the `exclude` globs, the `exempt`
+map, and `jobs`, `timeout` and the tool names. A file the CLI would reject raises `proof_pdf.ConfigError`. Pass those to
+`core.expand_targets` and `core.verify_files`, so the CLI and your code share one definition. `core.missing_tools(profile)` names the
+tools the profile needs (veraPDF for PDF/A, Ghostscript for colour) that are not on `PATH`, so a caller can fail early with one message.
+
 ### Proofing
 
 Beyond the standards, `verify` can hold a PDF to the rules a print job usually has. Missing glyphs and fonts are checked by

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/README.md

@@ -53,6 +53,12 @@ so nothing blocks the event loop.
 As a library the API is async: `await proof_pdf.core.verify_file(path, profile)` returns a `FileReport` of `Finding`s, and
 `await proof_pdf.core.verify_files(paths, profile, jobs=4)` returns one report per path in order. See `proof_pdf.models.Profile`.
 
+A job's config file works from Python too. `proof_pdf.load_profile(path=None, *, profile=None)` reads it like the CLI does (the nearest
+`proof-pdf.toml`, `PROOF_PDF_CONFIG`, `PROOF_PDF_PROFILE`) and returns a `LoadedConfig`: the `Profile`, the `exclude` globs, the `exempt`
+map, and `jobs`, `timeout` and the tool names. A file the CLI would reject raises `proof_pdf.ConfigError`. Pass those to
+`core.expand_targets` and `core.verify_files`, so the CLI and your code share one definition. `core.missing_tools(profile)` names the
+tools the profile needs (veraPDF for PDF/A, Ghostscript for colour) that are not on `PATH`, so a caller can fail early with one message.
+
 ### Proofing
 
 Beyond the standards, `verify` can hold a PDF to the rules a print job usually has. Missing glyphs and fonts are checked by

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/pyproject.toml

@@ -37,7 +37,7 @@ dependencies = [
     "pillow>=12.3.0",
     "typer>=0.27.3",
 ]
-version = "0.3.2"
+version = "0.3.3"
 
 [project.urls]
 Homepage = "https://github.com/release-art/proofpress"

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/src/proof_pdf/__init__.py

@@ -8,11 +8,16 @@ coverage, overprint, rich-black small text, stray RGB, effective image DPI).
 The entry point is :func:`proof_pdf.core.verify_file`; the CLI group lives in
 :mod:`proof_pdf.cli` and is the ``proof-pdf`` console script.
 
-Public API is the top-level modules: :mod:`~proof_pdf.core`, :mod:`~proof_pdf.models`, :mod:`~proof_pdf.inventory`,
-:mod:`~proof_pdf.preview`, :mod:`~proof_pdf.texlog` and :mod:`~proof_pdf.cli`. Everything under ``proof_pdf._internal``
-(the checks, the content and paint walks, the tool wrappers, the config reader) is private and may change at any time.
+Public API is the top-level modules (:mod:`~proof_pdf.core`, :mod:`~proof_pdf.models`, :mod:`~proof_pdf.inventory`,
+:mod:`~proof_pdf.preview`, :mod:`~proof_pdf.texlog`, :mod:`~proof_pdf.config`, :mod:`~proof_pdf.cli`) and the
+:func:`~proof_pdf.config.load_profile` re-export. Everything under ``proof_pdf._internal`` (the checks, the content and
+paint walks, the tool wrappers, the config reader) is private and may change at any time.
 
 The package takes PDF paths and nothing else. The finished-page geometry it checks
 against is a parameter (:class:`PageGeometry`) with no default, so a file from a
 printer is held to its own dimensions or the layer is skipped.
 """
+
+from .config import ConfigError, LoadedConfig, load_profile
+
+__all__ = ["ConfigError", "LoadedConfig", "load_profile"]

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/src/proof_pdf/cli.py

@@ -228,30 +228,7 @@ def verify_cmd(
         typer.echo("no PDFs to verify", err=True)
         raise typer.Exit(1)
 
-    profile = Profile(
-        flavour=flavour,
-        pdfa=pdfa,
-        pdfx=pdfx,
-        colour=colour,
-        geometry=_page_geometry(trim_mm, bleed_mm, tolerance_mm) if trim_mm else None,
-        max_tac=max_tac,
-        small_text_pt=small_text_pt,
-        min_dpi=min_dpi,
-        strict_cmyk=strict_cmyk,
-        k_only_text=k_only_text,
-        missing_glyphs=missing_glyphs,
-        min_text_pt=min_text_pt,
-        min_stroke_pt=min_stroke_pt,
-        safe_mm=safe_mm,
-        min_delta_l=min_delta_l,
-        proof_profile=proof_profile,
-        fonts=fonts,
-        allow_spots=tuple(allow_spot) if allow_spot else None,
-        output_condition=output_condition,
-        require_bleed=require_bleed,
-        uniform_pages=uniform_pages,
-        pages_multiple_of=pages_multiple_of,
-    )
+    profile = build_profile(locals())
     reports = asyncio.run(
         core.verify_files(
             targets,
@@ -402,6 +379,35 @@ def _parse_exemptions(specs: list[str]) -> dict[str, str]:
     return exemptions
 
 
+def build_profile(options: typing.Mapping[str, typing.Any]) -> Profile:
+    """The :class:`Profile` the ``verify`` options (by parameter name) describe; also used by ``load_profile``."""
+    o = options
+    return Profile(
+        flavour=o["flavour"],
+        pdfa=o["pdfa"],
+        pdfx=o["pdfx"],
+        colour=o["colour"],
+        geometry=_page_geometry(o["trim_mm"], o["bleed_mm"], o["tolerance_mm"]) if o["trim_mm"] else None,
+        max_tac=o["max_tac"],
+        small_text_pt=o["small_text_pt"],
+        min_dpi=o["min_dpi"],
+        strict_cmyk=o["strict_cmyk"],
+        k_only_text=o["k_only_text"],
+        missing_glyphs=o["missing_glyphs"],
+        min_text_pt=o["min_text_pt"],
+        min_stroke_pt=o["min_stroke_pt"],
+        safe_mm=o["safe_mm"],
+        min_delta_l=o["min_delta_l"],
+        proof_profile=o["proof_profile"],
+        fonts=o["fonts"],
+        allow_spots=tuple(o["allow_spot"]) if o["allow_spot"] else None,
+        output_condition=o["output_condition"],
+        require_bleed=o["require_bleed"],
+        uniform_pages=o["uniform_pages"],
+        pages_multiple_of=o["pages_multiple_of"],
+    )
+
+
 def _page_geometry(trim_mm: str, bleed_mm: float, tolerance_mm: float) -> PageGeometry:
     """Parse ``--trim-mm WxH`` into a :class:`PageGeometry`."""
     parts = trim_mm.lower().replace("*", "x").split("x")

proof_pdf-0.3.3/src/proof_pdf/config.py

@@ -0,0 +1,79 @@
+"""Read a ``proof-pdf.toml`` the way the CLI does, for library callers.
+
+One file can then carry a printer's numbers for both ``proof-pdf verify`` and Python code that calls
+:func:`proof_pdf.core.verify_files`.
+"""
+
+import dataclasses
+import os
+import pathlib
+import typing
+
+import typer
+import typer.main
+
+from ._internal import config as _config
+from ._internal.config import ConfigError
+from .models import Profile
+
+__all__ = ["ConfigError", "LoadedConfig", "load_profile"]
+
+
+@dataclasses.dataclass(frozen=True)
+class LoadedConfig:
+    """What ``verify`` would run with: the checks and the file selection, from the file plus the option defaults."""
+
+    profile: Profile
+    exclude: tuple[str, ...]  # globs for :func:`proof_pdf.core.expand_targets`
+    exempt: dict[str, str]  # glob -> reason, for ``verify_files(exemptions=...)``
+    jobs: int
+    timeout: float
+    verapdf_bin: str
+    gs_bin: str
+    path: pathlib.Path | None  # the file that was read; None when none was found
+
+
+def load_profile(
+    path: pathlib.Path | None = None, *, profile: str | None = None, command: str = "verify"
+) -> LoadedConfig:
+    """The settings the CLI's *command* would use, read from the config file.
+
+    *path* defaults to ``PROOF_PDF_CONFIG``, else the nearest ``proof-pdf.toml`` (or ``[tool.proof-pdf]`` in
+    ``pyproject.toml``) from the working directory; *profile* defaults to ``PROOF_PDF_PROFILE``. With no file, every
+    option has its CLI default. Raises :class:`ConfigError` for an unreadable file, an unknown key or table, a profile
+    the file lacks, or a value the CLI would reject.
+    """
+    from . import cli  # deferred: the CLI framework is only loaded when a caller wants its behaviour
+
+    if command != "verify":
+        raise ConfigError(f"only the verify command makes a profile, not {command!r}")
+    path = path or (pathlib.Path(env) if (env := os.environ.get("PROOF_PDF_CONFIG")) else None)
+    profile = profile or os.environ.get("PROOF_PDF_PROFILE") or None
+    path = path or _config.find_config(pathlib.Path.cwd())
+    if path is None and profile:
+        raise ConfigError("a profile needs a config file, and none was found")
+    commands = _click_commands()
+    defaults = _config.default_map(path, profile, commands) if path else {}
+    try:
+        with commands[command].make_context(command, [], default_map=defaults.get(command, {})) as ctx:
+            values = ctx.params
+        built = cli.build_profile(values)
+        exempt = cli._parse_exemptions(values["exempt"] or [])
+    except typer.BadParameter as exc:  # a bad value is the file's fault, not a CLI usage error
+        raise ConfigError(f"{path or 'defaults'}: {exc.format_message()}") from exc
+    return LoadedConfig(
+        profile=built,
+        exclude=tuple(values["exclude"] or ()),
+        exempt=exempt,
+        jobs=values["jobs"],
+        timeout=values["timeout"],
+        verapdf_bin=values["verapdf_bin"],
+        gs_bin=values["gs_bin"],
+        path=path,
+    )
+
+
+def _click_commands() -> dict[str, typing.Any]:
+    from . import cli
+
+    return dict(getattr(typer.main.get_command(cli.pdf_app), "commands", {}))

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/src/proof_pdf/core.py

@@ -56,6 +56,16 @@ async def verify_file(
     return report
 
 
+def missing_tools(profile: Profile, *, verapdf_bin: str = "verapdf", gs_bin: str = "gs") -> list[str]:
+    """The external tools *profile* needs that cannot be found, by the executable names given (empty if all are there).
+
+    veraPDF is needed for the PDF/A layer and Ghostscript for the colour layer (total ink). :func:`verify_file` reports
+    a missing tool as a failing finding; this lets a caller stop before a long run with one message of its own.
+    """
+    needed = ((verapdf_bin, profile.pdfa, verapdf.available), (gs_bin, profile.colour, colour.gs_available))
+    return [binary for binary, wanted, found in needed if wanted and not found(binary)]
+
+
 def exemption(path: pathlib.PurePath, exemptions: collections.abc.Mapping[str, str]) -> str | None:
     """The reason *path* was declared exempt, or ``None``.
 

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/tests/test_proof_pdf/test_core.py

@@ -259,3 +259,18 @@ class TestFileReport:
     )
     def test_finding_label(self, page, expected):
         assert Finding("x", Severity.ERROR, "hello", page).label() == expected
+
+
+class TestMissingTools:
+    def test_names_only_what_the_profile_needs_and_cannot_find(self, mocker):
+        mocker.patch.object(verapdf, "available", return_value=False)
+        mocker.patch.object(colour, "gs_available", return_value=False)
+        assert core.missing_tools(Profile(), verapdf_bin="vera", gs_bin="ghost") == ["vera", "ghost"]
+        assert core.missing_tools(Profile(pdfa=False)) == ["gs"]
+        assert core.missing_tools(Profile(colour=False)) == ["verapdf"]
+        assert core.missing_tools(Profile(pdfa=False, colour=False)) == []
+
+    def test_a_tool_that_is_there_is_not_reported(self, mocker):
+        mocker.patch.object(verapdf, "available", return_value=True)
+        mocker.patch.object(colour, "gs_available", return_value=True)
+        assert core.missing_tools(Profile()) == []

proof_pdf-0.3.3/tests/test_proof_pdf/test_load_profile.py

@@ -0,0 +1,90 @@
+"""``proof_pdf.load_profile``: the CLI's config reading, for library callers."""
+
+import pytest
+
+import proof_pdf
+from proof_pdf.models import PageGeometry, Profile
+
+CARD = """
+[verify]
+trim-mm = "105x148"
+bleed-mm = 3
+exclude = ["res/**", "_views/**", "*_preview.pdf"]
+safe-mm = 3
+require-bleed = true
+
+[verify.exempt]
+"manual.pdf" = "internal"
+
+[profiles.deluxe.verify]
+bleed-mm = 5
+"""
+
+
+@pytest.fixture
+def card(tmp_path, monkeypatch):
+    monkeypatch.delenv("PROOF_PDF_CONFIG", raising=False)
+    monkeypatch.delenv("PROOF_PDF_PROFILE", raising=False)
+    path = tmp_path / "proof-pdf.toml"
+    path.write_text(CARD)
+    return path
+
+
+def test_the_file_gives_the_profile_the_globs_and_the_exemptions(card):
+    loaded = proof_pdf.load_profile(card)
+    assert loaded.profile.geometry == PageGeometry(trim_w_mm=105, trim_h_mm=148, bleed_mm=3)
+    assert loaded.profile.safe_mm == 3 and loaded.profile.require_bleed is True
+    assert loaded.exclude == ("res/**", "_views/**", "*_preview.pdf")
+    assert loaded.exempt == {"manual.pdf": "internal"} and loaded.path == card
+
+
+def test_a_named_profile_overrides_the_base(card):
+    assert proof_pdf.load_profile(card, profile="deluxe").profile.geometry.bleed_mm == 5  # type: ignore[union-attr]
+
+
+def test_the_nearest_file_is_found_from_the_working_directory(card, monkeypatch):
+    monkeypatch.chdir(card.parent)
+    assert proof_pdf.load_profile().path == card
+
+
+def test_the_environment_names_the_file_and_profile(card, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path / "..")
+    monkeypatch.setenv("PROOF_PDF_CONFIG", str(card))
+    monkeypatch.setenv("PROOF_PDF_PROFILE", "deluxe")
+    assert proof_pdf.load_profile().profile.geometry.bleed_mm == 5  # type: ignore[union-attr]
+
+
+def test_no_file_means_the_cli_defaults(tmp_path, monkeypatch):
+    monkeypatch.delenv("PROOF_PDF_CONFIG", raising=False)
+    monkeypatch.chdir(tmp_path)
+    loaded = proof_pdf.load_profile()
+    assert loaded.profile == Profile() and loaded.path is None and loaded.exclude == () and loaded.exempt == {}
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        pytest.param("[verify]\nnot-an-option = 1\n", id="unknown-key"),
+        pytest.param('[verify]\ntrim-mm = "wide"\n', id="bad-trim"),
+        pytest.param('[verify]\nmin-dpi = "high"\n', id="bad-type"),
+        pytest.param("[nope]\nx = 1\n", id="unknown-table"),
+    ],
+)
+def test_a_file_the_cli_would_reject_is_a_config_error(tmp_path, monkeypatch, text):
+    monkeypatch.delenv("PROOF_PDF_CONFIG", raising=False)
+    path = tmp_path / "proof-pdf.toml"
+    path.write_text(text)
+    with pytest.raises(proof_pdf.ConfigError):
+        proof_pdf.load_profile(path)
+
+
+def test_a_profile_without_a_file_is_a_config_error(tmp_path, monkeypatch):
+    monkeypatch.delenv("PROOF_PDF_CONFIG", raising=False)
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(proof_pdf.ConfigError):
+        proof_pdf.load_profile(profile="deluxe")
+
+
+def test_only_verify_makes_a_profile():
+    with pytest.raises(proof_pdf.ConfigError):
+        proof_pdf.load_profile(command="inspect")

{proof_pdf-0.3.2 → proof_pdf-0.3.3}/tests/test_proof_pdf/test_public_api.py

@@ -4,7 +4,7 @@ import pkgutil
 
 import proof_pdf
 
-PUBLIC = {"cli", "core", "inventory", "models", "preview", "texlog"}
+PUBLIC = {"cli", "config", "core", "inventory", "models", "preview", "texlog"}
 
 
 def test_only_the_public_modules_sit_at_the_top_level():