stdplot 0.0.1__tar.gz

stdplot-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gabriel Lauzier
+
+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.

stdplot-0.0.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: stdplot
+Version: 0.0.1
+Summary: A standardize wrapper around `matplotlib` targetting a variety of canvases.
+Author-email: G-Lauz <gabriel.lauzier@usherbrooke.ca>
+License-Expression: MIT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Framework :: Matplotlib
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib<3.13,>=3.11.2
+Requires-Dist: scienceplots>=2.2
+Provides-Extra: qt
+Requires-Dist: PySide6; extra == "qt"
+Provides-Extra: notebook
+Requires-Dist: ipython; extra == "notebook"
+Provides-Extra: all
+Requires-Dist: PySide6; extra == "all"
+Requires-Dist: ipython; extra == "all"
+Dynamic: license-file
+
+# Standard Plot
+A standardized wrapper around `matplotlib` targeting a variety of canvases.
+
+## Installation
+Default installation is via `pip`:
+```bash
+pip install stdplot
+```
+For notebook and GUI support, install the optional dependencies:
+```bash
+pip install stdplot[notebook,qt] # or [all]
+```
+
+
+## Disclaimer
+This repository originated from a personal script I've developped on my own. Now it is rewriten heavily using `Claude` based on that previous work. It is mostly a project use by me as introduction and exploration of the capabilities of such tools in my workflow.

stdplot-0.0.1/README.md

@@ -0,0 +1,16 @@
+# Standard Plot
+A standardized wrapper around `matplotlib` targeting a variety of canvases.
+
+## Installation
+Default installation is via `pip`:
+```bash
+pip install stdplot
+```
+For notebook and GUI support, install the optional dependencies:
+```bash
+pip install stdplot[notebook,qt] # or [all]
+```
+
+
+## Disclaimer
+This repository originated from a personal script I've developped on my own. Now it is rewriten heavily using `Claude` based on that previous work. It is mostly a project use by me as introduction and exploration of the capabilities of such tools in my workflow.

stdplot-0.0.1/VERSION

@@ -0,0 +1 @@
+0.0.1

stdplot-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stdplot"
+authors = [
+    { name="G-Lauz", email="gabriel.lauzier@usherbrooke.ca" },
+]
+description = "A standardize wrapper around `matplotlib` targetting a variety of canvases."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Framework :: Matplotlib",
+  "Operating System :: OS Independent",
+]
+dynamic = ["version"]
+dependencies = ["matplotlib>=3.11.2,<3.13", "scienceplots>=2.2"]
+
+[project.optional-dependencies]
+qt = ["PySide6"]
+notebook = ["ipython"]
+all = ["PySide6", "ipython"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["stdplot*"]
+
+[tool.setuptools.package-data]
+stdplot = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.pyright]
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# tests/stdplot/ has no __init__.py; importlib mode keeps it from shadowing the package.
+addopts = "--import-mode=importlib"

stdplot-0.0.1/setup.cfg

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

stdplot-0.0.1/src/stdplot/__init__.py

@@ -0,0 +1,47 @@
+"""Publication-ready matplotlib figures, drawn once and exported to every target."""
+
+# Importing scienceplots registers its styles, which the default Style names.
+import scienceplots
+
+from stdplot.application import (
+    IEEE_PGF,
+    SCREEN,
+    AxesGrid,
+    Config,
+    Display,
+    Format,
+    LatexNotFoundError,
+    LatexSettings,
+    Layout,
+    MissingDependencyError,
+    MissingOutputError,
+    Size,
+    StdplotError,
+    Style,
+    Target,
+    UnknownStyleError,
+    ieee_pgf,
+)
+from stdplot.presentation.api import figure, plot
+
+__all__ = [
+    "IEEE_PGF",
+    "SCREEN",
+    "AxesGrid",
+    "Config",
+    "Display",
+    "Format",
+    "LatexNotFoundError",
+    "LatexSettings",
+    "Layout",
+    "MissingDependencyError",
+    "MissingOutputError",
+    "Size",
+    "StdplotError",
+    "Style",
+    "Target",
+    "UnknownStyleError",
+    "figure",
+    "ieee_pgf",
+    "plot",
+]

stdplot-0.0.1/src/stdplot/application/__init__.py

