gsplot 0.2.0__tar.gz → 0.4.0__tar.gz

gsplot-0.4.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: gsplot
+Version: 0.4.0
+Summary: Concise publication-quality scientific plotting built on Matplotlib
+License-Expression: MIT
+License-File: LICENSE
+Keywords: matplotlib,plotting,publication,scientific
+Author: Giordano Mattoni
+Maintainer: Soichiro Yamane
+Requires-Python: >=3.10
+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: Programming Language :: Python :: 3.14
+Requires-Dist: matplotlib (>=3.9.0)
+Requires-Dist: numpy (>=1.26.4)
+Project-URL: Documentation, https://soichiroyamane.github.io/gsplot/stable/
+Project-URL: Homepage, https://soichiroyamane.github.io/gsplot/
+Project-URL: Issues, https://github.com/SoichiroYamane/gsplot/issues
+Project-URL: Repository, https://github.com/SoichiroYamane/gsplot
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/SoichiroYamane/gsplot/main/docs/_static/logo/logo_title_gsplot.png" alt="gsplot logo" width="300">
+</div>
+
+[![Documentation](https://github.com/SoichiroYamane/gsplot/actions/workflows/gh-pages-sphinx.yml/badge.svg)](https://soichiroyamane.github.io/gsplot/stable/)
+[![PyPI](https://img.shields.io/pypi/v/gsplot)](https://pypi.org/project/gsplot/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](https://github.com/SoichiroYamane/gsplot/blob/main/LICENSE)
+
+# gsplot
+
+`gsplot` creates publication-quality scientific figures with a concise API on
+top of Matplotlib. It adds paper-aware layouts, deterministic plotting and
+styling helpers, validated JSON defaults, and lightweight build metadata while
+returning ordinary Matplotlib `Figure`, `Axes`, and Artist objects.
+
+The package is still evolving. Check the [documentation](https://soichiroyamane.github.io/gsplot/stable/)
+and the [issue tracker](https://github.com/SoichiroYamane/gsplot/issues) before
+depending on behavior that is not covered by the public API.
+
+## Install
+
+`gsplot` supports Python 3.10 and newer:
+
+```bash
+python -m pip install gsplot
+```
+
+## Quick example
+
+```python
+import gsplot as gs
+
+fig, axes = gs.subplots("AB")
+gs.line(axes["A"], [0, 1, 2], [0, 1, 4], label="quadratic")
+gs.scatter(axes["B"], [0, 1, 2], [0, 1, 4], label="samples", s=15)
+gs.label(axes, "x", "value", square=True, index="in")
+gs.legend(axes)
+gs.save(fig, "quickstart", show=False)
+```
+
+This creates a two-panel Matplotlib figure, saves `quickstart.png` and
+`quickstart.pdf`, and remains compatible with regular Matplotlib operations.
+
+The canonical helpers always receive their Figure or Axes target explicitly.
+`save` writes PNG and PDF transactionally at 600 DPI with a tight crop and
+displays the Figure after successful writes by default; pass `show=False` for
+batch or headless output. Use `crop=False` when output dimensions must match
+the Figure design canvas exactly. The advanced `savefig` helper retains its
+conservative output controls.
+
+For a complete scientific example, see the
+[publication example](https://soichiroyamane.github.io/gsplot/dev/guides/examples/publication.html).
+
+## Configuration
+
+Configuration is optional and explicit. Load a schema-2 JSON file and pass the
+immutable value to supported functions:
+
+```python
+import gsplot as gs
+
+config = gs.load_config("path/to/gsplot.json")
+fig, axes = gs.subplots(config=config)
+```
+
+When a value is specified more than once, the precedence is:
+
+1. an argument passed directly to the function;
+2. the supplied immutable `Config` value;
+3. the function's default value.
+
+Canonical code never searches the working directory or home directory for a
+configuration file. See the [configuration guide](https://soichiroyamane.github.io/gsplot/dev/guides/examples/configuration.html)
+for the supported schema, precedence, and backend notes.
+
+## Development
+
+The repository uses Poetry and targets Python 3.10 or newer. With a compatible
+Python interpreter:
+
+```bash
+python -m pip install "poetry==2.4.1"
+poetry install
+MPLBACKEND=Agg poetry run pytest -q
+MPLBACKEND=Agg poetry run sphinx-build -W -b html docs docs/_build/html
+```
+
+The scripts under `examples/` are executable documentation. Run one from its own
+directory, for example:
+
+```bash
+cd examples/layouts && python mosaic.py
+```
+
+`examples/compatibility/legacy_v0.py` intentionally demonstrates the deprecated
+0.x surface. All other plotting examples use the canonical explicit-target API.
+
+See [the developer setup guide](https://soichiroyamane.github.io/gsplot/stable/reference/contribution/developer_env.html)
+for formatting, type checking, packaging, and Docker instructions.
+
+For private vulnerability reports and the supported-version policy, see
+[SECURITY.md](https://github.com/SoichiroYamane/gsplot/blob/main/SECURITY.md).
+
+## Authors and maintenance
+
+This repository builds on the original code developed by Giordano Mattoni.
+
+- Original author: Giordano Mattoni
+- Maintainer: Soichiro Yamane
+
+## License
+
+This project is distributed under the
+[MIT License](https://github.com/SoichiroYamane/gsplot/blob/main/LICENSE).
+

gsplot-0.4.0/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/SoichiroYamane/gsplot/main/docs/_static/logo/logo_title_gsplot.png" alt="gsplot logo" width="300">
+</div>
+
+[![Documentation](https://github.com/SoichiroYamane/gsplot/actions/workflows/gh-pages-sphinx.yml/badge.svg)](https://soichiroyamane.github.io/gsplot/stable/)
+[![PyPI](https://img.shields.io/pypi/v/gsplot)](https://pypi.org/project/gsplot/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](https://github.com/SoichiroYamane/gsplot/blob/main/LICENSE)
+
+# gsplot
+
+`gsplot` creates publication-quality scientific figures with a concise API on
+top of Matplotlib. It adds paper-aware layouts, deterministic plotting and
+styling helpers, validated JSON defaults, and lightweight build metadata while
+returning ordinary Matplotlib `Figure`, `Axes`, and Artist objects.
+
+The package is still evolving. Check the [documentation](https://soichiroyamane.github.io/gsplot/stable/)
+and the [issue tracker](https://github.com/SoichiroYamane/gsplot/issues) before
+depending on behavior that is not covered by the public API.
+
+## Install
+
+`gsplot` supports Python 3.10 and newer:
+
+```bash
+python -m pip install gsplot
+```
+
+## Quick example
+
+```python
+import gsplot as gs
+
+fig, axes = gs.subplots("AB")
+gs.line(axes["A"], [0, 1, 2], [0, 1, 4], label="quadratic")
+gs.scatter(axes["B"], [0, 1, 2], [0, 1, 4], label="samples", s=15)
+gs.label(axes, "x", "value", square=True, index="in")
+gs.legend(axes)
+gs.save(fig, "quickstart", show=False)
+```
+
+This creates a two-panel Matplotlib figure, saves `quickstart.png` and
+`quickstart.pdf`, and remains compatible with regular Matplotlib operations.
+
+The canonical helpers always receive their Figure or Axes target explicitly.
+`save` writes PNG and PDF transactionally at 600 DPI with a tight crop and
+displays the Figure after successful writes by default; pass `show=False` for
+batch or headless output. Use `crop=False` when output dimensions must match
+the Figure design canvas exactly. The advanced `savefig` helper retains its
+conservative output controls.
+
+For a complete scientific example, see the
+[publication example](https://soichiroyamane.github.io/gsplot/dev/guides/examples/publication.html).
+
+## Configuration
+
+Configuration is optional and explicit. Load a schema-2 JSON file and pass the
+immutable value to supported functions:
+
+```python
+import gsplot as gs
+
+config = gs.load_config("path/to/gsplot.json")
+fig, axes = gs.subplots(config=config)
+```
+
+When a value is specified more than once, the precedence is:
+
+1. an argument passed directly to the function;
+2. the supplied immutable `Config` value;
+3. the function's default value.
+
+Canonical code never searches the working directory or home directory for a
+configuration file. See the [configuration guide](https://soichiroyamane.github.io/gsplot/dev/guides/examples/configuration.html)
+for the supported schema, precedence, and backend notes.
+
+## Development
+
+The repository uses Poetry and targets Python 3.10 or newer. With a compatible
+Python interpreter:
+
+```bash
+python -m pip install "poetry==2.4.1"
+poetry install
+MPLBACKEND=Agg poetry run pytest -q
+MPLBACKEND=Agg poetry run sphinx-build -W -b html docs docs/_build/html
+```
+
+The scripts under `examples/` are executable documentation. Run one from its own
+directory, for example:
+
+```bash
+cd examples/layouts && python mosaic.py
+```
+
+`examples/compatibility/legacy_v0.py` intentionally demonstrates the deprecated
+0.x surface. All other plotting examples use the canonical explicit-target API.
+
+See [the developer setup guide](https://soichiroyamane.github.io/gsplot/stable/reference/contribution/developer_env.html)
+for formatting, type checking, packaging, and Docker instructions.
+
+For private vulnerability reports and the supported-version policy, see
+[SECURITY.md](https://github.com/SoichiroYamane/gsplot/blob/main/SECURITY.md).
+
+## Authors and maintenance
+
+This repository builds on the original code developed by Giordano Mattoni.
+
+- Original author: Giordano Mattoni
+- Maintainer: Soichiro Yamane
+
+## License
+
+This project is distributed under the
+[MIT License](https://github.com/SoichiroYamane/gsplot/blob/main/LICENSE).

gsplot-0.4.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "gsplot"
+version = "0.4.0"
+description = "Concise publication-quality scientific plotting built on Matplotlib"
+authors = [
+  { name = "Giordano Mattoni" },
+]
+maintainers = [{ name = "Soichiro Yamane" }]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["matplotlib", "plotting", "publication", "scientific"]
+dependencies = [
+  "matplotlib>=3.9.0",
+  "numpy>=1.26.4",
+]
+
+[project.urls]
+Homepage = "https://soichiroyamane.github.io/gsplot/"
+Documentation = "https://soichiroyamane.github.io/gsplot/stable/"
+Repository = "https://github.com/SoichiroYamane/gsplot"
+Issues = "https://github.com/SoichiroYamane/gsplot/issues"
+
+[tool.poetry]
+packages = [{ include = "gsplot", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+flake8 = "^7.0.0"
+black = ">=26.3.1,<27.0.0"
+isort = ">=5.13.2,<9.0.0"
+pre-commit = "^4.6.1"
+furo = "^2025.12.19"
+myst-parser = "^4.0.0"
+pytest-watch = "^4.2.0"
+pytest = ">=9.0.3,<10.0.0"
+pytest-cov = ">=6.0,<8.0"
+certifi = ">=2025.1.31,<2026.0.0"
+pyright = "^1.1.390"
+mypy = "^2.3.0"
+pip-audit = { version = ">=2.10.1,<3.0.0", python = ">=3.10,<4.0" }
+sphinxext-opengraph = "^0.13.0"
+sphinx-pyscript = "^0.1.0"
+sphinx-tippy = "^0.4.3"
+sphinx-togglebutton = "^0.4.5"
+sphinx-design = "^0.6.1"
+sphinxcontrib-mermaid = "^2.1.0"
+pydata-sphinx-theme = "^0.19.0"
+sphinx-copybutton = "^0.5.2"
+sphinx-autobuild = "^2024.10.3"
+ipython = ">=8.20.0"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+
+[tool.isort]
+profile = "black"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

gsplot-0.4.0/src/gsplot/__init__.py

@@ -0,0 +1,213 @@
+"""Lazy public package boundary for the canonical gsplot API.
+
+The 0.3.x names remain available through deprecated compatibility adapters.
+Importing the package itself intentionally performs no Matplotlib,
+configuration, logging, metadata-file, or backend initialization.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ._compat.root import canonical_names as _canonical_names
+from ._compat.root import legacy_names as _legacy_names
+from ._compat.root import (
+    resolve_export,
+)
+from .version import __commit__, __version__
+
+if TYPE_CHECKING:
+    # Runtime lookup stays lazy.  Static analyzers see the canonical source
+    # objects instead of an ``Any``-typed dynamic facade, so the shipped
+    # ``py.typed`` marker provides useful signatures to downstream callers.
+    from ._compat.config import load_config
+    from ._config.model import Config
+    from ._core.errors import (
+        ConfigError,
+        DataError,
+        GsplotError,
+        LayoutError,
+        MetadataError,
+        OutputError,
+        PlotError,
+    )
+    from ._core.types import (
+        AxesDict,
+        AxesTarget,
+        AxisSpec,
+        BuildInfo,
+        ColorSpec,
+        InsetSpec,
+        LabelRecord,
+        LabelRecords,
+        LayoutMode,
+        LegendEntries,
+        Limit,
+        LineStyle,
+        Marker,
+        MetadataSnapshot,
+        MosaicSpec,
+        NormalizeSpec,
+        PerTarget,
+        Scale,
+        SizePreset,
+        SizeSpec,
+        StyleMode,
+        Theme,
+        TickSpec,
+        Unit,
+        ZoomCorners,
+    )
+    from ._figure.backend import use_backend
+    from ._figure.inset import inset, inset_axes
+    from ._figure.layout import subplots
+    from ._figure.output import save, savefig, show
+    from ._io.arrays import read, read_array
+    from ._io.build import build_info
+    from ._io.metadata import write_meta
+    from ._plot.basic import line, scatter
+    from ._plot.colored import cmap_dash, cmap_line, cmap_scatter
+    from ._plot.colormap import colors, sample_cmap
+    from ._style.axes import (
+        box_aspect,
+        label,
+        minor_ticks,
+        square,
+        style_axes,
+        suptitle,
+        title,
+    )
+    from ._style.legends import cmap_legend, legend, legend_entries, legends
+    from ._style.panels import index, panel_labels
+    from ._style.paper import paper
+    from ._style.themes import fig_facecolor, set_theme
+
+    # These are intentionally outside the canonical manifest but remain
+    # discoverable for the documented compatibility window.
+    get_cmap: Any
+    load_file: Any
+    load_file_fast: Any
+    axes: Any
+    axes_inset: Any
+    axes_inset_padding: Any
+    get_figure_size: Any
+    hello_world: Any
+    config_load: Any
+    config_dict: Any
+    config_entry_option: Any
+    home: Any
+    pwd: Any
+    pwd_move: Any
+    pwd_main: Any
+    line_colormap_solid: Any
+    line_colormap_dashed: Any
+    scatter_colormap: Any
+    graph_square: Any
+    graph_square_axes: Any
+    graph_white: Any
+    graph_white_axes: Any
+    graph_transparent: Any
+    graph_transparent_axes: Any
+    graph_facecolor: Any
+    label_add_index: Any
+    legend_axes: Any
+    legend_handlers: Any
+    legend_reverse: Any
+    legend_get_handlers: Any
+    legend_colormap: Any
+    ticks_off: Any
+    ticks_on: Any
+    ticks_on_axes: Any
+    title_axes: Any
+    logger: Any
+    save_metadata: Any
+
+__all__ = [
+    "subplots",
+    "inset",
+    "inset_axes",
+    "line",
+    "scatter",
+    "cmap_line",
+    "cmap_dash",
+    "cmap_scatter",
+    "colors",
+    "sample_cmap",
+    "style_axes",
+    "label",
+    "square",
+    "title",
+    "suptitle",
+    "minor_ticks",
+    "box_aspect",
+    "panel_labels",
+    "index",
+    "fig_facecolor",
+    "legend",
+    "legends",
+    "legend_entries",
+    "cmap_legend",
+    "set_theme",
+    "paper",
+    "save",
+    "savefig",
+    "show",
+    "load_config",
+    "read",
+    "read_array",
+    "write_meta",
+    "build_info",
+    "use_backend",
+    "Config",
+    "AxisSpec",
+    "Theme",
+    "InsetSpec",
+    "MetadataSnapshot",
+    "BuildInfo",
+    "LegendEntries",
+    "GsplotError",
+    "ConfigError",
+    "DataError",
+    "LayoutError",
+    "PlotError",
+    "OutputError",
+    "MetadataError",
+    "MosaicSpec",
+    "NormalizeSpec",
+    "ColorSpec",
+    "AxesDict",
+    "AxesTarget",
+    "PerTarget",
+    "LineStyle",
+    "Marker",
+    "Unit",
+    "SizePreset",
+    "SizeSpec",
+    "LayoutMode",
+    "StyleMode",
+    "ZoomCorners",
+    "Limit",
+    "Scale",
+    "TickSpec",
+    "LabelRecord",
+    "LabelRecords",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve a canonical or legacy root export only when requested."""
+
+    value = resolve_export(name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Include lazy compatibility names in interactive discovery."""
+
+    return sorted(
+        set(globals())
+        | set(_legacy_names())
+        | set(_canonical_names())
+        | {"__commit__", "__version__"}
+    )