zallery 0.0.1__py3-none-any.whl

zallery/__init__.py

@@ -0,0 +1,11 @@
+"""Build a light-and-dark example gallery for Zensical docs from jupytext scripts.
+
+Examples are percent-format `.py` files executed once in an ipykernel; each
+displayed matplotlib figure is rendered for both themes from that single run
+(see `zallery.theme`). [`build_gallery`][zallery.build_gallery] runs the whole
+pipeline: discover, cache, execute, render, index.
+"""
+
+from zallery.pipeline import build_gallery
+
+__all__ = ["build_gallery"]

zallery/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m zallery` alongside the `zallery` console script."""
+
+from zallery.cli import main
+
+raise SystemExit(main())

zallery/_types.py

@@ -0,0 +1,43 @@
+"""Shared dataclasses for the gallery builder."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ExampleSpec:
+    """A single discovered example file.
+
+    Attributes
+    ----------
+    source : pathlib.Path
+        Absolute path to the percent-format `.py` file.
+    base_name : str
+        Output stem used for the rendered Markdown, downloads, and cache entry.
+        Derived from `source.stem` with any leading numeric ordering prefix
+        (e.g. `01_`) stripped, so the source filename can control card order
+        without leaking the prefix into URLs.
+    section : str
+        Section folder name (e.g. `"io"`).
+    section_intro : str
+        Contents of the sibling `_section.md` file, or empty string if none.
+    """
+
+    source: Path
+    base_name: str
+    section: str
+    section_intro: str
+
+
+@dataclass(frozen=True)
+class RenderedExample:
+    """An example after the renderer has produced its artifacts."""
+
+    spec: ExampleSpec
+    title: str
+    summary: str
+    md_path: Path
+    thumbnail_light: Path | None
+    thumbnail_dark: Path | None

zallery/cache.py

@@ -0,0 +1,58 @@
+"""Cache key + cache directory helpers for the gallery builder."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from zallery._types import ExampleSpec
+
+
+def cache_key(
+    spec: ExampleSpec,
+    *,
+    deps_fingerprint: str,
+    python_version: str,
+) -> str:
+    """Compute a deterministic cache key for one example.
+
+    Parameters
+    ----------
+    spec : ExampleSpec
+        The example; its source file content is part of the key.
+    deps_fingerprint : str
+        Text identifying everything else that shapes the render (lockfile,
+        builder sources, configuration).
+    python_version : str
+        Version of the Python interpreter the example runs under.
+
+    Returns
+    -------
+    str
+        SHA-256 hex digest of the three inputs.
+    """
+    digest = hashlib.sha256()
+    digest.update(spec.source.read_bytes())
+    digest.update(b"\x00")
+    digest.update(deps_fingerprint.encode("utf-8"))
+    digest.update(b"\x00")
+    digest.update(python_version.encode("utf-8"))
+    return digest.hexdigest()
+
+
+def cache_dir(root: Path, key: str) -> Path:
+    """Return the cache directory for `key` rooted at `root`.
+
+    Parameters
+    ----------
+    root : pathlib.Path
+        Cache root directory.
+    key : str
+        Cache key of one example, see `cache_key`.
+
+    Returns
+    -------
+    pathlib.Path
+        Directory holding that example's cached artifacts.
+    """
+    return root / key

zallery/cli.py

@@ -0,0 +1,96 @@
+"""Command line interface: `zallery [--no-run] [--no-cache] [EXAMPLE ...]`.
+
+Run from anywhere inside a project whose `pyproject.toml` has a `[tool.zallery]`
+table (see `zallery.config`). With no arguments every example is executed; name
+example scripts to run only those. The whole gallery is rendered either way: the
+examples not run are restored from cache if present, or rendered without outputs
+(code and Markdown only).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from zallery.config import ConfigError, deps_fingerprint, load_config
+from zallery.pipeline import build_gallery
+
+BINDER_REF_ENV = "ZALLERY_BINDER_REF"
+"""Environment variable giving the git ref stamped into Binder URLs (default `main`)."""
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Build the gallery of the project the working directory belongs to.
+
+    Parameters
+    ----------
+    argv : Sequence[str], optional
+        Command line arguments. If not provided, `sys.argv[1:]` is used.
+
+    Returns
+    -------
+    int
+        Exit status: 0 on success, 1 when the examples directory is missing or an
+        argument names no example, 2 when no configuration is found.
+    """
+    parser = argparse.ArgumentParser(prog="zallery", description=__doc__)
+    parser.add_argument(
+        "examples",
+        nargs="*",
+        type=Path,
+        help=(
+            "Example scripts to run. The whole gallery is still rendered; unnamed "
+            "examples are taken from cache if present, or rendered without outputs. "
+            "If not provided, all examples are run."
+        ),
+    )
+    parser.add_argument(
+        "--no-run",
+        action="store_true",
+        help=(
+            "Run no example at all: every page is taken from cache if present, or "
+            "rendered without outputs. Cannot be combined with example paths."
+        ),
+    )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help=(
+            "Execute the selected examples even if a cached result exists, and "
+            "replace it. Examples not selected still come from cache."
+        ),
+    )
+    args = parser.parse_args(argv)
+    if args.no_run and args.examples:
+        parser.error("--no-run cannot be combined with example paths.")
+
+    try:
+        config = load_config(Path.cwd())
+    except ConfigError as exc:
+        print(f"zallery: {exc}", file=sys.stderr)
+        return 2
+    if not config.examples.is_dir():
+        print(f"No examples directory at {config.examples}", file=sys.stderr)
+        return 1
+
+    try:
+        build_gallery(
+            examples_root=config.examples,
+            built_dir=config.built,
+            cache_root=config.cache,
+            deps_fingerprint=deps_fingerprint(config),
+            repo_root=config.root,
+            binder_repo=config.binder_repo,
+            binder_ref=os.environ.get(BINDER_REF_ENV, "main"),
+            only=[] if args.no_run else (args.examples or None),
+            use_cache=not args.no_cache,
+            hook_module=config.hook,
+            hook_root=config.root,
+        )
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    return 0

zallery/config.py

@@ -0,0 +1,204 @@
+"""Project configuration, read from the `[tool.zallery]` table of `pyproject.toml`.
+
+The table is looked up from the working directory upwards, so `zallery` can run
+from anywhere inside the project. Relative paths in it are resolved against the
+directory holding that `pyproject.toml`, which is also the project root the kernel
+gets on its `sys.path` so the theme hook module imports.
+
+Keys (all optional):
+
+- `examples`: directory of example sections, default `docs/examples`.
+- `built`: where rendered pages go, default `<examples>/_built`.
+- `cache`: execution/render cache directory, default `.gallery-cache`.
+- `binder_repo`: `owner/repo` slug for the Binder launch buttons; no buttons if unset.
+- `hook`: dotted name of the module defining `gallery_retheme(fig, theme)`.
+- `fingerprint`: files whose content invalidates the cache when it changes,
+  default `["uv.lock"]`. The `zallery` sources, the hook module and the table
+  itself are always part of the fingerprint.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+import zallery
+
+_TABLE = "zallery"
+"""Name of the table under `[tool]`."""
+
+_KNOWN_KEYS = frozenset(
+    {"examples", "built", "cache", "binder_repo", "hook", "fingerprint"}
+)
+"""Keys the table may contain; anything else is a typo and rejected."""
+
+
+class ConfigError(ValueError):
+    """Raised when no usable `[tool.zallery]` table is found or it is malformed."""
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved project configuration.
+
+    Attributes
+    ----------
+    root : pathlib.Path
+        Directory holding the `pyproject.toml` the table was read from.
+    examples : pathlib.Path
+        Directory of example sections.
+    built : pathlib.Path
+        Directory rendered pages and assets are written to.
+    cache : pathlib.Path
+        Execution/render cache directory.
+    binder_repo : str, optional
+        `owner/repo` slug for Binder launch buttons. If not provided, no buttons.
+    hook : str, optional
+        Dotted name of the project's theme hook module. If not provided, only the
+        built-in swap runs.
+    fingerprint_files : tuple[pathlib.Path, ...]
+        Files whose content is part of the cache fingerprint.
+    """
+
+    root: Path
+    examples: Path
+    built: Path
+    cache: Path
+    binder_repo: str | None
+    hook: str | None
+    fingerprint_files: tuple[Path, ...]
+
+    @property
+    def hook_file(self) -> Path | None:
+        """Source file of the hook module under `root`, if the module is configured.
+
+        Returns
+        -------
+        pathlib.Path or None
+            `<root>/a/b.py` or `<root>/a/b/__init__.py` for `hook = "a.b"`, whichever
+            exists, else the module path with `.py`; `None` without a hook.
+        """
+        if self.hook is None:
+            return None
+        base = self.root.joinpath(*self.hook.split("."))
+        package_init = base / "__init__.py"
+        return package_init if package_init.is_file() else base.with_suffix(".py")
+
+
+def find_pyproject(start: Path) -> Path | None:
+    """Return the nearest `pyproject.toml` with a `[tool.zallery]` table.
+
+    Parameters
+    ----------
+    start : pathlib.Path
+        Directory to search from; its parents are searched in turn.
+
+    Returns
+    -------
+    pathlib.Path or None
+        The file, or `None` if no ancestor holds one with the table.
+    """
+    for directory in (start.resolve(), *start.resolve().parents):
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            with candidate.open("rb") as handle:
+                data = tomllib.load(handle)
+            if _TABLE in data.get("tool", {}):
+                return candidate
+    return None
+
+
+def load_config(start: Path) -> Config:
+    """Load the configuration that applies to `start`.
+
+    Parameters
+    ----------
+    start : pathlib.Path
+        Directory to search from, typically the working directory.
+
+    Returns
+    -------
+    Config
+        The resolved configuration, with relative paths made absolute under the
+        project root.
+
+    Raises
+    ------
+    ConfigError
+        If no `pyproject.toml` with a `[tool.zallery]` table is found, or the table
+        has unknown keys.
+    """
+    pyproject = find_pyproject(start)
+    if pyproject is None:
+        raise ConfigError(
+            f"No pyproject.toml with a [tool.zallery] table found in {start} or its "
+            "parents."
+        )
+    with pyproject.open("rb") as handle:
+        table = tomllib.load(handle)["tool"][_TABLE]
+    unknown = sorted(set(table) - _KNOWN_KEYS)
+    if unknown:
+        raise ConfigError(
+            f"Unknown keys in [tool.zallery] of {pyproject}: {', '.join(unknown)}. "
+            f"Known keys: {', '.join(sorted(_KNOWN_KEYS))}."
+        )
+
+    root = pyproject.parent
+    examples = root / table.get("examples", "docs/examples")
+    return Config(
+        root=root,
+        examples=examples,
+        built=root / table["built"] if "built" in table else examples / "_built",
+        cache=root / table.get("cache", ".gallery-cache"),
+        binder_repo=table.get("binder_repo"),
+        hook=table.get("hook"),
+        fingerprint_files=tuple(
+            root / p for p in table.get("fingerprint", ["uv.lock"])
+        ),
+    )
+
+
+def deps_fingerprint(config: Config) -> str:
+    """Return a string identifying everything that shapes an example's render.
+
+    Any change to it makes every cached example miss: the configured fingerprint
+    files (the lockfile by default), the `zallery` sources, the hook module, and
+    the configuration values themselves. The Binder ref is deliberately not part of
+    it, so renders are reused across branches.
+
+    Parameters
+    ----------
+    config : Config
+        The project configuration.
+
+    Returns
+    -------
+    str
+        Concatenated, locale-independent text of all the inputs.
+    """
+    parts: list[str] = [
+        json.dumps(
+            {
+                "examples": str(config.examples.relative_to(config.root)),
+                "built": str(config.built.relative_to(config.root)),
+                "binder_repo": config.binder_repo,
+                "hook": config.hook,
+            },
+            sort_keys=True,
+        )
+    ]
+    # Read everything as UTF-8 so the text does not depend on the platform's locale.
+    for path in config.fingerprint_files:
+        if path.is_file():
+            parts.append(f"\n# {path.relative_to(config.root)}\n")
+            parts.append(path.read_text(encoding="utf-8"))
+    for path in sorted(Path(zallery.__file__).resolve().parent.glob("*.py")):
+        parts.append(f"\n# zallery/{path.name}\n")
+        parts.append(path.read_text(encoding="utf-8"))
+    hook_file = config.hook_file
+    if hook_file is not None and hook_file.is_file():
+        parts.append(f"\n# {hook_file.relative_to(config.root)}\n")
+        parts.append(hook_file.read_text(encoding="utf-8"))
+    return "".join(parts)

zallery/discover.py

@@ -0,0 +1,54 @@
+"""Discover example source files under the examples root."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from zallery._types import ExampleSpec
+
+# Strip leading "01_", "02_" etc. from section directory names and example file
+# names so the built output uses clean names ("io", "decomposition",
+# "pca_single_recording") while the source paths can be prefixed for explicit
+# ordering.
+_NUMERIC_PREFIX_RE = re.compile(r"^\d+_")
+
+
+def discover(root: Path) -> list[ExampleSpec]:
+    """Return one example spec per example file.
+
+    Parameters
+    ----------
+    root : pathlib.Path
+        Examples root; each subdirectory not starting with `_` is a section.
+
+    Returns
+    -------
+    list[ExampleSpec]
+        One spec per `.py` file not starting with `_`, sorted by section folder
+        then file name. Empty if `root` is not a directory.
+    """
+    specs: list[ExampleSpec] = []
+    if not root.is_dir():
+        return specs
+
+    for section_dir in sorted(
+        p for p in root.iterdir() if p.is_dir() and not p.name.startswith("_")
+    ):
+        intro_path = section_dir / "_section.md"
+        intro = intro_path.read_text(encoding="utf-8") if intro_path.is_file() else ""
+        section_name = _NUMERIC_PREFIX_RE.sub("", section_dir.name)
+
+        for source in sorted(section_dir.glob("*.py")):
+            if source.name.startswith("_"):
+                continue
+            specs.append(
+                ExampleSpec(
+                    source=source,
+                    base_name=_NUMERIC_PREFIX_RE.sub("", source.stem),
+                    section=section_name,
+                    section_intro=intro,
+                )
+            )
+
+    return specs