@@ -0,0 +1,44 @@
+from stdplot.domain.config import Config, PlotRequest
+from stdplot.domain.errors import (
+    LatexNotFoundError,
+    MissingDependencyError,
+    MissingOutputError,
+    StdplotError,
+    UnknownStyleError,
+)
+from stdplot.domain.format import Display, Format, Layout
+from stdplot.domain.style import LatexSettings, Style
+from stdplot.domain.target import IEEE_PGF, SCREEN, Size, Target, ieee_pgf
+
+from .axes import AxesGrid
+from .environment import Environment, detect
+from .exporter import export
+from .session import Displayer, check_styles, resolve_style, session
+
+__all__ = [
+    "IEEE_PGF",
+    "SCREEN",
+    "AxesGrid",
+    "Config",
+    "Display",
+    "Displayer",
+    "Environment",
+    "Format",
+    "LatexNotFoundError",
+    "LatexSettings",
+    "Layout",
+    "MissingDependencyError",
+    "MissingOutputError",
+    "PlotRequest",
+    "Size",
+    "StdplotError",
+    "Style",
+    "Target",
+    "UnknownStyleError",
+    "check_styles",
+    "detect",
+    "export",
+    "ieee_pgf",
+    "resolve_style",
+    "session",
+]

stdplot-0.0.1/src/stdplot/application/axes.py

@@ -0,0 +1,65 @@
+"""Typed access to the grid of axes of a figure."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing
+
+if typing.TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+
+@dataclasses.dataclass(frozen=True)
+class AxesGrid:
+    """The axes of a figure, by row then column.
+
+    Attributes:
+        rows: One tuple per row, holding the axes of each column.
+    """
+
+    rows: tuple[tuple[Axes, ...], ...]
+
+    @classmethod
+    def from_figure(cls, figure: Figure, nrows: int, ncols: int) -> AxesGrid:
+        """Add an `nrows` by `ncols` grid of axes to the figure.
+
+        Args:
+            figure: Figure the axes are added to.
+            nrows: Number of rows.
+            ncols: Number of columns.
+
+        Returns:
+            The grid of the added axes.
+        """
+        # squeeze=False keeps the array 2-D even when nrows or ncols is 1.
+        array = figure.subplots(nrows, ncols, squeeze=False)
+        return cls(tuple(tuple(row) for row in array))
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Number of rows and columns."""
+        return (len(self.rows), len(self.rows[0]))
+
+    @property
+    def flat(self) -> tuple[Axes, ...]:
+        """Every axes, row by row."""
+        return tuple(axes for row in self.rows for axes in row)
+
+    @property
+    def single(self) -> Axes:
+        """The only axes of a 1x1 grid.
+
+        Raises:
+            ValueError: The grid holds more than one axes.
+        """
+        is_single = self.shape == (1, 1)
+        if not is_single:
+            nrows, ncols = self.shape
+            raise ValueError(f"The grid holds {nrows}x{ncols} axes, not a single one.")
+        return self.rows[0][0]
+
+    def __getitem__(self, position: tuple[int, int]) -> Axes:
+        """Return the axes at `(row, column)`."""
+        row, col = position
+        return self.rows[row][col]

stdplot-0.0.1/src/stdplot/application/environment.py

@@ -0,0 +1,44 @@
+"""Detection of what the running process can do."""
+
+from __future__ import annotations
+
+import dataclasses
+import shutil
+
+try:
+    import IPython
+except ImportError:  # stdplot[notebook] is not installed, so no kernel can be running
+    IPython = None
+
+
+@dataclasses.dataclass(frozen=True)
+class Environment:
+    """Capabilities of the running process that change how figures are drawn and shown.
+
+    Attributes:
+        latex_available: A `latex` binary is on the PATH.
+        in_notebook: The process is a Jupyter kernel, so figures can be shown inline.
+    """
+
+    latex_available: bool
+    in_notebook: bool
+
+
+def detect() -> Environment:
+    """Inspect the running process.
+
+    Returns:
+        The detected environment.
+    """
+    return Environment(
+        latex_available=shutil.which("latex") is not None,
+        in_notebook=_in_notebook(),
+    )
+
+
+def _in_notebook() -> bool:
+    if IPython is None:
+        return False
+    shell = IPython.get_ipython()
+    # A terminal IPython also has a shell, but only a kernel renders inline images.
+    return shell is not None and "IPKernelApp" in shell.config

stdplot-0.0.1/src/stdplot/application/exporter.py

