backstamp 0.0.1__tar.gz

backstamp-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Joschua Geuter
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

backstamp-0.0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: backstamp
+Version: 0.0.1
+Summary: Record how a figure was made inside the figure file itself: commit, calling function, parameters.
+Author: Joschua Geuter
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/Joschua21/backstamp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: pypdf>=3
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# backstamp
+
+A saved figure says nothing about the code that made it. Weeks later, finding the commit,
+the function and the parameters behind a plot means searching old scripts, or making it
+again.
+
+backstamp writes that record into the figure file when it is saved, and reads it back.
+
+## Install
+
+```
+pip install backstamp
+```
+
+Python 3.9 or later. Installs matplotlib and pypdf.
+
+## Save
+
+```python
+import backstamp
+
+def plot_accuracy(trials, window=50):
+    fig, ax = plt.subplots()
+    ...
+    backstamp.save(fig, "accuracy", fig_dir="figures/")
+```
+
+This writes `figures/accuracy.pdf` with a record of:
+
+- the commit of the repository the calling code lives in, marked `-dirty` when it has
+  uncommitted changes
+- the installed version of the calling package
+- the function that called `save`: its module, file, line, and the functions enclosing it
+- that function's parameters. Data objects are stored as their type and shape
+  (`<DataFrame 50x2>`, `<ndarray (3, 4) float64>`), not their values.
+- when the figure was made
+
+Parameters are recorded with the values they have when `save` runs, so a parameter
+reassigned inside the function is recorded with its new value.
+
+The record is JSON in the PDF's `Subject` field, with a one-line summary in `Title`.
+
+## Read
+
+```python
+from backstamp.metadata import read_figure_metadata
+
+read_figure_metadata("figures/accuracy.pdf")
+# {"commit": "a1b2c3d", "function": "plot_accuracy",
+#  "params": {"trials": "<DataFrame 50x2>", "window": 50}, ...}
+```
+
+Returns `{}` for a figure without a record, a file that is not a readable PDF, or a missing
+file.
+
+## Wrapping `save`
+
+The record names the nearest calling function outside backstamp. A function that wraps
+`save` passes its own module, so the record names the plotting function instead of the
+wrapper:
+
+```python
+backstamp.save(fig, name, fig_dir=out_dir, skip_modules=(__name__,))
+```
+
+## Licence
+
+BSD-3-Clause

backstamp-0.0.1/README.md

@@ -0,0 +1,68 @@
+# backstamp
+
+A saved figure says nothing about the code that made it. Weeks later, finding the commit,
+the function and the parameters behind a plot means searching old scripts, or making it
+again.
+
+backstamp writes that record into the figure file when it is saved, and reads it back.
+
+## Install
+
+```
+pip install backstamp
+```
+
+Python 3.9 or later. Installs matplotlib and pypdf.
+
+## Save
+
+```python
+import backstamp
+
+def plot_accuracy(trials, window=50):
+    fig, ax = plt.subplots()
+    ...
+    backstamp.save(fig, "accuracy", fig_dir="figures/")
+```
+
+This writes `figures/accuracy.pdf` with a record of:
+
+- the commit of the repository the calling code lives in, marked `-dirty` when it has
+  uncommitted changes
+- the installed version of the calling package
+- the function that called `save`: its module, file, line, and the functions enclosing it
+- that function's parameters. Data objects are stored as their type and shape
+  (`<DataFrame 50x2>`, `<ndarray (3, 4) float64>`), not their values.
+- when the figure was made
+
+Parameters are recorded with the values they have when `save` runs, so a parameter
+reassigned inside the function is recorded with its new value.
+
+The record is JSON in the PDF's `Subject` field, with a one-line summary in `Title`.
+
+## Read
+
+```python
+from backstamp.metadata import read_figure_metadata
+
+read_figure_metadata("figures/accuracy.pdf")
+# {"commit": "a1b2c3d", "function": "plot_accuracy",
+#  "params": {"trials": "<DataFrame 50x2>", "window": 50}, ...}
+```
+
+Returns `{}` for a figure without a record, a file that is not a readable PDF, or a missing
+file.
+
+## Wrapping `save`
+
+The record names the nearest calling function outside backstamp. A function that wraps
+`save` passes its own module, so the record names the plotting function instead of the
+wrapper:
+
+```python
+backstamp.save(fig, name, fig_dir=out_dir, skip_modules=(__name__,))
+```
+
+## Licence
+
+BSD-3-Clause

