lusca 0.1.1__tar.gz

lusca-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 evmckinney9
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lusca-0.1.1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: lusca
+Version: 0.1.1
+Summary: A Jupyter magic command for creating reproducible matplotlib figures.
+Author-email: Evan McKinney <evmckinney9@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/evmckinney9/lusca
+Project-URL: Repository, https://github.com/evmckinney9/lusca
+Project-URL: Issues, https://github.com/evmckinney9/lusca/issues
+Keywords: jupyter,ipython-magic,matplotlib,reproducibility,figures,scientific-plotting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: pylatexenc; extra == "dev"
+Requires-Dist: ipywidgets; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: format
+Requires-Dist: pre-commit; extra == "format"
+Requires-Dist: ruff; extra == "format"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# lusca
+
+![CI](https://github.com/evmckinney9/lusca/actions/workflows/ci.yml/badge.svg?branch=main) ![Python](https://img.shields.io/badge/python-3.12-blue.svg) ![Ruff](https://img.shields.io/badge/linter-ruff-green.svg)
+
+`lusca` is a Python library for creating reproducible matplotlib figures using Jupyter magic commands.
+
+Often, you want to use Jupyter for experiments but may not want to rerun the entire notebook to recreate plots. Additionally, saving data and figures is essential for artifact generation and reproducibility.
+
+## 📊 `%%mplfreeze` Command
+
+The `%%mplfreeze` magic command:
+- Captures the data used in your plots and saves it in a compressed NPZ file.
+- Automatically exports your figures in multiple useful formats.
+- Creates a minimal standalone script that reproduces the figure.
+- Snapshots Python/package versions and the git commit into `<name>.meta.json`.
+- Statically checks the cell for unsaved free names *before* writing anything,
+  then runs the generated replot in a subprocess to confirm the bundle
+  actually reproduces the figure — if `%%mplfreeze` succeeds, the replot is
+  guaranteed to work.
+- Leverages `lusca`'s built-in stylesheet.
+
+Once you're satisfied with your plot, add the `%%mplfreeze` command to the cell.
+```python
+%%mplfreeze <name> [vars ...] [--outdir DIR]
+```
+- `<name>`: Base name for outputs (folder + files).
+- `[vars ...]`: Variable names to save into the NPZ file.
+- `[--outdir DIR]`: (Optional) Parent output directory (default: `docs/figs`).
+
+### Example
+
+1. Import and load the magic command
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+import lusca
+%load_ext lusca
+```
+
+2. Some data
+```python
+x_data = np.linspace(-10, 10, 100)
+sine = np.sin(x_data)
+cosine = np.cos(x_data)
+```
+3. Plot + save
+```python
+%%mplfreeze trig_demo x_data sine cosine
+with plt.style.context("lusca"):
+    fig, ax = plt.subplots(1, 1, figsize=(3.5, 2.6), sharey=True)
+    ax.plot(x_data, sine, label="Sine")
+    ax.plot(x_data, cosine, label="Cosine")
+    plt.show()
+```
+
+An example notebook is available in `src/demo.ipynb`. The generated plots are saved in `docs/figs/` with the following structure:
+
+```
+name_stamp/
+    name.npz             # saved variables
+    name.pdf             # exported figure
+    name.png
+    name.svg
+    name.meta.json       # python/package versions + git commit
+    replot_name.py       # standalone replot script
+```
+## Installation
+
+Install `lusca` directly from GitHub:
+
+```bash
+pip install -e git+https://github.com/evmckinney9/lusca#egg=lusca
+```
+
+#### Note
+
+If you are using VS Code, you can set the workspace root as the default directory for saving figures by adding the following setting to your `settings.json` file. Otherwise, output paths will be relative to the notebook location.
+
+```json
+"jupyter.notebookFileRoot": "${workspaceFolder}"
+```

lusca-0.1.1/README.md

@@ -0,0 +1,81 @@
+# lusca
+
+![CI](https://github.com/evmckinney9/lusca/actions/workflows/ci.yml/badge.svg?branch=main) ![Python](https://img.shields.io/badge/python-3.12-blue.svg) ![Ruff](https://img.shields.io/badge/linter-ruff-green.svg)
+
+`lusca` is a Python library for creating reproducible matplotlib figures using Jupyter magic commands.
+
+Often, you want to use Jupyter for experiments but may not want to rerun the entire notebook to recreate plots. Additionally, saving data and figures is essential for artifact generation and reproducibility.
+
+## 📊 `%%mplfreeze` Command
+
+The `%%mplfreeze` magic command:
+- Captures the data used in your plots and saves it in a compressed NPZ file.
+- Automatically exports your figures in multiple useful formats.
+- Creates a minimal standalone script that reproduces the figure.
+- Snapshots Python/package versions and the git commit into `<name>.meta.json`.
+- Statically checks the cell for unsaved free names *before* writing anything,
+  then runs the generated replot in a subprocess to confirm the bundle
+  actually reproduces the figure — if `%%mplfreeze` succeeds, the replot is
+  guaranteed to work.
+- Leverages `lusca`'s built-in stylesheet.
+
+Once you're satisfied with your plot, add the `%%mplfreeze` command to the cell.
+```python
+%%mplfreeze <name> [vars ...] [--outdir DIR]
+```
+- `<name>`: Base name for outputs (folder + files).
+- `[vars ...]`: Variable names to save into the NPZ file.
+- `[--outdir DIR]`: (Optional) Parent output directory (default: `docs/figs`).
+
+### Example
+
+1. Import and load the magic command
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+import lusca
+%load_ext lusca
+```
+
+2. Some data
+```python
+x_data = np.linspace(-10, 10, 100)
+sine = np.sin(x_data)
+cosine = np.cos(x_data)
+```
+3. Plot + save
+```python
+%%mplfreeze trig_demo x_data sine cosine
+with plt.style.context("lusca"):
+    fig, ax = plt.subplots(1, 1, figsize=(3.5, 2.6), sharey=True)
+    ax.plot(x_data, sine, label="Sine")
+    ax.plot(x_data, cosine, label="Cosine")
+    plt.show()
+```
+
+An example notebook is available in `src/demo.ipynb`. The generated plots are saved in `docs/figs/` with the following structure:
+
+```
+name_stamp/
+    name.npz             # saved variables
+    name.pdf             # exported figure
+    name.png
+    name.svg
+    name.meta.json       # python/package versions + git commit
+    replot_name.py       # standalone replot script
+```
+## Installation
+
+Install `lusca` directly from GitHub:
+
+```bash
+pip install -e git+https://github.com/evmckinney9/lusca#egg=lusca
+```
+
+#### Note
+
+If you are using VS Code, you can set the workspace root as the default directory for saving figures by adding the following setting to your `settings.json` file. Otherwise, output paths will be relative to the notebook location.
+
+```json
+"jupyter.notebookFileRoot": "${workspaceFolder}"
+```

lusca-0.1.1/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lusca"
+description = "A Jupyter magic command for creating reproducible matplotlib figures."
+version = "0.1.1"
+authors = [{ name = "Evan McKinney", email = "evmckinney9@gmail.com" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = [
+    "jupyter",
+    "ipython-magic",
+    "matplotlib",
+    "reproducibility",
+    "figures",
+    "scientific-plotting",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Plugins",
+    "Framework :: IPython",
+    "Framework :: Jupyter",
+    "Framework :: Matplotlib",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = ["numpy", "matplotlib"]
+
+[project.urls]
+Homepage = "https://github.com/evmckinney9/lusca"
+Repository = "https://github.com/evmckinney9/lusca"
+Issues = "https://github.com/evmckinney9/lusca/issues"
+
+[project.optional-dependencies]
+dev = ["ipykernel", "pylatexenc", "ipywidgets", "pre-commit"]
+format = ["pre-commit", "ruff"]
+test = ["pytest"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["lusca*"]
+
+[tool.setuptools.package-data]
+lusca = ["styles/**/*.mplstyle"]
+
+[tool.ruff]
+target-version = "py312"
+fix = true
+extend-include = ["*.ipynb"]
+
+[tool.ruff.lint]
+select = ["D"]
+ignore = ["D105"] # magic methods like __init__ don't need docstrings
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**" = ["D"]
+"src/tests/**/*.py" = ["D1"]
+"**/*.ipynb" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

lusca-0.1.1/setup.cfg

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

lusca-0.1.1/src/lusca/__init__.py

@@ -0,0 +1,29 @@
+# https://github.com/garrettj403/SciencePlots/blob/master/scienceplots/__init__.py
+import os  # pathlib.Path.walk not available in Python <3.12
+
+import matplotlib.pyplot as plt
+
+import lusca
+
+# register the bundled stylesheets in the matplotlib style library
+styles_path = lusca.__path__[0]
+# styles_path = os.path.join(scienceplots_path, "styles")
+
+# Reads styles in /styles folder and all subfolders
+stylesheets = {}  # plt.style.library is a dictionary
+for folder, _, _ in os.walk(styles_path):
+    new_stylesheets = plt.style.core.read_style_directory(folder)
+    stylesheets.update(new_stylesheets)
+
+# Update dictionary of styles - plt.style.library
+plt.style.core.update_nested_dict(plt.style.library, stylesheets)
+# Update `plt.style.available`, copy-paste from:
+# https://github.com/matplotlib/matplotlib/blob/a170539a421623bb2967a45a24bb7926e2feb542/lib/matplotlib/style/core.py#L266  # noqa: E501
+plt.style.core.available[:] = sorted(plt.style.library.keys())
+
+# Re-export the magic's IPython hooks so users can do `%load_ext lusca`
+# instead of the longer `%load_ext lusca.mpl_freeze`.
+from lusca.mpl_freeze import (  # noqa: E402, F401
+    load_ipython_extension,
+    unload_ipython_extension,
+)

lusca-0.1.1/src/lusca/mpl_freeze.py

@@ -0,0 +1,615 @@
+"""Jupyter magic for freezing matplotlib plots and saving data.
+
+This module provides the %%mplfreeze magic command for Jupyter/IPython, which captures
+plotting cells, saves specified variables to compressed NPZ files, exports figures in
+multiple formats, and generates standalone replot scripts for reproducibility.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import builtins as _builtins
+import json
+import logging
+import os
+import platform
+import shlex
+import shutil
+import subprocess
+import sys
+import textwrap
+from datetime import datetime
+from importlib import metadata as importlib_metadata
+from pathlib import Path
+
+import numpy as np
+
+# Names the generated replot script binds before executing the captured cell.
+_REPLOT_PROVIDED: frozenset[str] = frozenset(
+    {"np", "plt", "lusca", "os", "Path", "data"}
+)
+
+
+# ---- parse: %%mplfreeze <name> [vars ...] [--outdir DIR] ----
+def _parse_line(line: str):
+    p = argparse.ArgumentParser(prog="%%mplfreeze", add_help=False)
+    p.add_argument("name", help="Base name for outputs (folder + files)")
+    p.add_argument("vars", nargs="*", help="Variable names to save into the NPZ")
+    p.add_argument("--outdir", default="docs/figs", help="Parent output directory")
+    a = p.parse_args(shlex.split(line))
+    return a.name, a.vars, a.outdir
+
+
+def _warn_on_reserved_varnames(varnames: list[str]) -> None:
+    """Warn if any saved varname shadows a name the replot pre-binds.
+
+    The replot does ``import numpy as np`` etc. before binding NPZ data,
+    so a saved variable named ``np`` will silently overwrite the numpy
+    import in the replot's namespace. Almost always a mistake.
+    """
+    clashes = sorted(set(varnames) & _REPLOT_PROVIDED)
+    if clashes:
+        logging.warning(
+            f"[mplfreeze] saved variable(s) {clashes} shadow names the replot "
+            f"pre-binds {sorted(_REPLOT_PROVIDED)}; the NPZ value will overwrite "
+            f"the import (e.g. saving 'np' replaces numpy). Rename if "
+            f"unintentional."
+        )
+
+
+def _warn_on_extra_figures(fignums: list[int], kept_num: int) -> None:
+    """Warn if the cell created multiple figures; only ``kept_num`` is saved."""
+    if len(fignums) > 1:
+        logging.warning(
+            f"[mplfreeze] cell created {len(fignums)} figures "
+            f"(numbers={sorted(fignums)}); only fig#{kept_num} was saved. "
+            f"To capture the others, split them into separate %%mplfreeze "
+            f"cells or assign the desired one to `fig`."
+        )
+
+
+def _collect_loaded_names(tree: ast.AST) -> set[str]:
+    return {
+        n.id
+        for n in ast.walk(tree)
+        if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load)
+    }
+
+
+def _collect_cell_defined_names(tree: ast.AST) -> set[str]:
+    """Best-effort set of names bound anywhere in the cell.
+
+    Conservative: walks the whole tree and treats any binding (assignment,
+    import, function/class/lambda parameter, comprehension target, except
+    handler, walrus) as cell-scope. Star-imports cannot be enumerated; we
+    insert the sentinel "*" so the caller can warn.
+    """
+    defined: set[str] = set()
+
+    def _add_target(node: ast.AST) -> None:
+        if isinstance(node, ast.Name):
+            defined.add(node.id)
+        elif isinstance(node, (ast.Tuple, ast.List)):
+            for elt in node.elts:
+                _add_target(elt)
+        elif isinstance(node, ast.Starred):
+            _add_target(node.value)
+        # Attribute / Subscript targets bind nothing new.
+
+    def _add_args(args: ast.arguments) -> None:
+        for a in (*args.posonlyargs, *args.args, *args.kwonlyargs):
+            defined.add(a.arg)
+        if args.vararg:
+            defined.add(args.vararg.arg)
+        if args.kwarg:
+            defined.add(args.kwarg.arg)
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign):
+            for t in node.targets:
+                _add_target(t)
+        elif isinstance(node, (ast.AugAssign, ast.AnnAssign)):
+            _add_target(node.target)
+        elif isinstance(node, (ast.For, ast.AsyncFor)):
+            _add_target(node.target)
+        elif isinstance(node, (ast.With, ast.AsyncWith)):
+            for item in node.items:
+                if item.optional_vars is not None:
+                    _add_target(item.optional_vars)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            defined.add(node.name)
+            _add_args(node.args)
+        elif isinstance(node, ast.ClassDef):
+            defined.add(node.name)
+        elif isinstance(node, ast.Lambda):
+            _add_args(node.args)
+        elif isinstance(
+            node, (ast.ListComp, ast.SetComp, ast.GeneratorExp, ast.DictComp)
+        ):
+            for gen in node.generators:
+                _add_target(gen.target)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                if alias.name == "*":
+                    defined.add("*")
+                else:
+                    defined.add(alias.asname or alias.name.split(".")[0])
+        elif isinstance(node, ast.ExceptHandler):
+            if node.name:
+                defined.add(node.name)
+        elif isinstance(node, ast.NamedExpr):
+            _add_target(node.target)
+
+    return defined
+
+
+def _check_free_names(cell_src: str, varnames: list[str]) -> None:
+    """Raise RuntimeError if the cell references names not bound at replot time.
+
+    The replot script binds: numpy as np, pyplot as plt, lusca, os, Path,
+    data, plus each saved variable. Anything else used in the cell must
+    either be a builtin or be defined inside the cell itself.
+    """
+    try:
+        tree = ast.parse(cell_src)
+    except SyntaxError:
+        logging.warning(
+            "[mplfreeze] could not parse captured cell as Python (likely "
+            "contains IPython magics or shell escapes); skipping free-name "
+            "check."
+        )
+        return
+
+    defined_in_cell = _collect_cell_defined_names(tree)
+    if "*" in defined_in_cell:
+        logging.warning(
+            "[mplfreeze] captured cell uses `from ... import *`; free-name "
+            "check cannot enumerate names provided by the star import."
+        )
+        defined_in_cell.discard("*")
+
+    loaded = _collect_loaded_names(tree)
+    provided = (
+        set(varnames) | set(_REPLOT_PROVIDED) | set(dir(_builtins)) | defined_in_cell
+    )
+    missing = sorted(loaded - provided)
+    if missing:
+        raise RuntimeError(
+            f"[mplfreeze] captured cell references unsaved free names: "
+            f"{missing}. Add these to the %%mplfreeze line, or inline their "
+            f"values inside the cell."
+        )
+
+
+def _save_npz(path: Path, ns: dict, varnames: list[str]) -> dict[str, dict]:
+    """Save varnames from ns into a compressed NPZ; return per-variable metadata.
+
+    Emits a logging.warning for any variable whose ``np.asarray`` coercion
+    yields ``dtype=object`` — that artifact will require ``allow_pickle=True``
+    to load and is brittle across NumPy/Python versions.
+    """
+    arrays: dict[str, np.ndarray] = {}
+    info: dict[str, dict] = {}
+    for v in varnames:
+        if v not in ns:
+            raise RuntimeError(
+                f"[mplfreeze] Variable '{v}' not found in the notebook namespace."
+            )
+        arr = np.asarray(ns[v])
+        arrays[v] = arr
+        info[v] = {"shape": arr.shape, "dtype": arr.dtype}
+        if arr.dtype == object:
+            logging.warning(
+                f"[mplfreeze] Variable {v!r} coerced to a dtype=object array "
+                f"(shape={arr.shape}); the saved .npz will use pickle and "
+                f"requires allow_pickle=True to load. Pickled .npz is brittle "
+                f"across NumPy/Python versions — consider flattening {v!r} "
+                f"into rectangular numeric arrays for long-term reproducibility."
+            )
+    if not arrays:
+        raise RuntimeError(
+            "[mplfreeze] No variables provided. Use: %%mplfreeze name x y ..."
+        )
+    np.savez_compressed(path, **arrays)
+    return info
+
+
+def _write_replot(
+    root: Path,
+    cell_src: str,
+    base: str,
+    varnames: list[str],
+    info: dict[str, dict],
+) -> None:
+    bind_lines = []
+    for v in varnames:
+        meta = info[v]
+        if meta["dtype"] == object and meta["shape"] == ():
+            # 0-d object array — unwrap so users get the original Python value.
+            bind_lines.append(f"        {v} = data[{v!r}].item()")
+        else:
+            bind_lines.append(f"        {v} = data[{v!r}]")
+    binds = "\n".join(bind_lines)
+    code = f'''# replot_{base}.py — auto-generated by %%mplfreeze
+import argparse
+import os
+from pathlib import Path
+import numpy as np, matplotlib.pyplot as plt
+
+try:
+    import lusca  # noqa: F401  — registers bundled matplotlib stylesheets
+except ImportError:
+    pass
+
+HERE = Path(__file__).parent
+NPZ  = HERE / "{base}.npz"
+
+def main(out_path=None):
+    _prev_cwd = os.getcwd()
+    os.chdir(HERE)
+    try:
+        data = np.load(NPZ, allow_pickle=True)
+{binds}
+
+        # ---- begin captured plotting cell ----
+{textwrap.indent(cell_src.strip(), "        ")}
+        # ---- end captured plotting cell ----
+
+        fig = plt.gcf()
+        if out_path:
+            fig.savefig(out_path)
+        return fig
+    finally:
+        os.chdir(_prev_cwd)
+
+if __name__ == "__main__":
+    # parse_known_args so that argv pollution from a Jupyter kernel launch
+    # (e.g. `-f /path/to/kernel-XXX.json`) is ignored rather than mistaken
+    # for a savefig destination.
+    _p = argparse.ArgumentParser()
+    _p.add_argument("--out", default=None, help="Optional path to save the figure")
+    _args, _ = _p.parse_known_args()
+    main(_args.out)
+'''
+    (root / f"replot_{base}.py").write_text(code)
+
+
+def _git_snapshot(cwd: Path) -> dict | None:
+    """Return {commit, branch, dirty} for the git repo at cwd, or None."""
+
+    def _git(*args: str) -> str | None:
+        try:
+            r = subprocess.run(
+                ["git", "-C", str(cwd), *args],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return None
+        return r.stdout.strip() if r.returncode == 0 else None
+
+    commit = _git("rev-parse", "HEAD")
+    if commit is None:
+        return None
+    branch = _git("rev-parse", "--abbrev-ref", "HEAD")
+    status = _git("status", "--porcelain")
+    return {
+        "commit": commit,
+        "branch": branch,
+        "dirty": bool(status) if status is not None else None,
+    }
+
+
+def _package_version(name: str) -> str | None:
+    try:
+        return importlib_metadata.version(name)
+    except importlib_metadata.PackageNotFoundError:
+        return None
+
+
+def _write_metadata(
+    root: Path,
+    base: str,
+    line: str,
+    varnames: list[str],
+    outdir: str,
+) -> None:
+    """Write `<base>.meta.json` snapshotting the freeze environment.
+
+    Captures Python/numpy/matplotlib/lusca versions, the platform string,
+    git commit + dirty state (if cwd is in a repo), and the magic invocation.
+    Future-you needs this when matplotlib's defaults shift and the frozen
+    PNG no longer matches what the replot draws.
+    """
+    meta = {
+        "freeze_time": datetime.now().isoformat(timespec="seconds"),
+        "magic_line": line,
+        "base": base,
+        "varnames": list(varnames),
+        "outdir": outdir,
+        "python": platform.python_version(),
+        "platform": platform.platform(),
+        "packages": {
+            "numpy": _package_version("numpy"),
+            "matplotlib": _package_version("matplotlib"),
+            "lusca": _package_version("lusca"),
+        },
+        "git": _git_snapshot(Path.cwd()),
+    }
+    (root / f"{base}.meta.json").write_text(json.dumps(meta, indent=2) + "\n")
+
+
+def _maybe_dedupe_against_latest(outdir: Path, base: str, root: Path) -> Path:
+    """If ``{base}_latest`` already points at an identical run, delete root.
+
+    "Identical" means the NPZ and the generated replot script are byte-equal
+    (the figure exports may differ in embedded timestamps even for matching
+    inputs, so we don't compare them). When the user re-runs an unchanged
+    cell, this prevents the output directory from accumulating one new
+    timestamped folder per execution.
+
+    Returns the run folder that should be considered the "current" one —
+    either the prior one (if dedup happened) or ``root`` unchanged.
+    """
+    latest = outdir / f"{base}_latest"
+    if not latest.is_symlink():
+        return root
+    try:
+        prior = (outdir / os.readlink(latest)).resolve()
+    except OSError:
+        return root
+    if not prior.is_dir() or prior == root.resolve():
+        return root
+    npz_a, npz_b = root / f"{base}.npz", prior / f"{base}.npz"
+    rep_a, rep_b = root / f"replot_{base}.py", prior / f"replot_{base}.py"
+    if not (npz_b.exists() and rep_b.exists()):
+        return root
+    if (
+        npz_a.read_bytes() == npz_b.read_bytes()
+        and rep_a.read_bytes() == rep_b.read_bytes()
+    ):
+        shutil.rmtree(root)
+        logging.info(
+            f"[mplfreeze] new run is identical to {prior.name}; removed "
+            f"redundant {root.name} and kept the existing folder."
+        )
+        return prior
+    return root
+
+
+def _update_latest_symlink(outdir: Path, base: str, target: Path) -> None:
+    """Point ``{base}_latest`` at ``target`` (a sibling folder).
+
+    Falls back to writing ``{base}_latest.txt`` containing the target name
+    on platforms / filesystems where symlinks are unavailable (notably
+    Windows without developer mode).
+    """
+    link = outdir / f"{base}_latest"
+    target_name = target.name
+    if link.is_symlink() or link.exists():
+        try:
+            link.unlink()
+        except OSError:
+            pass
+    try:
+        link.symlink_to(target_name, target_is_directory=True)
+    except OSError as e:
+        logging.warning(
+            f"[mplfreeze] could not create symlink {link.name} → "
+            f"{target_name} ({e}); writing {base}_latest.txt pointer instead."
+        )
+        (outdir / f"{base}_latest.txt").write_text(target_name + "\n")
+
+
+def _smoke_test_replot(
+    root: Path,
+    base: str,
+    pixel_diff: float = 0.05,
+    pixel_fraction: float = 0.005,
+) -> None:
+    """Run the generated replot in a subprocess and verify it reproduces the figure.
+
+    Raises RuntimeError if the replot fails to execute or fails to produce a
+    figure file. Logs a warning when more than ``pixel_fraction`` of pixels
+    differ from the canonical by more than ``pixel_diff`` (mpimg returns
+    floats in [0, 1]). The metric is fraction-based rather than max-based
+    because matplotlib's anti-aliasing flips a handful of pixels along line
+    edges from light to dark across runs — visually identical, but a strict
+    max_diff check would flag every reasonable freeze.
+    """
+    import matplotlib.image as mpimg
+
+    # Absolute paths matter: the replot subprocess chdir's to its own folder
+    # before resolving any path it received, so a relative check_png would
+    # be interpreted relative to the new cwd and fail.
+    root = root.resolve()
+    replot = root / f"replot_{base}.py"
+    canonical_png = root / f"{base}.png"
+    check_png = root / f".{base}.smoke.png"
+    check_png.unlink(missing_ok=True)
+
+    env = {**os.environ, "MPLBACKEND": "Agg"}
+    proc = subprocess.run(
+        [sys.executable, str(replot), "--out", str(check_png)],
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=300,
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"[mplfreeze] replot smoke-test FAILED: {replot.name} exited "
+            f"with code {proc.returncode}. The frozen run is NOT reproducible "
+            f"as-is.\n--- replot stderr ---\n{proc.stderr.rstrip()}"
+        )
+    if not check_png.exists():
+        raise RuntimeError(
+            f"[mplfreeze] replot smoke-test ran but produced no figure. The "
+            f"captured cell may close all figures before main() returns."
+        )
+
+    try:
+        canon = mpimg.imread(canonical_png)
+        check = mpimg.imread(check_png)
+    finally:
+        check_png.unlink(missing_ok=True)
+
+    if canon.shape != check.shape:
+        raise RuntimeError(
+            f"[mplfreeze] replot smoke-test: figure shape {check.shape} does "
+            f"not match canonical {canon.shape}."
+        )
+    diff = np.abs(canon.astype(float) - check.astype(float)).max(axis=2)
+    drift = float((diff > pixel_diff).sum() / diff.size)
+    if drift > pixel_fraction:
+        logging.warning(
+            f"[mplfreeze] replot smoke-test: {drift:.2%} of pixels differ "
+            f"from canonical by more than {pixel_diff} (threshold "
+            f"{pixel_fraction:.2%}). Replot runs but the figure is not "
+            f"pixel-faithful — likely non-deterministic content in the "
+            f"cell (timestamps, unseeded RNG, etc.)."
+        )
+    else:
+        logging.info(
+            f"[mplfreeze] replot smoke-test passed ({drift:.4%} of pixels "
+            f"differ; threshold {pixel_fraction:.2%})."
+        )
+
+
+def mplfreeze(line: str, cell: str):
+    """Freeze a matplotlib cell into a reproducible artifact bundle.
+
+    Captures the cell, saves the named variables into a compressed NPZ,
+    exports the figure as PDF/SVG/PNG, writes a standalone
+    ``replot_<name>.py`` that regenerates the figure from the NPZ,
+    snapshots the env (Python + package versions + git commit) into
+    ``<name>.meta.json``, then *runs* the generated replot in a
+    subprocess to confirm the bundle reproduces the figure before
+    declaring success.
+
+    Static checks before any I/O:
+        * Saved variable names that shadow replot-bound names
+          (``np``, ``plt``, ``lusca``, ``os``, ``Path``, ``data``) → warning.
+        * Free names referenced in the cell that aren't saved or
+          defined in-cell → RuntimeError.
+
+    Runtime checks after the cell executes:
+        * Multiple open figures (only ``plt.gcf()`` is saved) → warning.
+        * Replot subprocess exit ≠ 0 or missing figure → RuntimeError.
+        * Replotted PNG differs from the canonical by > 0.01 → warning
+          (not an error; non-determinism like timestamps or unseeded RNG
+          is the most common cause).
+
+    Args:
+        line: ``"name var1 var2 ... [--outdir DIR]"``. Default outdir
+            is ``docs/figs``.
+        cell: Python source of the cell to capture and execute.
+
+    Example:
+        %%mplfreeze trig_demo x_data sine cosine tanh
+        with plt.style.context("lusca"):
+            fig, axes = plt.subplots(1, 2, figsize=(7.0, 2.6), sharey=True)
+            axes[0].plot(x_data, sine); axes[0].plot(x_data, cosine)
+            axes[1].plot(sine, tanh, linestyle="--")
+            axes[1].plot(cosine, tanh, linestyle="--")
+
+    Output layout under ``<outdir>/<name>_<timestamp>/``::
+
+        <name>.npz             # saved variables
+        <name>.{pdf,svg,png}   # exported figure
+        <name>.meta.json       # env + git snapshot
+        replot_<name>.py       # standalone replot script
+
+    Raises:
+        RuntimeError: not in IPython/Jupyter; no figure produced; cell
+            references unsaved free names; or the replot smoke-test
+            fails (subprocess non-zero exit, missing figure, shape
+            mismatch).
+    """
+    import matplotlib.pyplot as plt
+    from IPython import get_ipython
+    from matplotlib.figure import Figure
+
+    ip = get_ipython()
+    if ip is None:
+        raise RuntimeError("%%mplfreeze must run inside IPython/Jupyter.")
+    ns = ip.user_ns
+
+    base, varnames, outdir = _parse_line(line)
+
+    # Validate the captured cell can run standalone before touching the disk.
+    _warn_on_reserved_varnames(varnames)
+    _check_free_names(cell, varnames)
+
+    # create run folder
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    root = Path(outdir) / f"{base}_{stamp}"
+    root.mkdir(parents=True, exist_ok=True)
+
+    # save arrays
+    info = _save_npz(root / f"{base}.npz", ns, varnames)
+    logging.info(f"Saved {len(varnames)} arrays → {root / f'{base}.npz'}")
+
+    # run the plotting cell now
+    ip.run_cell(cell)
+
+    # snapshot the single figure
+    fig = ns.get("fig", None)
+    if not isinstance(fig, Figure):
+        fig = plt.gcf()
+    if not isinstance(fig, Figure):
+        raise RuntimeError(
+            "[mplfreeze] No Matplotlib Figure found as 'fig' or current figure."
+        )
+    _warn_on_extra_figures(plt.get_fignums(), fig.number)
+    for ext in ("pdf", "svg", "png"):
+        fig.savefig(root / f"{base}.{ext}")
+    logging.info(f"Saved figure → {root}/{base}.{{pdf,svg,png}}")
+
+    # write replot script with explicit local bindings
+    _write_replot(root, cell, base, varnames, info)
+    logging.info(f"Wrote {root / f'replot_{base}.py'}")
+
+    # snapshot environment versions / git state for future debugging
+    _write_metadata(root, base, line, varnames, outdir)
+    logging.info(f"Wrote {root / f'{base}.meta.json'}")
+
+    # Smoke-test: actually exec the replot and confirm it produces the same
+    # figure. If freeze succeeds, the replot is *guaranteed* to work later.
+    _smoke_test_replot(root, base)
+
+    # Dedupe vs. the prior `{base}_latest` if the new run is identical, then
+    # update the symlink so callers can embed a stable path in their docs.
+    outdir_path = Path(outdir)
+    final_root = _maybe_dedupe_against_latest(outdir_path, base, root)
+    _update_latest_symlink(outdir_path, base, final_root)
+
+    logging.info(f"Run folder: {final_root} (latest → {base}_latest)")
+
+
+# ---- IPython extension hooks ----
+def load_ipython_extension(ip):
+    """Load the mplfreeze magic command into IPython.
+
+    Args:
+        ip: The IPython instance to register the magic command with.
+    """
+    mgr = ip.magics_manager.magics
+    if "cell" in mgr and "mplfreeze" in mgr["cell"]:
+        del mgr["cell"]["mplfreeze"]
+    ip.register_magic_function(mplfreeze, magic_kind="cell", magic_name="mplfreeze")
+
+
+def unload_ipython_extension(ip):
+    """Unload the mplfreeze magic command from IPython.
+
+    Args:
+        ip: The IPython instance to unregister the magic command from.
+    """
+    mgr = ip.magics_manager.magics
+    if "cell" in mgr and "mplfreeze" in mgr["cell"]:
+        del mgr["cell"]["mplfreeze"]

lusca-0.1.1/src/lusca/styles/lusca.mplstyle

@@ -0,0 +1,50 @@
+# === Figure ===
+figure.figsize: 3.5, 2.6 # compact, journal-friendly
+figure.dpi: 600
+
+# === Fonts ===
+font.family: DejaVu Sans # simple, consistent with your prefs
+font.size: 10 # between 8 and 16; scales well
+mathtext.fontset: dejavusans # TeX-like look without usetex
+axes.unicode_minus: True
+
+# === Axes & Lines ===
+axes.linewidth: 1.0 # not too heavy (compromise: 0.5 vs 3)
+axes.labelpad: 4
+grid.linewidth: 0.5
+
+# Clean, readable categorical cycle
+# axes.prop_cycle: cycler('color', ['0C5DA5', '00B945', 'FF9500', 'FF2C00', '845B97', '474747', '9e9e9e'])
+lines.linewidth: 1.5
+lines.markersize: 4
+lines.markeredgewidth: 0.8
+lines.markerfacecolor: w
+
+# === Ticks ===
+xtick.top: True
+ytick.right: True
+xtick.direction: in
+ytick.direction: in
+xtick.minor.visible: False
+ytick.minor.visible: False
+
+# Compromise sizes/widths (between big/heavy and tiny/light)
+xtick.major.size: 5
+xtick.major.width: 1.0
+xtick.minor.size: 3
+xtick.minor.width: 0.8
+ytick.major.size: 5
+ytick.major.width: 1.0
+ytick.minor.size: 3
+ytick.minor.width: 0.8
+
+# === Legend ===
+# Legend properties (base.mplstyle)
+legend.frameon: False
+legend.framealpha: 0
+legend.loc: lower center
+legend.handletextpad: 0.4
+
+# === Saving ===
+# savefig.bbox: tight
+savefig.pad_inches: 0.02

lusca-0.1.1/src/lusca.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: lusca
+Version: 0.1.1
+Summary: A Jupyter magic command for creating reproducible matplotlib figures.
+Author-email: Evan McKinney <evmckinney9@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/evmckinney9/lusca
+Project-URL: Repository, https://github.com/evmckinney9/lusca
+Project-URL: Issues, https://github.com/evmckinney9/lusca/issues
+Keywords: jupyter,ipython-magic,matplotlib,reproducibility,figures,scientific-plotting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: pylatexenc; extra == "dev"
+Requires-Dist: ipywidgets; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: format
+Requires-Dist: pre-commit; extra == "format"
+Requires-Dist: ruff; extra == "format"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# lusca
+
+![CI](https://github.com/evmckinney9/lusca/actions/workflows/ci.yml/badge.svg?branch=main) ![Python](https://img.shields.io/badge/python-3.12-blue.svg) ![Ruff](https://img.shields.io/badge/linter-ruff-green.svg)
+
+`lusca` is a Python library for creating reproducible matplotlib figures using Jupyter magic commands.
+
+Often, you want to use Jupyter for experiments but may not want to rerun the entire notebook to recreate plots. Additionally, saving data and figures is essential for artifact generation and reproducibility.
+
+## 📊 `%%mplfreeze` Command
+
+The `%%mplfreeze` magic command:
+- Captures the data used in your plots and saves it in a compressed NPZ file.
+- Automatically exports your figures in multiple useful formats.
+- Creates a minimal standalone script that reproduces the figure.
+- Snapshots Python/package versions and the git commit into `<name>.meta.json`.
+- Statically checks the cell for unsaved free names *before* writing anything,
+  then runs the generated replot in a subprocess to confirm the bundle
+  actually reproduces the figure — if `%%mplfreeze` succeeds, the replot is
+  guaranteed to work.
+- Leverages `lusca`'s built-in stylesheet.
+
+Once you're satisfied with your plot, add the `%%mplfreeze` command to the cell.
+```python
+%%mplfreeze <name> [vars ...] [--outdir DIR]
+```
+- `<name>`: Base name for outputs (folder + files).
+- `[vars ...]`: Variable names to save into the NPZ file.
+- `[--outdir DIR]`: (Optional) Parent output directory (default: `docs/figs`).
+
+### Example
+
+1. Import and load the magic command
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+import lusca
+%load_ext lusca
+```
+
+2. Some data
+```python
+x_data = np.linspace(-10, 10, 100)
+sine = np.sin(x_data)
+cosine = np.cos(x_data)
+```
+3. Plot + save
+```python
+%%mplfreeze trig_demo x_data sine cosine
+with plt.style.context("lusca"):
+    fig, ax = plt.subplots(1, 1, figsize=(3.5, 2.6), sharey=True)
+    ax.plot(x_data, sine, label="Sine")
+    ax.plot(x_data, cosine, label="Cosine")
+    plt.show()
+```
+
+An example notebook is available in `src/demo.ipynb`. The generated plots are saved in `docs/figs/` with the following structure:
+
+```
+name_stamp/
+    name.npz             # saved variables
+    name.pdf             # exported figure
+    name.png
+    name.svg
+    name.meta.json       # python/package versions + git commit
+    replot_name.py       # standalone replot script
+```
+## Installation
+
+Install `lusca` directly from GitHub:
+
+```bash
+pip install -e git+https://github.com/evmckinney9/lusca#egg=lusca
+```
+
+#### Note
+
+If you are using VS Code, you can set the workspace root as the default directory for saving figures by adding the following setting to your `settings.json` file. Otherwise, output paths will be relative to the notebook location.
+
+```json
+"jupyter.notebookFileRoot": "${workspaceFolder}"
+```

lusca-0.1.1/src/lusca.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/lusca/__init__.py
+src/lusca/mpl_freeze.py
+src/lusca.egg-info/PKG-INFO
+src/lusca.egg-info/SOURCES.txt
+src/lusca.egg-info/dependency_links.txt
+src/lusca.egg-info/requires.txt
+src/lusca.egg-info/top_level.txt
+src/lusca/styles/lusca.mplstyle

lusca-0.1.1/src/lusca.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lusca-0.1.1/src/lusca.egg-info/requires.txt

@@ -0,0 +1,15 @@
+numpy
+matplotlib
+
+[dev]
+ipykernel
+pylatexenc
+ipywidgets
+pre-commit
+
+[format]
+pre-commit
+ruff
+
+[test]
+pytest

lusca-0.1.1/src/lusca.egg-info/top_level.txt

@@ -0,0 +1 @@
+lusca