@@ -0,0 +1,45 @@
+"""Export of a figure to its targets."""
+
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    import pathlib
+
+    from matplotlib.figure import Figure
+
+    from stdplot.domain.target import Target
+
+
+def export(
+    figure: Figure, targets: tuple[Target, ...], output_dir: pathlib.Path, name: str
+) -> tuple[pathlib.Path, ...]:
+    """Write the figure once per target, resized to each target's size.
+
+    The figure gets its size back afterwards, so exporting does not change what is
+    shown next.
+
+    Args:
+        figure: Figure to export.
+        targets: Files to write.
+        output_dir: Directory the files are written to; created when missing.
+        name: Name of the figure, used as the file stem.
+
+    Returns:
+        The written paths, in the order of the targets.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+    width, height = figure.get_size_inches()
+    try:
+        return tuple(
+            _write(figure, target, output_dir / target.filename(name)) for target in targets
+        )
+    finally:
+        figure.set_size_inches(width, height)
+
+
+def _write(figure: Figure, target: Target, path: pathlib.Path) -> pathlib.Path:
+    figure.set_size_inches(target.size.as_tuple())
+    figure.savefig(path, format=target.format.value, dpi=target.dpi)
+    return path

stdplot-0.0.1/src/stdplot/application/session.py

@@ -0,0 +1,114 @@
+"""The drawing session: style a figure, hand it to the caller, then export and show it."""
+
+from __future__ import annotations
+
+import contextlib
+import typing
+import warnings
+
+import matplotlib.style
+from matplotlib.figure import Figure
+
+from stdplot.domain.errors import LatexNotFoundError, UnknownStyleError
+
+from .axes import AxesGrid
+from .exporter import export
+
+if typing.TYPE_CHECKING:
+    import collections.abc
+
+    from stdplot.domain.config import PlotRequest
+    from stdplot.domain.style import Style
+
+    from .environment import Environment
+
+
+class Displayer(typing.Protocol):
+    """Shows a finished figure to the user."""
+
+    def show(self, figure: Figure, title: str) -> None:
+        """Show the figure.
+
+        Args:
+            figure: Figure to show.
+            title: Title of the figure, such as its name.
+        """
+
+
+def resolve_style(request: PlotRequest, environment: Environment) -> Style:
+    """Pick the style to draw with, falling back to mathtext when LaTeX is missing.
+
+    Args:
+        request: The figure to draw.
+        environment: What the running process can do.
+
+    Returns:
+        The configured style, or a copy without LaTeX when it is not installed.
+
+    Raises:
+        LatexNotFoundError: A target needs LaTeX and it is not installed.
+    """
+    style = request.config.style
+    if environment.latex_available:
+        return style
+    if request.needs_latex:
+        raise LatexNotFoundError
+    if not style.latex.usetex:
+        return style
+    warnings.warn(
+        "LaTeX is not installed; rendering text with matplotlib's mathtext instead.",
+        stacklevel=2,
+    )
+    return style.without_latex()
+
+
+def check_styles(style: Style) -> None:
+    """Check that matplotlib knows every style name.
+
+    Args:
+        style: The style to check.
+
+    Raises:
+        UnknownStyleError: Some names are not registered with matplotlib.
+    """
+    unknown = tuple(name for name in style.names if name not in matplotlib.style.available)
+    has_unknown = bool(unknown)
+    if has_unknown:
+        raise UnknownStyleError(unknown)
+
+
+@contextlib.contextmanager
+def session(
+    request: PlotRequest, displayer: Displayer, environment: Environment
+) -> collections.abc.Iterator[tuple[Figure, AxesGrid]]:
+    """Draw one figure under the configured style, then export and show it.
+
+    The style wraps the caller's drawing, not only the export, because matplotlib reads
+    fonts and LaTeX settings when each artist is created. An error raised while drawing
+    skips both the export and the display.
+
+    Args:
+        request: The figure to draw.
+        displayer: Shows the figure once drawn, when the request asks for it.
+        environment: What the running process can do.
+
+    Yields:
+        The figure, sized to the preview target, and its grid of axes.
+
+    Raises:
+        LatexNotFoundError: A target needs LaTeX and it is not installed.
+        UnknownStyleError: Some style names are not registered with matplotlib.
+    """
+    style = resolve_style(request, environment)
+    check_styles(style)
+    config = request.config
+    with matplotlib.style.context(style.to_rc_list()):
+        # The ieee style raises figure.dpi to 600; the preview dpi keeps windows usable.
+        figure = Figure(figsize=config.preview.size.as_tuple(), dpi=config.preview.dpi)
+        figure.set_layout_engine(config.layout.value)
+        grid = AxesGrid.from_figure(figure, request.nrows, request.ncols)
+        yield figure, grid
+        if request.save:
+            export(figure, config.targets, request.output_dir, request.name)
+        if request.show:
+            displayer.show(figure, request.name)

stdplot-0.0.1/src/stdplot/domain/config.py

@@ -0,0 +1,84 @@
+"""Configuration of how figures are drawn, exported and shown."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing
+
+from .errors import MissingOutputError
+from .format import Display, Layout
+from .style import Style
+from .target import IEEE_PGF, SCREEN, Target
+
+if typing.TYPE_CHECKING:
+    import pathlib
+
+
+@dataclasses.dataclass(frozen=True)
+class Config:
+    """Settings shared by every figure drawn with it.
+
+    Attributes:
+        style: Style applied while the figure is drawn.
+        targets: Files written when saving.
+        preview: Size, resolution and format the figure is drawn and shown at.
+        output_dir: Directory the targets are written to; required when saving.
+        layout: Layout engine re-run before every export.
+        display: Where a shown figure appears.
+    """
+
+    style: Style = dataclasses.field(default_factory=Style)
+    targets: tuple[Target, ...] = (IEEE_PGF, SCREEN)
+    preview: Target = SCREEN
+    output_dir: pathlib.Path | None = None
+    layout: Layout = Layout.TIGHT
+    display: Display = Display.AUTO
+
+
+@dataclasses.dataclass(frozen=True)
+class PlotRequest:
+    """One figure to draw: its config, name, axes grid and what happens once it is drawn."""
+
+    config: Config
+    name: str
+    nrows: int
+    ncols: int
+    save: bool
+    show: bool
+
+    def __post_init__(self) -> None:
+        """Reject requests that cannot be drawn or saved.
+
+        Raises:
+            ValueError: The name is empty or the grid has fewer than one row or column.
+            MissingOutputError: Saving without an output directory or without targets.
+        """
+        has_name = bool(self.name)
+        if not has_name:
+            raise ValueError("A figure needs a non-empty name.")
+
+        has_axes = self.nrows >= 1 and self.ncols >= 1
+        if not has_axes:
+            raise ValueError(f"A figure needs at least 1x1 axes, got {self.nrows}x{self.ncols}.")
+
+        if self.save and self.config.output_dir is None:
+            raise MissingOutputError("an output_dir")
+        if self.save and not self.config.targets:
+            raise MissingOutputError("at least one target")
+
+    @property
+    def output_dir(self) -> pathlib.Path:
+        """Directory the targets are written to.
+
+        Raises:
+            MissingOutputError: The config has no output directory.
+        """
+        output_dir = self.config.output_dir
+        if output_dir is None:
+            raise MissingOutputError("an output_dir")
+        return output_dir
+
+    @property
+    def needs_latex(self) -> bool:
+        """Whether drawing this request needs a LaTeX installation."""
+        return self.save and any(target.requires_latex for target in self.config.targets)