backstamp-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "backstamp"
+dynamic = ["version"]
+description = "Record how a figure was made inside the figure file itself: commit, calling function, parameters."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Joschua Geuter" }]
+requires-python = ">=3.9"
+dependencies = ["matplotlib", "pypdf>=3"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: Matplotlib",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Repository = "https://github.com/Joschua21/backstamp"
+
+[tool.setuptools.dynamic]
+version = { attr = "backstamp.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

backstamp-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

backstamp-0.0.1/src/backstamp/__init__.py

@@ -0,0 +1,11 @@
+"""Record how a figure was made inside the figure file itself.
+
+- `save`: write a figure as PDF with its record embedded.
+- `metadata.read_figure_metadata`: read the record back.
+- `provenance`: the record itself -- commit, version, and the call that made the figure.
+"""
+from .save import save
+
+__version__ = "0.0.1"
+
+__all__ = ["save", "__version__"]

backstamp-0.0.1/src/backstamp/metadata.py

@@ -0,0 +1,217 @@
+"""Provenance embedded in the saved PDF itself -- no sidecar, still one file.
+
+Open a figure months later and recover what it shows and how it was made, from the file
+you are already looking at. A sidecar JSON solves the same problem right up until
+someone emails the PDF on its own.
+
+**The constraint that shapes this** (verified against the matplotlib PDF backend): the
+PDF info dictionary accepts only ``Title``, ``Author``, ``Subject``, ``Keywords``,
+``Creator``, ``Producer``, ``CreationDate``, ``ModDate`` and ``Trapped``. Any other key
+is dropped with a ``UserWarning``, and ``CreationDate`` must be a real ``datetime``. So
+the structured record goes into ``Subject`` as JSON, with a human-readable one-liner in
+``Title`` -- the field a PDF viewer shows without being asked.
+
+Reading uses `pypdf`. matplotlib writes the info dictionary as an uncompressed literal
+string, so a stdlib parser is the fallback when pypdf cannot open a file.
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+
+from .provenance import provenance as _provenance
+
+# A PDF string value has to stay a reasonable size; beyond this the record is truncated
+# rather than risking an unwieldy info dictionary.
+MAX_BLOB = 3000
+
+# The keys matplotlib will accept. Anything else is silently discarded, so filter here
+# rather than letting a warning appear at every save.
+_ALLOWED = frozenset({
+    "Title", "Author", "Subject", "Keywords", "Creator", "Producer",
+    "CreationDate", "ModDate", "Trapped",
+})
+
+
+def summarize_scope(save_name: str, subjids=None, dates=None) -> str:
+    """The one-line human summary that lands in ``Title``.
+
+    e.g. ``"accuracy sub-040,045,066 20251124-20260203"``.
+    """
+    parts = [save_name] if save_name else []
+    subj = _as_list(subjids)
+    date = _as_list(dates)
+    if subj:
+        parts.append("sub-" + ",".join(_fmt_subj(s) for s in subj))
+    if date:
+        dates_sorted = sorted(str(d) for d in date)
+        parts.append(
+            dates_sorted[0] if len(dates_sorted) == 1
+            else f"{dates_sorted[0]}-{dates_sorted[-1]}"
+        )
+    return " ".join(parts)
+
+
+def _as_list(value):
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return list(value)
+    return [value]
+
+
+def _fmt_subj(value):
+    try:
+        return f"{int(value):03d}"
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def build_pdf_metadata(save_name: str, *, subjids=None, dates=None,
+                       provenance: dict | None = None, call: dict | None = None,
+                       extra: dict | None = None) -> dict:
+    """The matplotlib ``metadata=`` dict for one figure.
+
+    ``provenance`` overrides capture entirely; otherwise a record is built from ``call``
+    (a `capture_call` result) or, failing that, captured here.
+    """
+    record = provenance if provenance is not None else _provenance(call=call)
+    if subjids is not None:
+        record.setdefault("subjids", [_fmt_subj(s) for s in _as_list(subjids)])
+    if dates is not None:
+        record.setdefault("dates", [str(d) for d in _as_list(dates)])
+    if extra:
+        record.update(extra)
+
+    blob = _dump(record)
+    creator = "hypnose"
+    if record.get("version"):
+        creator = f"{record.get('module', 'hypnose')} {record['version']}"
+
+    return {
+        "Title": summarize_scope(save_name, subjids, dates),
+        "Subject": blob,
+        "Creator": creator,
+        "CreationDate": datetime.now(),  # must be a datetime, not a string
+    }
+
+
+def _dump(record: dict) -> str:
+    """JSON, ASCII-only, shrunk by dropping the bulkiest field if it will not fit.
+
+    ``ensure_ascii=True`` is load-bearing, not tidiness: matplotlib writes a PDF string
+    containing any non-ASCII character as UTF-16BE with a byte-order mark instead of
+    latin-1. Keeping the blob ASCII keeps the encoding predictable for every reader.
+    """
+    blob = json.dumps(record, default=str)
+    if len(blob) <= MAX_BLOB:
+        return blob
+    trimmed = dict(record)
+    trimmed["params"] = {"...": "omitted (too large)"}
+    blob = json.dumps(trimmed, default=str)
+    return blob if len(blob) <= MAX_BLOB else blob[: MAX_BLOB - 3] + "..."
+
+
+def filter_metadata(metadata: dict) -> dict:
+    """Drop keys matplotlib would reject, so saving never emits a UserWarning."""
+    return {k: v for k, v in (metadata or {}).items() if k in _ALLOWED}
+
+
+# --- reading back ---------------------------------------------------------
+
+
+def read_figure_metadata(path) -> dict:
+    """Recover a saved figure's provenance.
+
+    Returns the parsed ``Subject`` record, plus ``_title`` and ``_creator``.
+
+    Yields ``{}`` for a PDF carrying no provenance, an unreadable one, or a missing
+    file -- never raises, since this is a diagnostic tool and failing hard on an old
+    figure helps nobody. Note the emptiness is deliberate rather than incidental:
+    matplotlib stamps every PDF with its own ``Creator``, so returning that alone would
+    make ``if not read_figure_metadata(p)`` stop meaning "no provenance here".
+    """
+    path = Path(path)
+    if not path.exists():
+        return {}
+    info = _read_info_pypdf(path)
+    if info is None:
+        info = _read_info_stdlib(path)
+
+    subject = (info or {}).get("Subject")
+    if not subject:
+        return {}
+
+    out: dict = {}
+    try:
+        parsed = json.loads(subject)
+    except (ValueError, TypeError):
+        parsed = None
+    if isinstance(parsed, dict):
+        out.update(parsed)
+    else:
+        out["_subject"] = subject
+    if info.get("Title"):
+        out["_title"] = info["Title"]
+    if info.get("Creator"):
+        out["_creator"] = info["Creator"]
+    return out
+
+
+def _read_info_pypdf(path: Path) -> dict | None:
+    try:
+        from pypdf import PdfReader
+    except Exception:
+        return None
+    try:
+        meta = PdfReader(str(path)).metadata or {}
+        return {str(k).lstrip("/"): str(v) for k, v in meta.items()}
+    except Exception:
+        return None
+
+
+# `/Subject (....)` where the closing paren is not escaped. matplotlib writes the info
+# dictionary uncompressed, so this finds it without a PDF parser.
+_ENTRY_RE = r"/{key}\s*\((.*?)(?<!\\)\)"
+
+
+def _read_info_stdlib(path: Path) -> dict:
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return {}
+    info = {}
+    for key in ("Title", "Subject", "Creator"):
+        match = re.search(_ENTRY_RE.format(key=key).encode(), raw, re.S)
+        if match:
+            info[key] = _unescape(match.group(1))
+    return info
+
+
+_ESCAPES = {"n": "\n", "r": "\r", "t": "\t", "b": "\b", "f": "\f"}
+
+
+def _unescape(value: bytes) -> str:
+    """Undo PDF literal-string escaping and decode.
+
+    Two things that are easy to get wrong:
+
+    * Unescaping is one left-to-right pass, not a sequence of `str.replace` calls --
+      replacing ``\\(`` before ``\\\\`` corrupts a literal backslash preceding a paren.
+    * A PDF string holding any non-ASCII character is written as UTF-16BE behind a
+      byte-order mark. We keep our own blob ASCII, but a figure saved by other code (or
+      by an older version of this one) may not be, so honour the BOM.
+    """
+    if value[:2] in (b"\xfe\xff", b"\xff\xfe"):
+        text = value.decode("utf-16", errors="replace")
+    else:
+        text = value.decode("utf-8", errors="replace")
+    return re.sub(r"\\(.)", lambda m: _ESCAPES.get(m.group(1), m.group(1)), text)
+
+
+__all__ = [
+    "build_pdf_metadata", "read_figure_metadata", "summarize_scope", "filter_metadata",
+    "MAX_BLOB",
+]

backstamp-0.0.1/src/backstamp/provenance.py

@@ -0,0 +1,303 @@
+"""What produced this output: commit, version, and the call that made it.
+
+A figure or a results file that cannot be traced back to the code that made it is a
+figure you have to reproduce from scratch before you can trust it. This module builds a
+small, JSON-safe record answering "which code, which version, called how" -- embedded in
+saved PDFs (`metadata`) and, from Phase 7, in `manifest.json` as well. One
+implementation, so the two cannot drift.
+
+**Anchoring, and why there is no default.** `git_commit()` takes the path of the code
+whose commit you want. It must be the *caller's* file: backstamp is installed as a
+library, so anchoring on ``__file__`` here would stamp every figure from every repo with
+the backstamp commit -- plausible-looking and wrong, the same silent-resolution failure
+that `io/paths` hit in restructure_2 Phase 2a and `io/layout` in 2b. `capture_call()`
+finds the calling frame, and `provenance()` anchors on its file.
+
+Nothing here raises. Provenance is a nice-to-have attached to real work, so a detached
+HEAD, a missing `git`, an unreadable frame or an exotic argument type degrades to a
+`None` field or a `<TypeName>` placeholder -- never a failed save.
+"""
+from __future__ import annotations
+
+import inspect
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+# Truncation limits. The PDF info dictionary is not a database: the record has to stay
+# small enough to sit in one string value, so containers are sampled rather than stored.
+MAX_ITEMS = 10
+MAX_STR = 80
+MAX_PARAMS = 15
+
+# How many enclosing function names to keep alongside `function`. Four reaches past a
+# local _save_fig closure and its enclosing analysis function without bloating the blob.
+MAX_CHAIN = 4
+
+# Frames belonging to the saving machinery itself, never the answer to "who plotted this".
+_SKIP_MODULES = (
+    "backstamp.provenance",
+    "backstamp.save",
+    "backstamp.metadata",
+)
+
+_GIT_TIMEOUT = 5
+
+
+# --- git ------------------------------------------------------------------
+
+
+def _git(args, cwd) -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", *args], cwd=str(cwd), capture_output=True, text=True,
+            timeout=_GIT_TIMEOUT,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip() if out.returncode == 0 else None
+
+
+def git_commit(anchor) -> str | None:
+    """Short commit of the repo containing ``anchor``, ``-dirty`` if it has changes.
+
+    ``anchor`` is a file or directory *inside the repo you want described* -- see the
+    module docstring on why this has no default.
+
+    The dirty suffix is not decoration: a bare hash on a modified tree points at code
+    that is not what ran, which is worse than recording nothing.
+    """
+    if anchor is None:
+        return None
+    anchor = Path(anchor)
+    cwd = anchor.parent if anchor.is_file() else anchor
+    if not cwd.exists():
+        return None
+
+    commit = _git(["rev-parse", "--short", "HEAD"], cwd)
+    if not commit:
+        return None
+    # `git status` can be slow on a large tree; this is the cheap equivalent that still
+    # sees both tracked modifications and untracked files.
+    status = _git(["status", "--porcelain", "--untracked-files=normal"], cwd)
+    return f"{commit}-dirty" if status else commit
+
+
+def package_version(module_name: str | None) -> str | None:
+    """Installed version of the distribution providing ``module_name``'s top package.
+
+    The import package and the distribution are routinely named differently -- this
+    family ships `hypnose_behavior` from `hypnose-behavior-analysis` -- so guessing by
+    swapping underscores for hyphens finds nothing. `packages_distributions()` is the
+    real mapping; the guess is only a fallback for Python 3.9, which lacks it.
+    """
+    if not module_name:
+        return None
+    root = module_name.split(".")[0]
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+    except Exception:
+        return None
+
+    try:
+        from importlib.metadata import packages_distributions
+
+        for dist in packages_distributions().get(root, ()):
+            try:
+                return version(dist)
+            except PackageNotFoundError:
+                continue
+    except ImportError:
+        pass  # Python 3.9
+
+    for candidate in (root, root.replace("_", "-")):
+        try:
+            return version(candidate)
+        except Exception:
+            continue
+    return None
+
+
+# --- value summarising ----------------------------------------------------
+
+
+def summarize_value(value, *, max_items: int = MAX_ITEMS, max_str: int = MAX_STR):
+    """Render one call argument as something small and JSON-safe.
+
+    Scalars pass through, strings truncate, containers are sampled, and arrays and
+    frames become shape descriptors (``<DataFrame 50x2>``) rather than being serialised
+    -- the point is to recognise the call later, not to reconstruct its inputs.
+    """
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        # Guard against NaN/inf, which are not valid JSON.
+        return value if value == value and abs(value) != float("inf") else str(value)
+    if isinstance(value, str):
+        return value if len(value) <= max_str else value[: max_str - 3] + "..."
+    if isinstance(value, Path):
+        return summarize_value(str(value), max_str=max_str)
+
+    described = _describe_scientific(value)
+    if described is not None:
+        return described
+
+    if isinstance(value, dict):
+        out = {
+            str(k): summarize_value(v, max_items=max_items, max_str=max_str)
+            for k, v in list(value.items())[:max_items]
+        }
+        if len(value) > max_items:
+            out["..."] = f"+{len(value) - max_items} more"
+        return out
+    if isinstance(value, (list, tuple, set, frozenset)):
+        items = list(value)
+        out = [summarize_value(v, max_items=max_items, max_str=max_str)
+               for v in items[:max_items]]
+        if len(items) > max_items:
+            out.append(f"...+{len(items) - max_items} more")
+        return out
+
+    return f"<{type(value).__name__}>"
+
+
+def _describe_scientific(value) -> str | None:
+    """Shape descriptors for pandas/numpy/matplotlib objects, without importing them.
+
+    Dispatching on the type's module keeps this module importable (and fast) in an
+    environment where numpy or matplotlib is absent, and avoids paying an import just to
+    describe an argument.
+    """
+    module = type(value).__module__.split(".")[0]
+    name = type(value).__name__
+
+    if module == "pandas":
+        if name == "DataFrame":
+            try:
+                return f"<DataFrame {value.shape[0]}x{value.shape[1]}>"
+            except Exception:
+                return "<DataFrame>"
+        if name == "Series":
+            try:
+                return f"<Series {len(value)} {value.dtype}>"
+            except Exception:
+                return "<Series>"
+    if module == "numpy" and name == "ndarray":
+        try:
+            return f"<ndarray {tuple(value.shape)} {value.dtype}>"
+        except Exception:
+            return "<ndarray>"
+    if module == "matplotlib":
+        return f"<{name}>"
+    return None
+
+
+# --- the calling frame ----------------------------------------------------
+
+
+def capture_call(*, skip_modules=(), max_params: int = MAX_PARAMS) -> dict | None:
+    """Describe the nearest frame that is not saving machinery.
+
+    Returns ``{"function", "file", "lineno", "params"}``, where ``params`` covers the
+    named arguments *and* anything that arrived via ``**kwargs``.
+
+    Also returns ``chain``: the next few enclosing function names. Frame-walking is
+    inherently fragile -- ``function`` is only ever "the nearest frame we did not skip",
+    and in real code that is often a local ``_save_fig`` closure rather than the analysis
+    that produced the figure. The chain makes the real caller recoverable anyway, which a
+    single frame cannot. Extend ``skip_modules``, or pass an explicit record to
+    `save`, when even that is not enough.
+    """
+    skip = set(_SKIP_MODULES) | set(skip_modules)
+    try:
+        stack = inspect.stack()
+    except Exception:
+        return None
+    try:
+        kept = [
+            entry for entry in stack[1:]
+            if (entry.frame.f_globals.get("__name__", "") not in skip)
+            and not entry.frame.f_globals.get("__name__", "").startswith(
+                ("importlib", "runpy"))
+        ]
+        if not kept:
+            return None
+        entry = kept[0]
+        return {
+            "function": entry.function,
+            "module": entry.frame.f_globals.get("__name__", ""),
+            "file": Path(entry.filename).name,
+            "path": entry.filename,
+            "lineno": entry.lineno,
+            "chain": [e.function for e in kept[:MAX_CHAIN]],
+            "params": _frame_params(entry.frame, max_params),
+        }
+    except Exception:
+        return None
+    finally:
+        # inspect.stack() holds frame references; dropping them promptly keeps large
+        # plotting locals from being kept alive by a reference cycle.
+        del stack
+
+
+def _frame_params(frame, max_params: int) -> dict:
+    try:
+        info = inspect.getargvalues(frame)
+    except Exception:
+        return {}
+    params: dict = {}
+    for name in info.args:
+        if name in ("self", "cls"):
+            continue
+        params[name] = summarize_value(info.locals.get(name))
+    if info.keywords:  # the **kwargs catch-all: record what was actually passed
+        for name, value in (info.locals.get(info.keywords) or {}).items():
+            params[str(name)] = summarize_value(value)
+    if len(params) > max_params:
+        kept = dict(list(params.items())[:max_params])
+        kept["..."] = f"+{len(params) - max_params} more"
+        return kept
+    return params
+
+
+# --- the record -----------------------------------------------------------
+
+
+def provenance(*, anchor=None, call: dict | None = None, extra: dict | None = None,
+               skip_modules=()) -> dict:
+    """A record of what produced this output.
+
+    ``call`` is a `capture_call` result; when omitted, one is captured here. ``anchor``
+    defaults to the calling code's own file, so the commit describes the repo that ran
+    rather than whichever repo happens to host this function.
+
+    ``skip_modules`` is forwarded to `capture_call`. A repo whose own save function is
+    a thin wrapper **must** pass its module name, or the capture names the wrapper
+    instead of the plotting function that called it.
+    """
+    if call is None:
+        call = capture_call(skip_modules=skip_modules)
+    if anchor is None and call is not None:
+        anchor = call.get("path")
+
+    record = {
+        "created_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "commit": git_commit(anchor),
+        "version": package_version(call.get("module") if call else None),
+    }
+    if call is not None:
+        record.update(
+            {k: call[k] for k in
+             ("function", "module", "file", "lineno", "chain", "params") if k in call}
+        )
+    if extra:
+        record.update(extra)
+    return {k: v for k, v in record.items() if v is not None}
+
+
+__all__ = [
+    "provenance", "git_commit", "package_version", "summarize_value", "capture_call",
+    "MAX_ITEMS", "MAX_STR", "MAX_PARAMS", "MAX_CHAIN",
+]

backstamp-0.0.1/src/backstamp/save.py

@@ -0,0 +1,60 @@
+"""Save a figure as PDF with its provenance record embedded."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .metadata import build_pdf_metadata, filter_metadata
+from .provenance import provenance as _provenance
+
+
+def save(fig, name: str, *, fig_dir, filename=None, subjids=None, dates=None,
+         dpi: int = 600, bbox_inches=None, provenance=None, metadata=None,
+         skip_modules=()) -> Path:
+    """Save ``fig`` as ``fig_dir / filename``, with its provenance embedded.
+
+    - ``name`` heads the ``Title`` summary; ``filename`` defaults to ``{name}.pdf``.
+    - ``fig_dir`` is created if absent.
+    - ``subjids`` / ``dates`` go into the record and the ``Title``.
+    - ``provenance``: a `provenance.provenance()` record to embed instead of capturing one.
+    - ``skip_modules``: modules the frame walk passes over. A wrapper around `save` must
+      pass its own, or the record names the wrapper instead of the plotting function.
+    - ``metadata``: extra PDF info-dictionary entries; keys outside the PDF standard set
+      are dropped.
+
+    Read it back with `metadata.read_figure_metadata(path)`.
+    """
+    # Imported here, so `import backstamp.provenance` stays standard library only.
+    import matplotlib as mpl
+
+    if fig is None:
+        raise ValueError("fig cannot be None")
+    if not name:
+        raise ValueError("name must be non-empty")
+
+    fig_dir = Path(fig_dir)
+    fig_dir.mkdir(parents=True, exist_ok=True)
+    out_path = fig_dir / (filename or f"{name}.pdf")
+
+    bbox = bbox_inches if bbox_inches is not None else "tight"
+
+    # Provenance is attached to real work, so it must never be the reason a save fails:
+    # a broken frame walk or an unreadable git tree costs the metadata, not the figure.
+    try:
+        record = provenance if provenance is not None else _provenance(
+            skip_modules=skip_modules)
+        info = build_pdf_metadata(name, subjids=subjids, dates=dates, provenance=record)
+        info.update(metadata or {})
+        info = filter_metadata(info)
+    except Exception:
+        info = filter_metadata(metadata or {})
+
+    # Type 42 (TrueType) keeps PDF text editable/searchable; matplotlib's default of
+    # Type 3 does not, and journals reject it. Enforced here, scoped, so a caller that
+    # applied no style still gets it.
+    with mpl.rc_context({"pdf.fonttype": 42, "ps.fonttype": 42}):
+        fig.savefig(out_path, bbox_inches=bbox, dpi=dpi, metadata=info)
+
+    return out_path
+
+
+__all__ = ["save"]

backstamp-0.0.1/src/backstamp.egg-info/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: backstamp
+Version: 0.0.1
+Summary: Record how a figure was made inside the figure file itself: commit, calling function, parameters.
+Author: Joschua Geuter
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/Joschua21/backstamp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: pypdf>=3
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# backstamp
+
+A saved figure says nothing about the code that made it. Weeks later, finding the commit,
+the function and the parameters behind a plot means searching old scripts, or making it
+again.
+
+backstamp writes that record into the figure file when it is saved, and reads it back.
+
+## Install
+
+```
+pip install backstamp
+```
+
+Python 3.9 or later. Installs matplotlib and pypdf.
+
+## Save
+
+```python
+import backstamp
+
+def plot_accuracy(trials, window=50):
+    fig, ax = plt.subplots()
+    ...
+    backstamp.save(fig, "accuracy", fig_dir="figures/")
+```
+
+This writes `figures/accuracy.pdf` with a record of:
+
+- the commit of the repository the calling code lives in, marked `-dirty` when it has
+  uncommitted changes
+- the installed version of the calling package
+- the function that called `save`: its module, file, line, and the functions enclosing it
+- that function's parameters. Data objects are stored as their type and shape
+  (`<DataFrame 50x2>`, `<ndarray (3, 4) float64>`), not their values.
+- when the figure was made
+
+Parameters are recorded with the values they have when `save` runs, so a parameter
+reassigned inside the function is recorded with its new value.
+
+The record is JSON in the PDF's `Subject` field, with a one-line summary in `Title`.
+
+## Read
+
+```python
+from backstamp.metadata import read_figure_metadata
+
+read_figure_metadata("figures/accuracy.pdf")
+# {"commit": "a1b2c3d", "function": "plot_accuracy",
+#  "params": {"trials": "<DataFrame 50x2>", "window": 50}, ...}
+```
+
+Returns `{}` for a figure without a record, a file that is not a readable PDF, or a missing
+file.
+
+## Wrapping `save`
+
+The record names the nearest calling function outside backstamp. A function that wraps
+`save` passes its own module, so the record names the plotting function instead of the
+wrapper:
+
+```python
+backstamp.save(fig, name, fig_dir=out_dir, skip_modules=(__name__,))
+```
+
+## Licence
+
+BSD-3-Clause

backstamp-0.0.1/src/backstamp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/backstamp/__init__.py
+src/backstamp/metadata.py
+src/backstamp/provenance.py
+src/backstamp/save.py
+src/backstamp.egg-info/PKG-INFO
+src/backstamp.egg-info/SOURCES.txt
+src/backstamp.egg-info/dependency_links.txt
+src/backstamp.egg-info/requires.txt
+src/backstamp.egg-info/top_level.txt
+tests/test_provenance.py

backstamp-0.0.1/src/backstamp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

backstamp-0.0.1/src/backstamp.egg-info/requires.txt

@@ -0,0 +1,5 @@
+matplotlib
+pypdf>=3
+
+[test]
+pytest

backstamp-0.0.1/src/backstamp.egg-info/top_level.txt

@@ -0,0 +1 @@
+backstamp

backstamp-0.0.1/tests/test_provenance.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python
+"""Unit tests for `backstamp.provenance`, `backstamp.metadata` and `backstamp.save`.
+
+Run directly (no pytest needed)::
+
+    python tests/test_provenance.py
+
+The value summariser is where the work is: every argument any plotting function has ever
+been called with has to become small, JSON-safe text without raising. Most of the cases
+below are that.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import matplotlib  # noqa: E402
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt  # noqa: E402
+
+try:
+    import pandas as pd  # noqa: E402
+except ImportError:  # not a dependency; the pandas cases run where it is installed
+    pd = None
+
+from backstamp.provenance import (  # noqa: E402
+    capture_call, git_commit, provenance, summarize_value,
+)
+from backstamp.metadata import (  # noqa: E402
+    MAX_BLOB, build_pdf_metadata, filter_metadata, read_figure_metadata, summarize_scope,
+)
+from backstamp.save import save  # noqa: E402
+
+
+# --- the value summariser -------------------------------------------------
+
+
+def test_scalars_pass_through():
+    for value in (None, True, False, 0, -3, 2.5, "short"):
+        assert summarize_value(value) == value, value
+
+
+def test_long_strings_truncate():
+    out = summarize_value("x" * 500)
+    assert len(out) <= 80 and out.endswith("...")
+
+
+def test_non_finite_floats_become_strings():
+    """NaN and inf are not valid JSON; json.dumps emits them anyway, so catch them here."""
+    for value in (float("nan"), float("inf"), float("-inf")):
+        assert isinstance(summarize_value(value), str)
+    assert json.loads(json.dumps({"v": summarize_value(float("nan"))}))
+
+
+def test_containers_truncate_and_report_the_remainder():
+    out = summarize_value(list(range(50)))
+    assert len(out) == 11 and out[-1] == "...+40 more"
+    out = summarize_value({f"k{i}": i for i in range(50)})
+    assert len(out) == 11 and out["..."] == "+40 more"
+    assert summarize_value((1, 2)) == [1, 2]
+    assert sorted(summarize_value({3, 1, 2})) == [1, 2, 3]
+
+
+def test_nested_containers_are_summarised_recursively():
+    assert summarize_value({"a": [1, {"b": "x" * 500}]})["a"][1]["b"].endswith("...")
+
+
+def test_scientific_types_become_descriptors():
+    import numpy as np
+
+    assert summarize_value(np.zeros((100, 3))) == "<ndarray (100, 3) float64>"
+    fig, ax = plt.subplots()
+    assert summarize_value(ax).startswith("<Axes")
+    plt.close(fig)
+    if pd is not None:
+        assert summarize_value(pd.DataFrame({"a": [1, 2], "b": [3, 4]})) == "<DataFrame 2x2>"
+        assert summarize_value(pd.Series([1, 2, 3])).startswith("<Series 3 ")
+
+
+def test_unknown_objects_become_type_names():
+    class Widget:
+        pass
+
+    assert summarize_value(Widget()) == "<Widget>"
+    assert summarize_value(Path("/tmp/x")) == "/tmp/x"
+
+
+def test_summariser_output_is_json_serialisable():
+    import numpy as np
+
+    payload = {"arr": np.zeros(3), "nested": [{"x": None}],
+               "big": list(range(100)), "nan": float("nan")}
+    if pd is not None:
+        payload["df"] = pd.DataFrame({"a": [1]})
+    json.dumps(summarize_value(payload))  # must not raise
+
+
+# --- capturing the call ---------------------------------------------------
+
+
+def _plotter(data, subjids, *, window=30, **kwargs):
+    return capture_call()
+
+
+def test_capture_records_function_args_and_kwargs():
+    import numpy as np
+
+    got = _plotter(np.zeros((2, 1)), [40, 45], window=7, color="red")
+    assert got["function"] == "_plotter"
+    assert got["file"] == "test_provenance.py"
+    assert isinstance(got["lineno"], int)
+    assert got["params"]["data"] == "<ndarray (2, 1) float64>"
+    assert got["params"]["subjids"] == [40, 45]
+    assert got["params"]["window"] == 7
+    assert got["params"]["color"] == "red"  # arrived via **kwargs
+
+
+def test_capture_skips_the_saving_machinery():
+    """The first frame must never be provenance.py itself."""
+    assert capture_call()["function"] == "test_capture_skips_the_saving_machinery"
+
+
+# --- git ------------------------------------------------------------------
+
+
+def test_git_commit_reports_dirty_and_tolerates_a_non_repo():
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        assert git_commit(root) is None  # not a repo -> None, never an exception
+
+        run = lambda *a: subprocess.run(a, cwd=root, capture_output=True)  # noqa: E731
+        run("git", "init", "-q")
+        run("git", "config", "user.email", "t@t")
+        run("git", "config", "user.name", "t")
+        (root / "a.txt").write_text("one")
+        run("git", "add", "-A")
+        run("git", "commit", "-qm", "first")
+
+        clean = git_commit(root)
+        assert clean and not clean.endswith("-dirty")
+
+        (root / "a.txt").write_text("two")
+        assert git_commit(root) == f"{clean}-dirty"
+
+    assert git_commit(None) is None
+    assert git_commit(Path("/nonexistent/xyz")) is None
+
+
+def test_provenance_anchors_on_the_caller_not_on_the_library():
+    """The whole point: the commit must describe the code that ran.
+
+    backstamp is installed as a library, so anchoring on its own __file__ would stamp
+    every figure from every repo with the backstamp commit.
+    """
+    record = provenance()
+    assert record["function"] == "test_provenance_anchors_on_the_caller_not_on_the_library"
+    assert record["file"] == "test_provenance.py"
+    assert "created_at" in record
+    json.dumps(record)
+
+
+# --- the PDF ---------------------------------------------------------------
+
+
+def test_package_version_resolves_a_renamed_distribution():
+    """Import package and distribution names often differ.
+
+    `hypnose_behavior` ships from `hypnose-behavior-analysis`, so swapping underscores
+    for hyphens finds nothing; only packages_distributions() maps it, from Python 3.10.
+    """
+    from backstamp.provenance import package_version
+
+    with tempfile.TemporaryDirectory() as tmp:
+        info = Path(tmp) / "renamed_dist-1.2.3.dist-info"
+        info.mkdir()
+        (info / "METADATA").write_text(
+            "Metadata-Version: 2.1\nName: renamed-dist\nVersion: 1.2.3\n")
+        (info / "top_level.txt").write_text("other_name\n")
+        sys.path.insert(0, tmp)
+        try:
+            renamed = package_version("other_name.sub")
+        finally:
+            sys.path.remove(tmp)
+    if sys.version_info >= (3, 10):
+        assert renamed == "1.2.3", renamed
+
+    assert package_version("matplotlib.figure")
+    assert package_version("__main__") is None
+    assert package_version("definitely_not_installed_xyz") is None
+    assert package_version(None) is None
+
+
+def test_summarize_scope():
+    assert summarize_scope("accuracy", 66, 20260709) == "accuracy sub-066 20260709"
+    assert summarize_scope("accuracy", [40, 45, 66], ["20251124", "20260203"]) == (
+        "accuracy sub-040,045,066 20251124-20260203")
+    assert summarize_scope("plain") == "plain"
+
+
+def test_filter_metadata_drops_keys_matplotlib_would_reject():
+    out = filter_metadata({"Title": "t", "Subject": "s", "Custom": "x"})
+    assert out == {"Title": "t", "Subject": "s"}
+
+
+def test_oversized_records_are_shrunk_not_dropped():
+    huge = {"function": "f", "params": {f"k{i}": "v" * 100 for i in range(200)}}
+    blob = build_pdf_metadata("n", provenance=huge)["Subject"]
+    assert len(blob) <= MAX_BLOB
+    assert json.loads(blob)["function"] == "f"  # the identifying fields survive
+
+
+def test_pdf_round_trip():
+    """Save a real figure and read its provenance back out."""
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        ax.plot([1, 2, 3], [1, 4, 9])
+        path = save(fig, "accuracy", fig_dir=tmp, subjids=[40, 66],
+                    dates=[20251124, 20260203])
+        plt.close(fig)
+        assert path.exists() and path.name == "accuracy.pdf"
+
+        got = read_figure_metadata(path)
+        assert got["function"] == "test_pdf_round_trip"
+        assert got["file"] == "test_provenance.py"
+        assert got["subjids"] == ["040", "066"]
+        assert got["dates"] == ["20251124", "20260203"]
+        assert got["_title"] == "accuracy sub-040,066 20251124-20260203"
+        assert "created_at" in got
+
+
+def test_filename_and_a_new_fig_dir():
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        path = save(fig, "x", fig_dir=Path(tmp) / "new", filename="x_sub-040.pdf")
+        plt.close(fig)
+        assert path == Path(tmp) / "new" / "x_sub-040.pdf" and path.exists()
+
+
+def test_explicit_provenance_overrides_introspection():
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        path = save(fig, "x", fig_dir=tmp, subjids=1,
+                    provenance={"function": "the_real_plotter", "note": "explicit"})
+        plt.close(fig)
+        got = read_figure_metadata(path)
+        assert got["function"] == "the_real_plotter" and got["note"] == "explicit"
+
+
+def test_saving_never_warns_about_infodict_keys():
+    import warnings
+
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            save(fig, "x", fig_dir=tmp, subjids=1, metadata={"Bogus": "dropped"})
+        plt.close(fig)
+        assert not [w for w in caught if "infodict" in str(w.message)]
+
+
+def test_reading_a_provenance_free_or_missing_pdf_returns_empty():
+    """Empty must mean "no provenance", so `if not read_figure_metadata(p)` is usable.
+
+    matplotlib stamps a Creator on every PDF it writes, so a bare figure is not an
+    empty info dictionary -- it just has nothing of ours in it.
+    """
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        bare = Path(tmp) / "bare.pdf"
+        fig.savefig(bare)
+        plt.close(fig)
+        assert read_figure_metadata(bare) == {}
+        assert read_figure_metadata(Path(tmp) / "nope.pdf") == {}
+        (Path(tmp) / "junk.pdf").write_bytes(b"not a pdf")
+        assert read_figure_metadata(Path(tmp) / "junk.pdf") == {}
+
+
+def test_stdlib_reader_matches_on_awkward_characters():
+    """Both readers: pypdf through read_figure_metadata, and the stdlib fallback directly."""
+    from backstamp.metadata import _read_info_stdlib
+
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        note = r"parens ( ) and \ backslash"
+        path = save(fig, "x", fig_dir=tmp, subjids=1,
+                    provenance={"function": "f", "note": note})
+        plt.close(fig)
+        assert json.loads(_read_info_stdlib(path)["Subject"])["note"] == note
+        assert read_figure_metadata(path)["note"] == note
+
+
+def test_a_wrapper_can_exclude_itself():
+    """A repo whose save function is a thin wrapper must not name itself as the plotter.
+
+    Capturing inside the wrapper is not enough -- capture_call still returns the
+    wrapper's own frame. Only the skip list fixes it.
+    """
+    import types
+
+    # A stand-in for hypnose_behavior.io.save, in its own module namespace -- the
+    # wrapper and the plotter must not share one, or skipping hides both.
+    wrapper_mod = types.ModuleType("fake_repo.io.save")
+    wrapper_mod.provenance = provenance
+    exec(
+        "def save_figure():\n"
+        "    return provenance(), provenance(skip_modules=('fake_repo.io.save',))\n",
+        wrapper_mod.__dict__,
+    )
+
+    def real_plotter():
+        return wrapper_mod.save_figure()
+
+    naive, skipped = real_plotter()
+    assert naive["function"] == "save_figure"      # the bug this guards against
+    assert skipped["function"] == "real_plotter"   # what we actually want
+
+
+def test_save_forwards_skip_modules():
+    import types
+
+    wrapper_mod = types.ModuleType("fake_repo.io.save")
+    wrapper_mod.save = save
+    exec(
+        "def save_figure(fig, fig_dir):\n"
+        "    return save(fig, 'x', fig_dir=fig_dir, skip_modules=(__name__,))\n",
+        wrapper_mod.__dict__,
+    )
+
+    def real_plotter(fig_dir):
+        fig, ax = plt.subplots()
+        path = wrapper_mod.save_figure(fig, fig_dir)
+        plt.close(fig)
+        return path
+
+    with tempfile.TemporaryDirectory() as tmp:
+        assert read_figure_metadata(real_plotter(tmp))["function"] == "real_plotter"
+
+
+def test_chain_reaches_past_an_inner_save_closure():
+    """The real case from movement_analysis_utils: a nested `_save_fig` helper.
+
+    `function` can only ever be "the nearest frame we did not skip", and in real
+    plotting code that is often a local closure rather than the analysis that produced
+    the figure. The chain is what makes the enclosing function recoverable.
+    """
+    def run_movement_stats_batch():
+        def _save_fig():  # the closure that actually calls save
+            return provenance()
+        return _save_fig()
+
+    record = run_movement_stats_batch()
+    assert record["function"] == "_save_fig"
+    assert record["chain"][:2] == ["_save_fig", "run_movement_stats_batch"]
+    assert "test_chain_reaches_past_an_inner_save_closure" in record["chain"]
+
+
+def test_chain_survives_the_pdf_round_trip():
+    with tempfile.TemporaryDirectory() as tmp:
+        def analysis():
+            def _save_fig():
+                fig, ax = plt.subplots()
+                path = save(fig, "x", fig_dir=tmp, subjids=1)
+                plt.close(fig)
+                return path
+            return _save_fig()
+
+        got = read_figure_metadata(analysis())
+        assert got["chain"][:2] == ["_save_fig", "analysis"]
+
+
+def test_blob_stays_ascii_so_the_pdf_string_encoding_is_predictable():
+    """Any non-ASCII character makes matplotlib write the string as UTF-16BE.
+
+    The truncation markers used to be "…", which silently switched the encoding and
+    broke the stdlib reader for exactly the records that needed truncating.
+    """
+    from backstamp.metadata import _dump
+
+    blob = _dump({"params": summarize_value({"big": list(range(99)), "s": "y" * 300})})
+    blob.encode("ascii")  # must not raise
+    assert "..." in blob
+
+
+def test_round_trip_survives_truncation_and_non_ascii_arguments():
+    with tempfile.TemporaryDirectory() as tmp:
+        fig, ax = plt.subplots()
+        path = save(fig, "x", fig_dir=tmp, subjids=1, provenance={
+            "function": "f",
+            "params": summarize_value({"many": list(range(99)), "unicode": "µ ± σ °C"}),
+        })
+        plt.close(fig)
+        got = read_figure_metadata(path)
+        assert got["function"] == "f"
+        assert got["params"]["many"][-1] == "...+89 more"
+        assert got["params"]["unicode"] == "µ ± σ °C"
+
+
+def main() -> int:
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failures = []
+    for test in tests:
+        try:
+            test()
+        except Exception as exc:  # noqa: BLE001
+            failures.append(test.__name__)
+            print(f"  [FAIL] {test.__name__}: {type(exc).__name__}: {exc}")
+        else:
+            print(f"  [ok]   {test.__name__}")
+    print(f"\n{len(tests) - len(failures)}/{len(tests)} passed")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())