plotform 0.1.0__py3-none-any.whl

plotform/__init__.py

@@ -0,0 +1,53 @@
+"""Plotform: a minimalist Matplotlib theme and plotting toolkit."""
+
+from importlib.metadata import version as _distribution_version
+
+from .api import annotate, bar, barh, colorbar, legend
+from .fonts import MONO_FONT, SANS_FONT
+from .palette import (
+    AXIS,
+    BASE_COLORS,
+    CORAL,
+    DIVERGING_CMAP,
+    GRID,
+    INK,
+    MUTED,
+    MUTED_AXIS,
+    PRIMARY,
+    SCALAR_CMAP,
+    SCALAR_STOPS,
+    SEQUENTIAL_CMAP,
+    WHITE,
+    get_palette,
+)
+from .theme import apply_theme, theme
+from .three_d import style_3d
+
+__version__ = _distribution_version("plotform")
+
+__all__ = [
+    "AXIS",
+    "BASE_COLORS",
+    "CORAL",
+    "DIVERGING_CMAP",
+    "GRID",
+    "INK",
+    "MONO_FONT",
+    "MUTED",
+    "MUTED_AXIS",
+    "PRIMARY",
+    "SANS_FONT",
+    "SCALAR_CMAP",
+    "SCALAR_STOPS",
+    "SEQUENTIAL_CMAP",
+    "WHITE",
+    "annotate",
+    "apply_theme",
+    "bar",
+    "barh",
+    "colorbar",
+    "get_palette",
+    "legend",
+    "style_3d",
+    "theme",
+]

plotform/api.py

@@ -0,0 +1,47 @@
+"""Native-style convenience names for Plotform helpers."""
+
+from __future__ import annotations
+
+from .colorbar_utils import capsule_colorbar
+from .legend_utils import pill_legend
+from .rounded import add_pill, rounded_bar, rounded_barh
+
+
+def _axes(ax=None):
+    if ax is not None:
+        return ax
+    from matplotlib import pyplot as plt
+
+    return plt.gca()
+
+
+def legend(ax=None, **kwargs):
+    """Create a pill legend, using the current axes when ``ax`` is omitted."""
+    return pill_legend(_axes(ax), **kwargs)
+
+
+def bar(*args, ax=None, **kwargs):
+    """Draw rounded bars with native ``plt.bar``-style argument order."""
+    return rounded_bar(_axes(ax), *args, **kwargs)
+
+
+def barh(*args, ax=None, **kwargs):
+    """Draw horizontal rounded bars with native ``plt.barh``-style order."""
+    return rounded_barh(_axes(ax), *args, **kwargs)
+
+
+def colorbar(mappable, *, fig=None, ax=None, **kwargs):
+    """Create a capsule colorbar, using the current figure/axes by default."""
+    if fig is None:
+        from matplotlib import pyplot as plt
+
+        fig = plt.gcf()
+    return capsule_colorbar(fig, _axes(ax), mappable, **kwargs)
+
+
+def annotate(text, xy, *, ax=None, **kwargs):
+    """Add a capsule annotation with native ``Axes.annotate`` argument order."""
+    return add_pill(_axes(ax), xy[0], xy[1], text, **kwargs)
+
+
+__all__ = ["annotate", "bar", "barh", "colorbar", "legend"]

plotform/assets/fonts/PlotformMono-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2025 The Google Sans Code Project Authors (github.com/googlefonts/googlesans-code)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

plotform/assets/fonts/PlotformMono-TRADEMARKS.md