stdplot-0.0.1/src/stdplot/domain/errors.py

@@ -0,0 +1,61 @@
+"""Exceptions raised by stdplot."""
+
+from __future__ import annotations
+
+
+class StdplotError(Exception):
+    """Base class of every error raised by stdplot."""
+
+
+class LatexNotFoundError(StdplotError):
+    """A target needs LaTeX, but no LaTeX installation is on the PATH."""
+
+    def __init__(self) -> None:
+        """Build the message explaining why LaTeX is needed."""
+        super().__init__(
+            "A PGF target needs a LaTeX installation, but `latex` is not on the PATH. "
+            "Install a TeX distribution or remove the PGF targets from the config."
+        )
+
+
+class MissingOutputError(StdplotError, ValueError):
+    """Saving was requested, but the config does not say where or as what."""
+
+    def __init__(self, missing: str) -> None:
+        """Build the message naming the missing setting.
+
+        Args:
+            missing: What the config lacks, such as "an output_dir".
+        """
+        super().__init__(f"Saving a figure needs {missing} in the config.")
+
+
+class MissingDependencyError(StdplotError, ImportError):
+    """A feature needs an optional dependency that is not installed."""
+
+    def __init__(self, extra: str) -> None:
+        """Build the message naming the extra to install.
+
+        Args:
+            extra: Name of the stdplot extra providing the dependency, such as "qt".
+        """
+        super().__init__(
+            f'This feature needs an optional dependency: pip install "stdplot[{extra}]"'
+        )
+        self.extra = extra
+
+
+class UnknownStyleError(StdplotError):
+    """A style name is not registered with matplotlib."""
+
+    def __init__(self, names: tuple[str, ...]) -> None:
+        """Build the message listing the unknown styles.
+
+        Args:
+            names: The style names matplotlib does not know.
+        """
+        super().__init__(
+            f"Unknown matplotlib style(s): {', '.join(names)}. "
+            "See matplotlib.style.available for the registered names."
+        )
+        self.names = names

