plotstyle 0.1.0a1__py3-none-any.whl

plotstyle/__init__.py

@@ -0,0 +1,121 @@
+"""PlotStyle — scientific journal figure style presets for Matplotlib.
+
+PlotStyle makes it trivial to produce publication-ready figures that conform
+to the typographic and dimensional requirements of major academic journals.
+A single :func:`use` call reconfigures Matplotlib's ``rcParams``; helper
+functions handle figure sizing, colour palettes, accessibility previews,
+validation, and submission-ready export.
+
+Quick start
+-----------
+    >>> import matplotlib.pyplot as plt
+    >>> import plotstyle
+    >>>
+    >>> plotstyle.use("nature")
+    >>>
+    >>> fig, ax = plotstyle.subplots(columns=1)
+    >>> ax.plot([0, 1, 2], [0.2, 0.8, 0.4], color=plotstyle.palette("nature")[0])
+    >>> ax.set_xlabel("Time (s)")
+    >>> ax.set_ylabel("Signal (a.u.)")
+    >>>
+    >>> report = plotstyle.validate(fig, journal="nature")
+    >>> print(report)
+    >>>
+    >>> plotstyle.savefig(fig, "figure1.pdf")
+
+Package layout
+--------------
+The public API is re-exported here from the following sub-packages:
+
+- :mod:`plotstyle.core.style`          — :func:`use`, :class:`JournalStyle`
+- :mod:`plotstyle.core.figure`         — :func:`figure`, :func:`subplots`
+- :mod:`plotstyle.core.export`         — :func:`savefig`, :func:`export_submission`
+- :mod:`plotstyle.core.migrate`        — :func:`diff`, :func:`migrate`, :class:`SpecDiff`
+- :mod:`plotstyle.color.palettes`      — :func:`palette`
+- :mod:`plotstyle.color.accessibility` — :func:`preview_colorblind`
+- :mod:`plotstyle.color.grayscale`     — :func:`preview_grayscale`
+- :mod:`plotstyle.validation`          — :func:`validate`
+- :mod:`plotstyle.specs`               — :data:`registry`
+- :mod:`plotstyle.preview.gallery`     — :func:`gallery`
+- :mod:`plotstyle.preview.print_size`  — :func:`preview_print_size`
+
+Version
+-------
+The installed version is accessible as :data:`plotstyle.__version__`.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Package metadata
+# ---------------------------------------------------------------------------
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+# ---------------------------------------------------------------------------
+# Colour utilities
+# ---------------------------------------------------------------------------
+from plotstyle.color.accessibility import preview_colorblind
+from plotstyle.color.grayscale import preview_grayscale
+from plotstyle.color.palettes import palette
+
+# ---------------------------------------------------------------------------
+# Core — style application, figure construction, export, spec migration
+# ---------------------------------------------------------------------------
+from plotstyle.core.export import export_submission, savefig
+from plotstyle.core.figure import figure, subplots
+from plotstyle.core.migrate import SpecDiff, diff, migrate
+from plotstyle.core.style import JournalStyle, use
+
+# ---------------------------------------------------------------------------
+# Seaborn integration
+# ---------------------------------------------------------------------------
+from plotstyle.integrations.seaborn import patch_seaborn, plotstyle_theme, unpatch_seaborn
+
+# ---------------------------------------------------------------------------
+# Preview helpers
+# ---------------------------------------------------------------------------
+from plotstyle.preview.gallery import gallery
+from plotstyle.preview.print_size import preview_print_size
+
+# ---------------------------------------------------------------------------
+# Journal spec registry
+# ---------------------------------------------------------------------------
+from plotstyle.specs import registry
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+from plotstyle.validation import validate
+
+try:
+    __version__: str = _pkg_version("plotstyle")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+# ---------------------------------------------------------------------------
+# Public API surface
+# ---------------------------------------------------------------------------
+
+__all__: list[str] = [
+    "JournalStyle",
+    "SpecDiff",
+    "__version__",
+    "diff",
+    "export_submission",
+    "figure",
+    "gallery",
+    "migrate",
+    "palette",
+    "patch_seaborn",
+    "plotstyle_theme",
+    "preview_colorblind",
+    "preview_grayscale",
+    "preview_print_size",
+    "registry",
+    "savefig",
+    "subplots",
+    "unpatch_seaborn",
+    "use",
+    "validate",
+]

plotstyle/_utils/io.py

@@ -0,0 +1,113 @@
+"""File I/O helpers for PlotStyle.
+
+This module provides thin wrappers around common file operations used
+throughout PlotStyle:
+
+- **TOML loading** — :func:`load_toml` reads journal specification and
+  configuration files.  On Python 3.11+ the standard library
+  :mod:`tomllib` module is used; on older Python versions the third-party
+  :mod:`tomli` back-port is required.
+
+Python version handling
+-----------------------
+TOML support was added to the Python standard library in 3.11 (PEP 680).
+For Python 3.10 and earlier, PlotStyle requires the ``tomli`` package, which
+is API-compatible with ``tomllib`` and is a zero-dependency pure-Python
+library.  The import shim at module level ensures the rest of the codebase
+imports only from this module, insulating it from the stdlib/backport split.
+
+Example
+-------
+    >>> from pathlib import Path
+    >>> from plotstyle._utils.io import load_toml
+    >>> config = load_toml(Path("pyproject.toml"))
+    >>> config["project"]["name"]
+    'plotstyle'
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# TOML back-compat shim
+# ---------------------------------------------------------------------------
+
+# tomllib became part of the standard library in Python 3.11 (PEP 680).
+# For earlier versions we fall back to the 'tomli' third-party package, which
+# is API-identical and is a declared dependency of PlotStyle for Python < 3.11.
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "PlotStyle requires the 'tomli' package on Python < 3.11. "
+            "Install it with:  pip install tomli"
+        ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Load and parse a TOML file into a Python dictionary.
+
+    Opens *path* in binary mode (as required by both :mod:`tomllib` and
+    :mod:`tomli`) and returns the fully parsed document.  All standard TOML
+    types are mapped to their Python equivalents: strings, integers, floats,
+    booleans, datetimes, arrays, and inline tables.
+
+    Args:
+        path: Filesystem path to the ``.toml`` file.  Must be an existing,
+            readable regular file.  :class:`~pathlib.Path` is the canonical
+            type, but any object implementing the :meth:`open` protocol with
+            binary-read support is accepted.
+
+    Returns
+    -------
+        A :class:`dict` containing the top-level keys and values parsed from
+        the TOML document.  Nested tables become nested dicts; TOML arrays
+        become Python lists.
+
+    Raises
+    ------
+        FileNotFoundError: If *path* does not exist on the filesystem.
+        IsADirectoryError: If *path* points to a directory rather than a file.
+        PermissionError: If the process does not have read permission for
+            *path*.
+        OSError: For other low-level I/O failures (e.g., broken filesystem,
+            NFS timeout).
+        tomllib.TOMLDecodeError: If the file content is not valid TOML.  The
+            exception message includes the line and column of the syntax error.
+
+    Example:
+        >>> from pathlib import Path
+        >>> from plotstyle._utils.io import load_toml
+        >>> data = load_toml(Path("journals/nature.toml"))
+        >>> data["journal"]["name"]
+        'Nature'
+
+    Notes
+    -----
+        - Both :mod:`tomllib` (stdlib, Python ≥ 3.11) and :mod:`tomli`
+          (backport, Python < 3.11) require the file to be opened in *binary*
+          mode (``"rb"``).  This module handles that detail internally so
+          callers can treat :func:`load_toml` as a plain text-file loader.
+        - No caching is performed; each call re-reads the file from disk.
+          For files that are loaded repeatedly (e.g., palette data), callers
+          should cache the result at the call site.
+        - The function does not validate the contents of the parsed dictionary
+          beyond what the TOML spec requires.  Schema validation is the
+          responsibility of the caller.
+    """
+    with path.open("rb") as fh:
+        return tomllib.load(fh)

plotstyle/_utils/warnings.py

@@ -0,0 +1,86 @@
+"""Warning hierarchy for PlotStyle.
+
+All warnings emitted by PlotStyle derive from :class:`PlotStyleWarning`, which
+itself subclasses the built-in :class:`UserWarning`.  This two-level hierarchy
+lets users selectively filter or silence PlotStyle-specific warnings without
+affecting unrelated user warnings from other packages:
+
+.. code-block:: python
+
+    import warnings
+    from plotstyle._utils.warnings import PlotStyleWarning
+
+    # Silence all PlotStyle warnings at once.
+    warnings.filterwarnings("ignore", category=PlotStyleWarning)
+
+    # Or silence only a specific sub-class.
+    from plotstyle._utils.warnings import FontFallbackWarning
+
+    warnings.filterwarnings("ignore", category=FontFallbackWarning)
+
+Warning classes
+---------------
+.. autosummary::
+
+    PlotStyleWarning
+    FontFallbackWarning
+
+Design notes
+------------
+- All warning classes are intentionally kept as thin stubs.  They carry no
+  data attributes beyond the message string inherited from :class:`Warning`.
+  If structured warning data is ever needed, add it as constructor arguments
+  on the specific subclass rather than on the base class.
+- ``pass`` is omitted from class bodies by convention (a docstring is
+  sufficient to make the body non-empty), improving readability in IDEs and
+  documentation renderers.
+- Inheriting from :class:`UserWarning` (via :class:`PlotStyleWarning`) ensures
+  that ``warnings.warn(..., stacklevel=2)`` displays the caller's frame, not
+  the internals of PlotStyle, in the warning message.
+"""
+
+from __future__ import annotations
+
+
+class PlotStyleWarning(UserWarning):
+    """Base class for all PlotStyle warnings.
+
+    Subclass :class:`UserWarning` so that PlotStyle warnings are visible by
+    default (Python does not suppress ``UserWarning`` the way it suppresses
+    :class:`DeprecationWarning`), while still being filterable as a group.
+
+    All other PlotStyle warning classes inherit from this class.  To silence
+    every warning from PlotStyle in one call, filter on this base class:
+
+    .. code-block:: python
+
+        import warnings
+
+        warnings.filterwarnings("ignore", category=PlotStyleWarning)
+
+    Example:
+        >>> import warnings
+        >>> from plotstyle._utils.warnings import PlotStyleWarning
+        >>> warnings.warn("example", PlotStyleWarning, stacklevel=2)
+    """
+
+
+class FontFallbackWarning(PlotStyleWarning):
+    """Raised when a preferred font is unavailable and a fallback is used.
+
+    PlotStyle attempts to activate journal-specific fonts (e.g., Helvetica
+    Neue for Nature, Times New Roman for IEEE).  When the requested font is
+    not installed on the system, Matplotlib falls back to its default font
+    family.  This warning is emitted in that situation so that authors are
+    aware the rendered figure may not match the journal's typographic
+    requirements.
+
+    Example:
+        >>> import warnings
+        >>> from plotstyle._utils.warnings import FontFallbackWarning
+        >>> warnings.warn(
+        ...     "Font 'Helvetica Neue' not found; falling back to 'DejaVu Sans'.",
+        ...     FontFallbackWarning,
+        ...     stacklevel=2,
+        ... )
+    """

plotstyle/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0a1'
+__version_tuple__ = version_tuple = (0, 1, 0, 'a1')
+
+__commit_id__ = commit_id = None