@@ -0,0 +1,17 @@
+Google Sans Code Trademarks
+===========================
+
+Google commissioned the Google Sans fonts collection, including Google Sans Code, as 'work for hire' and owns all rights to these works.
+However, Google also does not include within the Open Font License ([OFL.txt](OFL.txt)) any Reserved Font Names (RFNs) within the copyright statement. 
+
+“Google”, “Google Sans” and “Google Sans Code” are trademarks of Google LLC.
+
+Use of any version of this Font Software does not allow you to use the “Google” trademark on its own or as part of any other trademarks, terms, or source identifiers.
+
+The “Google Sans Code” trademark may be used in connection with the Original Font Software version or Modified Font Software, but such use may only be in connection with the Original Font Software and in no way may be used in a manner that may imply any affiliation with or sponsorship by Google LLC.
+
+The “Google Sans Code” trademark may not be incorporated as part of your company name, product name, domain name, or social media profile without permission.
+
+The “Google Sans Code” trademark should not be combined with other trademarks, terms, or source identifiers, and may not be modified without permission.
+
+For example, Modified Versions of the Font Software may use the Google mark in a Github repo fork that is used to contribute a Pull Request to the [github.com/googlefonts/googlesans-code](https://github.com/googlefonts/googlesans-code) repo.

plotform/assets/fonts/PlotformSans-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2015 The Google Sans Flex Authors (https://github.com/googlefonts/googlesans-flex)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

plotform/assets/fonts/PlotformSans-TRADEMARKS.md

@@ -0,0 +1,17 @@
+Google Sans Flex Trademarks
+===========================
+
+Google commissioned the Google Sans fonts collection, including Google Sans Flex, as 'work for hire' and owns all rights to these works.
+However, Google also does not include within the Open Font License ([OFL.txt](OFL.txt)) any Reserved Font Names (RFNs) within the copyright statement. 
+
+“Google”, “Google Sans” and “Google Sans Flex” are trademarks of Google LLC.
+
+Use of any version of this Font Software does not allow you to use the “Google” trademark on its own or as part of any other trademarks, terms, or source identifiers.
+
+The “Google”, “Google Sans” or “Google Sans Flex” trademarks may be used in connection with the Original Font Software version or Modified Font Software, but such use may only be in connection with the Original Font Software and in no way may be used in a manner that may imply any affiliation with or sponsorship by Google LLC.
+
+The “Google”, “Google Sans” or “Google Sans Flex” trademarks may not be incorporated as part of your company name, product name, domain name, or social media profile without permission.
+
+The “Google”, “Google Sans” or “Google Sans Flex” trademarks should not be combined with other trademarks, terms, or source identifiers, and may not be modified without permission.
+
+For example, Modified Versions of the Font Software may use the Google mark in a Github repo fork that is used to contribute a Pull Request to the [github.com/googlefonts/googlesans-flex](https://github.com/googlefonts/googlesans-flex) repo.

plotform/assets/fonts/README.md

@@ -0,0 +1,30 @@
+# Bundled font attributions
+
+Plotform includes derived, static font instances so plots render consistently
+without requiring system-wide font installation or variable-font axis support.
+
+## Plotform Sans
+
+- Source: **Google Sans Flex**, Google Sans Flex Authors
+- Upstream: https://github.com/googlefonts/googlesans-flex
+- Downloaded from: https://github.com/google/fonts/tree/main/ofl/googlesansflex
+- Modification: instantiated with `ROND=100`; weight and every other variable
+  axis were left at their source defaults. The font was then renamed to avoid
+  collision with separately installed Google fonts.
+- Result: `PlotformSans-Rounded.ttf`, regular weight 400
+- License: `PlotformSans-OFL.txt` (SIL Open Font License 1.1)
+- Trademark notice: `PlotformSans-TRADEMARKS.md`
+
+## Plotform Mono
+
+- Source: **Google Sans Code**, Google Sans Code Project Authors
+- Upstream: https://github.com/googlefonts/googlesans-code
+- Downloaded from: https://github.com/google/fonts/tree/main/ofl/googlesanscode
+- Modification: instantiated at the source default weight and renamed.
+- Result: `PlotformMono-Regular.ttf`, regular weight 400
+- License: `PlotformMono-OFL.txt` (SIL Open Font License 1.1)
+- Trademark notice: `PlotformMono-TRADEMARKS.md`
+
+Run `python tools/prepare_fonts.py` from the repository root to regenerate these
+assets from Google Fonts. The generated documents and figures are not subject
+to the font software license; the font files themselves remain under the OFL.

plotform/colorbar_utils.py

@@ -0,0 +1,75 @@
+"""Vertical capsule tracks for continuous scalar colorbars."""
+
+from __future__ import annotations
+
+from matplotlib.patches import PathPatch
+from matplotlib.path import Path
+from matplotlib.transforms import IdentityTransform
+
+from .palette import INK
+from .rounded import capsule_path
+
+
+class DisplayCapsulePatch(PathPatch):
+    """An invisible display-space capsule used to clip colorbar artists."""
+
+    def __init__(self):
+        super().__init__(
+            capsule_path(0, 0, 1, 1),
+            facecolor="none",
+            edgecolor="none",
+            transform=IdentityTransform(),
+        )
+
+    def get_path(self) -> Path:
+        ax = getattr(self, "axes", None)
+        if ax is None:
+            return capsule_path(0, 0, 1, 1)
+        bounds = ax.bbox
+        return capsule_path(bounds.x0, bounds.y0, bounds.width, bounds.height)
+
+
+def capsule_colorbar(fig, ax, mappable, **kwargs):
+    """Create a vertical colorbar whose visible gradient is an exact capsule.
+
+    Tick marks and numeric labels remain outside the track. Additional keyword
+    arguments are forwarded to ``Figure.colorbar``. The returned Colorbar has a
+    ``capsule_patch`` attribute for inspection and advanced customization.
+    """
+    if kwargs.get("orientation", "vertical") != "vertical":
+        raise ValueError("capsule_colorbar currently supports vertical orientation only")
+    kwargs["orientation"] = "vertical"
+    colorbar = fig.colorbar(mappable, ax=ax, **kwargs)
+    cax = colorbar.ax
+
+    clip = DisplayCapsulePatch()
+    clip.set_clip_on(False)
+    cax.add_patch(clip)
+    for artist in (*cax.images, *cax.collections):
+        artist.set_clip_path(clip)
+    if getattr(colorbar, "solids", None) is not None:
+        colorbar.solids.set_clip_path(clip)
+
+    if getattr(colorbar, "outline", None) is not None:
+        colorbar.outline.set_visible(False)
+    for spine in cax.spines.values():
+        spine.set_visible(False)
+    cax.patch.set_visible(False)
+    cax.yaxis.set_ticks_position("right")
+    cax.yaxis.set_label_position("right")
+    cax.tick_params(
+        axis="y",
+        which="both",
+        direction="out",
+        length=3,
+        width=0.8,
+        colors=INK,
+        labelcolor=INK,
+        pad=5,
+    )
+
+    colorbar.capsule_patch = clip
+    return colorbar
+
+
+__all__ = ["capsule_colorbar"]

plotform/fonts.py

@@ -0,0 +1,56 @@
+"""Registration and verification of the bundled theme fonts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from matplotlib import font_manager
+
+SANS_FONT = "Plotform Sans"
+MONO_FONT = "Plotform Mono"
+FONT_DIR = Path(__file__).resolve().parent / "assets" / "fonts"
+FONT_FILES = ("PlotformSans-Rounded.ttf", "PlotformMono-Regular.ttf")
+
+_registered = False
+
+
+def font_paths() -> dict[str, Path]:
+    """Return the expected bundled font paths by family name."""
+    return {
+        SANS_FONT: FONT_DIR / FONT_FILES[0],
+        MONO_FONT: FONT_DIR / FONT_FILES[1],
+    }
+
+
+def register_fonts(*, verify: bool = True) -> dict[str, Path]:
+    """Register bundled fonts with Matplotlib without modifying the OS.
+
+    Returns the resolved font files. With ``verify=True``, a missing or invalid
+    font raises instead of silently falling back to a system font.
+    """
+    global _registered
+
+    paths = font_paths()
+    missing = [str(path) for path in paths.values() if not path.is_file()]
+    if missing:
+        raise FileNotFoundError("Bundled theme fonts are missing: " + ", ".join(missing))
+
+    if not _registered:
+        for path in paths.values():
+            font_manager.fontManager.addfont(str(path))
+        _registered = True
+
+    if verify:
+        resolved: dict[str, Path] = {}
+        for family in (SANS_FONT, MONO_FONT):
+            properties = font_manager.FontProperties(family=family)
+            found = Path(font_manager.findfont(properties, fallback_to_default=False)).resolve()
+            expected = paths[family].resolve()
+            if found != expected:
+                raise RuntimeError(
+                    f"Matplotlib resolved {family!r} to {found}, expected {expected}"
+                )
+            resolved[family] = found
+        return resolved
+
+    return paths