stdplot-0.0.1/src/stdplot/domain/format.py

@@ -0,0 +1,30 @@
+"""Enumerations of the export formats, layout engines and display backends."""
+
+from __future__ import annotations
+
+import enum
+
+
+class Format(enum.Enum):
+    """File format of an export; the value is both the extension and matplotlib's name."""
+
+    PGF = "pgf"
+    SVG = "svg"
+    PNG = "png"
+    PDF = "pdf"
+
+
+class Layout(enum.Enum):
+    """Layout engine re-run before every export; the value is matplotlib's name."""
+
+    TIGHT = "tight"
+    CONSTRAINED = "constrained"
+    NONE = "none"
+
+
+class Display(enum.Enum):
+    """Where a shown figure appears."""
+
+    AUTO = "auto"
+    NOTEBOOK = "notebook"
+    QT = "qt"

stdplot-0.0.1/src/stdplot/domain/style.py

@@ -0,0 +1,49 @@
+"""The visual style applied while a figure is drawn."""
+
+from __future__ import annotations
+
+import dataclasses
+
+NO_LATEX_STYLE = "no-latex"
+
+
+@dataclasses.dataclass(frozen=True)
+class LatexSettings:
+    """LaTeX rendering settings, applied on top of the named styles."""
+
+    texsystem: str = "pdflatex"
+    font_family: str = "serif"
+    usetex: bool = True
+    rcfonts: bool = False
+
+    def to_rc(self) -> dict[str, object]:
+        """Translate the settings to matplotlib rcParams."""
+        return {
+            "pgf.texsystem": self.texsystem,
+            "font.family": self.font_family,
+            "text.usetex": self.usetex,
+            "pgf.rcfonts": self.rcfonts,
+            # The science style crops exports to a tight bbox, which would make a PGF
+            # narrower than the width its target was sized to fit.
+            "savefig.bbox": "standard",
+        }
+
+
+@dataclasses.dataclass(frozen=True)
+class Style:
+    """Named matplotlib styles plus the LaTeX settings layered over them."""
+
+    names: tuple[str, ...] = ("science", "grid", "ieee")
+    latex: LatexSettings = LatexSettings()
+
+    def without_latex(self) -> Style:
+        """Return a copy that renders text with matplotlib's mathtext instead of LaTeX."""
+        return dataclasses.replace(
+            self,
+            names=(*self.names, NO_LATEX_STYLE),
+            latex=dataclasses.replace(self.latex, usetex=False),
+        )
+
+    def to_rc_list(self) -> list[str | dict[str, object]]:
+        """Return the style in the form `matplotlib.style.context` accepts."""
+        return [*self.names, self.latex.to_rc()]

stdplot-0.0.1/src/stdplot/domain/target.py

@@ -0,0 +1,87 @@
+"""Export targets: what format a figure is written to, and at what size."""
+
+from __future__ import annotations
+
+import dataclasses
+
+from .format import Format
+
+IEEE_COLUMN_WIDTH_IN = 3.40067
+
+
+@dataclasses.dataclass(frozen=True)
+class Size:
+    """Physical size of a figure, in inches."""
+
+    width: float
+    height: float
+
+    def __post_init__(self) -> None:
+        """Reject sizes matplotlib cannot draw.
+
+        Raises:
+            ValueError: The width or the height is not positive.
+        """
+        is_positive = self.width > 0 and self.height > 0
+        if not is_positive:
+            raise ValueError(f"A size must be positive, got {self.width} x {self.height} in.")
+
+    @classmethod
+    def from_width(cls, width: float, aspect: float) -> Size:
+        """Build a size from its width and its height-to-width ratio.
+
+        Args:
+            width: Width, in inches.
+            aspect: Height divided by width.
+
+        Returns:
+            The size.
+        """
+        return cls(width, width * aspect)
+
+    def as_tuple(self) -> tuple[float, float]:
+        """Return the size as the `(width, height)` pair matplotlib expects."""
+        return (self.width, self.height)
+
+
+@dataclasses.dataclass(frozen=True)
+class Target:
+    """One file a figure is exported to."""
+
+    format: Format
+    size: Size
+    dpi: int = 300
+
+    @property
+    def requires_latex(self) -> bool:
+        """Whether writing this target needs a LaTeX installation."""
+        return self.format is Format.PGF
+
+    def filename(self, name: str) -> str:
+        """Name the file this target writes for a figure.
+
+        Args:
+            name: Name of the figure.
+
+        Returns:
+            The file name, with the format's extension.
+        """
+        return f"{name}.{self.format.value}"
+
+
+def ieee_pgf(scale: float = 1.0, aspect: float = 6 / 8, dpi: int = 300) -> Target:
+    """Build a PGF target sized to a fraction of an IEEE column.
+
+    Args:
+        scale: Fraction of the column width the figure spans.
+        aspect: Height divided by width.
+        dpi: Resolution of the raster elements embedded in the PGF.
+
+    Returns:
+        The PGF target.
+    """
+    return Target(Format.PGF, Size.from_width(IEEE_COLUMN_WIDTH_IN * scale, aspect), dpi)
+
+
+IEEE_PGF = ieee_pgf()
+SCREEN = Target(Format.SVG, Size(8.0, 6.0), dpi=100)

stdplot-0.0.1/src/stdplot/presentation/api.py

@@ -0,0 +1,204 @@
+"""The public drawing API: the `figure` context manager and the `plot` decorator.
+
+Without `nrows` and `ncols`, the drawing code receives the figure's single `Axes`.
+With either of them it receives an `AxesGrid`, even for a 1x1 grid, so the type of the
+axes follows from the call alone.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import typing
+
+from stdplot.application import Config, PlotRequest, detect, session
+
+from .display import select_displayer
+
+if typing.TYPE_CHECKING:
+    import collections.abc
+
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+    from stdplot.application import AxesGrid
+
+P = typing.ParamSpec("P")
+R = typing.TypeVar("R")
+
+DEFAULT_CONFIG = Config()
+
+
+@typing.overload
+def figure(
+    name: str,
+    *,
+    nrows: None = None,
+    ncols: None = None,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> contextlib.AbstractContextManager[tuple[Figure, Axes]]: ...
+@typing.overload
+def figure(
+    name: str,
+    *,
+    nrows: int,
+    ncols: int | None = None,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> contextlib.AbstractContextManager[tuple[Figure, AxesGrid]]: ...
+@typing.overload
+def figure(
+    name: str,
+    *,
+    nrows: None = None,
+    ncols: int,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> contextlib.AbstractContextManager[tuple[Figure, AxesGrid]]: ...
+def figure(
+    name: str,
+    *,
+    nrows: int | None = None,
+    ncols: int | None = None,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> contextlib.AbstractContextManager[tuple[Figure, Axes | AxesGrid]]:
+    """Open a styled figure, then export and show it when the block exits.
+
+    Args:
+        name: Name of the figure, used as the file stem and the window title.
+        nrows: Number of rows of axes; set it or `ncols` to receive an `AxesGrid`.
+        ncols: Number of columns of axes; set it or `nrows` to receive an `AxesGrid`.
+        config: Style, targets, preview and display of the figure.
+        save: Write the figure to every target of the config on exit.
+        show: Display the figure on exit.
+
+    Returns:
+        A context manager yielding the figure and its axes.
+
+    Raises:
+        ValueError: The name is empty or the grid has fewer than one row or column.
+        MissingOutputError: Saving without an output directory or without targets.
+    """
+    request = _request(name, nrows, ncols, config, save=save, show=show)
+    return _draw(request, single=nrows is None and ncols is None)
+
+
+@typing.overload
+def plot(
+    name: str | None = None,
+    *,
+    nrows: None = None,
+    ncols: None = None,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> collections.abc.Callable[
+    [collections.abc.Callable[typing.Concatenate[Figure, Axes, P], R]],
+    collections.abc.Callable[P, R],
+]: ...
+@typing.overload
+def plot(
+    name: str | None = None,
+    *,
+    nrows: int,
+    ncols: int | None = None,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> collections.abc.Callable[
+    [collections.abc.Callable[typing.Concatenate[Figure, AxesGrid, P], R]],
+    collections.abc.Callable[P, R],
+]: ...
+@typing.overload
+def plot(
+    name: str | None = None,
+    *,
+    nrows: None = None,
+    ncols: int,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> collections.abc.Callable[
+    [collections.abc.Callable[typing.Concatenate[Figure, AxesGrid, P], R]],
+    collections.abc.Callable[P, R],
+]: ...
+def plot(
+    name: str | None = None,
+    *,
+    nrows: int | None = None,
+    ncols: int | None = None,
+    config: Config = DEFAULT_CONFIG,
+    save: bool = False,
+    show: bool = True,
+) -> collections.abc.Callable[
+    [collections.abc.Callable[typing.Concatenate[Figure, Axes | AxesGrid, P], R]],
+    collections.abc.Callable[P, R],
+]:
+    """Make a drawing function open, export and show its own figure on every call.
+
+    The function receives the figure and its axes ahead of its own arguments. Calling
+    the decorated function draws the figure and returns what the function returns.
+
+    Args:
+        name: Name of the figure; defaults to the name of the function.
+        nrows: Number of rows of axes; set it or `ncols` to receive an `AxesGrid`.
+        ncols: Number of columns of axes; set it or `nrows` to receive an `AxesGrid`.
+        config: Style, targets, preview and display of the figure.
+        save: Write the figure to every target of the config after each call.
+        show: Display the figure after each call.
+
+    Returns:
+        The decorator. It raises `ValueError` or `MissingOutputError` when applied, for
+        the same reasons as `figure`.
+    """
+    single = nrows is None and ncols is None
+
+    def decorator(
+        func: collections.abc.Callable[typing.Concatenate[Figure, Axes | AxesGrid, P], R],
+    ) -> collections.abc.Callable[P, R]:
+        figure_name = func.__name__ if name is None else name
+        request = _request(figure_name, nrows, ncols, config, save=save, show=show)
+
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            with _draw(request, single=single) as (fig, axes):
+                return func(fig, axes, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def _request(
+    name: str,
+    nrows: int | None,
+    ncols: int | None,
+    config: Config,
+    *,
+    save: bool,
+    show: bool,
+) -> PlotRequest:
+    return PlotRequest(
+        config=config,
+        name=name,
+        nrows=1 if nrows is None else nrows,
+        ncols=1 if ncols is None else ncols,
+        save=save,
+        show=show,
+    )
+
+
+@contextlib.contextmanager
+def _draw(
+    request: PlotRequest, *, single: bool
+) -> collections.abc.Iterator[tuple[Figure, Axes | AxesGrid]]:
+    environment = detect()
+    displayer = select_displayer(request.config.display, environment, request.config.preview)
+    with session(request, displayer, environment) as (fig, grid):
+        yield (fig, grid.single) if single else (fig, grid)

stdplot-0.0.1/src/stdplot/presentation/display/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import typing
+
+from stdplot.application import Display
+
+from .notebook import NotebookDisplayer
+from .qt import QtDisplayer
+
+if typing.TYPE_CHECKING:
+    from stdplot.application import Displayer, Environment, Target
+
+
+def select_displayer(display: Display, environment: Environment, preview: Target) -> Displayer:
+    """Pick where a shown figure appears, resolving `Display.AUTO` from the environment.
+
+    Args:
+        display: The requested display.
+        environment: What the running process can do.
+        preview: Format and resolution an inline figure is rendered with.
+
+    Returns:
+        The notebook displayer when asked for or inside a Jupyter kernel, the Qt
+        displayer otherwise.
+    """
+    is_auto_notebook = display is Display.AUTO and environment.in_notebook
+    use_notebook = display is Display.NOTEBOOK or is_auto_notebook
+    if use_notebook:
+        return NotebookDisplayer(preview)
+    return QtDisplayer()

stdplot-0.0.1/src/stdplot/presentation/display/notebook.py

@@ -0,0 +1,53 @@
+"""Inline display of figures in a Jupyter notebook."""
+
+from __future__ import annotations
+
+import dataclasses
+import io
+import typing
+
+from stdplot.application import Format, MissingDependencyError
+
+if typing.TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+    from stdplot.application import Target
+
+try:
+    import IPython.display
+except ImportError:  # stdplot[notebook] is not installed
+    IPython = None
+
+
+@dataclasses.dataclass(frozen=True)
+class NotebookDisplayer:
+    """Shows figures inline, in the output of the running cell.
+
+    Attributes:
+        target: Format and resolution the figure is rendered with.
+    """
+
+    target: Target
+
+    def show(self, figure: Figure, title: str) -> None:
+        """Render the figure and display it below the cell.
+
+        Args:
+            figure: Figure to show.
+            title: Unused, since an inline figure has no window to title.
+
+        Raises:
+            MissingDependencyError: IPython is not installed.
+        """
+        if IPython is None:
+            raise MissingDependencyError("notebook")
+        buffer = io.BytesIO()
+        figure.savefig(buffer, format=self.target.format.value, dpi=self.target.dpi)
+        data = buffer.getvalue()
+        is_svg = self.target.format is Format.SVG
+        image = (
+            IPython.display.SVG(data=data)
+            if is_svg
+            else IPython.display.Image(data=data, format=self.target.format.value)
+        )
+        IPython.display.display(image)

stdplot-0.0.1/src/stdplot/presentation/display/qt.py

@@ -0,0 +1,44 @@
+"""Display of figures in a Qt window with the matplotlib toolbar."""
+
+from __future__ import annotations
+
+import typing
+
+from stdplot.application import MissingDependencyError
+
+if typing.TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+try:
+    from matplotlib.backends import backend_qt, backend_qtagg
+except ImportError:  # no Qt binding is installed: stdplot[qt] is missing
+    backend_qt = None
+    backend_qtagg = None
+
+
+class QtDisplayer:
+    """Shows figures in a Qt window, blocking until the window is closed."""
+
+    def show(self, figure: Figure, title: str) -> None:
+        """Open a window on the figure and run the Qt event loop until it closes.
+
+        Args:
+            figure: Figure to show.
+            title: Title of the window.
+
+        Raises:
+            MissingDependencyError: No Qt binding is installed.
+        """
+        if backend_qt is None or backend_qtagg is None:
+            raise MissingDependencyError("qt")
+        previous_canvas = figure.canvas
+        canvas = backend_qtagg.FigureCanvasQTAgg(figure)
+        try:
+            manager = backend_qt.FigureManagerQT(canvas, 1)
+            manager.set_window_title(title)
+            manager.show()
+            backend_qt.FigureManagerQT.start_main_loop()
+        finally:
+            # The Qt canvas is destroyed with its window; putting the previous canvas
+            # back keeps the figure drawable and savable after the window is closed.
+            figure.set_canvas(previous_canvas)

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

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: stdplot
+Version: 0.0.1
+Summary: A standardize wrapper around `matplotlib` targetting a variety of canvases.
+Author-email: G-Lauz <gabriel.lauzier@usherbrooke.ca>
+License-Expression: MIT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Framework :: Matplotlib
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib<3.13,>=3.11.2
+Requires-Dist: scienceplots>=2.2
+Provides-Extra: qt
+Requires-Dist: PySide6; extra == "qt"
+Provides-Extra: notebook
+Requires-Dist: ipython; extra == "notebook"
+Provides-Extra: all
+Requires-Dist: PySide6; extra == "all"
+Requires-Dist: ipython; extra == "all"
+Dynamic: license-file
+
+# Standard Plot
+A standardized wrapper around `matplotlib` targeting a variety of canvases.
+
+## Installation
+Default installation is via `pip`:
+```bash
+pip install stdplot
+```
+For notebook and GUI support, install the optional dependencies:
+```bash
+pip install stdplot[notebook,qt] # or [all]
+```
+
+
+## Disclaimer
+This repository originated from a personal script I've developped on my own. Now it is rewriten heavily using `Claude` based on that previous work. It is mostly a project use by me as introduction and exploration of the capabilities of such tools in my workflow.

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

@@ -0,0 +1,27 @@
+LICENSE
+README.md
+VERSION
+pyproject.toml
+src/stdplot/__init__.py
+src/stdplot/py.typed
+src/stdplot.egg-info/PKG-INFO
+src/stdplot.egg-info/SOURCES.txt
+src/stdplot.egg-info/dependency_links.txt
+src/stdplot.egg-info/requires.txt
+src/stdplot.egg-info/top_level.txt
+src/stdplot/application/__init__.py
+src/stdplot/application/axes.py
+src/stdplot/application/environment.py
+src/stdplot/application/exporter.py
+src/stdplot/application/session.py
+src/stdplot/domain/__init__.py
+src/stdplot/domain/config.py
+src/stdplot/domain/errors.py
+src/stdplot/domain/format.py
+src/stdplot/domain/style.py
+src/stdplot/domain/target.py
+src/stdplot/presentation/__init__.py
+src/stdplot/presentation/api.py
+src/stdplot/presentation/display/__init__.py
+src/stdplot/presentation/display/notebook.py
+src/stdplot/presentation/display/qt.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,12 @@
+matplotlib<3.13,>=3.11.2
+scienceplots>=2.2
+
+[all]
+PySide6
+ipython
+
+[notebook]
+ipython
+
+[qt]
+PySide6

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

@@ -0,0 +1 @@
+stdplot