gsplot 0.4.0__tar.gz → 0.4.1__tar.gz

{gsplot-0.4.0 → gsplot-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsplot
-Version: 0.4.0
+Version: 0.4.1
 Summary: Concise publication-quality scientific plotting built on Matplotlib
 License-Expression: MIT
 License-File: LICENSE

{gsplot-0.4.0 → gsplot-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gsplot"
-version = "0.4.0"
+version = "0.4.1"
 description = "Concise publication-quality scientific plotting built on Matplotlib"
 authors = [
   { name = "Giordano Mattoni" },

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/__init__.py

@@ -75,6 +75,7 @@ if TYPE_CHECKING:
         square,
         style_axes,
         suptitle,
+        ticks,
         title,
     )
     from ._style.legends import cmap_legend, legend, legend_entries, legends
@@ -139,6 +140,7 @@ __all__ = [
     "title",
     "suptitle",
     "minor_ticks",
+    "ticks",
     "box_aspect",
     "panel_labels",
     "index",

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/__init__.pyi

@@ -60,6 +60,7 @@ from ._style.axes import minor_ticks as minor_ticks
 from ._style.axes import square as square
 from ._style.axes import style_axes as style_axes
 from ._style.axes import suptitle as suptitle
+from ._style.axes import ticks as ticks
 from ._style.axes import title as title
 from ._style.legends import cmap_legend as cmap_legend
 from ._style.legends import legend as legend
@@ -129,6 +130,7 @@ __all__ = [
     "title",
     "suptitle",
     "minor_ticks",
+    "ticks",
     "box_aspect",
     "panel_labels",
     "index",

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_compat/legacy_api.py

@@ -20,6 +20,7 @@ from typing import Any, Literal, cast
 import numpy as np
 from matplotlib import ticker
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 from mpl_toolkits.axes_grid1.inset_locator import inset_axes as _mpl_inset_axes
 from numpy.typing import ArrayLike, NDArray
@@ -310,16 +311,21 @@ def _legacy_limits(
     if value is None:
         return None, "linear", None, None
     if isinstance(value, (str, bytes)):
+        if value in ("", "*"):
+            return None, "linear", None, None
         raise LayoutError("legacy limits must be a finite sequence")
     values = tuple(value)
     if len(values) < 2:
         raise LayoutError("legacy limits must contain two values")
-    try:
-        limits = (float(values[0]), float(values[1]))
-    except (TypeError, ValueError) as exc:
-        raise LayoutError("legacy limits must contain finite values") from exc
-    if not np.all(np.isfinite(limits)) or limits[0] == limits[1]:
-        raise LayoutError("legacy limits must contain finite unequal values")
+    if values[0] in (None, "", "*") and values[1] in (None, "", "*"):
+        limits = None
+    else:
+        try:
+            limits = (float(cast(Any, values[0])), float(cast(Any, values[1])))
+        except (TypeError, ValueError) as exc:
+            raise LayoutError("legacy limits must contain finite values") from exc
+        if not np.all(np.isfinite(limits)) or limits[0] == limits[1]:
+            raise LayoutError("legacy limits must contain finite unequal values")
     scale = values[2] if len(values) > 2 and isinstance(values[2], str) else "linear"
     if scale not in {"linear", "log", "symlog", "logit"}:
         raise LayoutError(f"unsupported legacy scale: {scale!r}")
@@ -835,25 +841,25 @@ def legend_colormap(
     )
 
 
-def ticks_off(ax: Axes, mode: str = "xy") -> None:
+def ticks_off(ax: Axes | _AxesBase, mode: str = "xy") -> None:
     """Adapt legacy minor-tick disabling to the canonical selector."""
 
     _warn("ticks_off", "minor_ticks")
     selected = {"xy": "both"}.get(mode, mode)
     _minor_ticks(
-        ax,
+        cast(Any, ax),
         False,
         axis=cast(Literal["x", "y", "both"], selected),
     )
 
 
-def ticks_on(ax: Axes, mode: str = "xy") -> None:
+def ticks_on(ax: Axes | _AxesBase, mode: str = "xy") -> None:
     """Adapt legacy minor-tick enabling to the canonical selector."""
 
     _warn("ticks_on", "minor_ticks")
     selected = {"xy": "both"}.get(mode, mode)
     _minor_ticks(
-        ax,
+        cast(Any, ax),
         True,
         axis=cast(Literal["x", "y", "both"], selected),
     )

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_compat/root.py

@@ -86,6 +86,7 @@ _CANONICAL_EXPORTS: Final[dict[str, tuple[str, str]]] = {
     "title": ("gsplot._compat.root_api", "title"),
     "suptitle": ("gsplot._style.axes", "suptitle"),
     "minor_ticks": ("gsplot._style.axes", "minor_ticks"),
+    "ticks": ("gsplot._style.axes", "ticks"),
     "box_aspect": ("gsplot._style.axes", "box_aspect"),
     "panel_labels": ("gsplot._style.panels", "panel_labels"),
     "index": ("gsplot._style.panels", "index"),

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_compat/root_api.py

@@ -15,6 +15,7 @@ from typing import Any, get_type_hints
 from weakref import WeakKeyDictionary
 
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 from numpy.typing import ArrayLike
 
@@ -32,7 +33,7 @@ from .._style.legends import legend as _legend
 from .._style.paper import PAPER_CYCLE_RGBA as _LEGACY_COLORS
 
 _UNSET = object()
-_LEGACY_PLOT_COUNTS: WeakKeyDictionary[Axes, int] = WeakKeyDictionary()
+_LEGACY_PLOT_COUNTS: WeakKeyDictionary[Axes | _AxesBase, int] = WeakKeyDictionary()
 
 _LEGACY_LEGEND_KEYS = {
     "handlers",
@@ -389,7 +390,7 @@ def scatter(
 def _legacy_label_records(value: Any) -> tuple[Any, ...] | None:
     """Recognize non-empty historical records without reading pyplot state."""
 
-    if isinstance(value, (str, bytes, Mapping, Axes)):
+    if isinstance(value, (str, bytes, Mapping, Axes, _AxesBase)):
         return None
     try:
         records = tuple(value)
@@ -430,6 +431,14 @@ def label(
     pad: Any = _UNSET,
     xpad: Any = _UNSET,
     ypad: Any = _UNSET,
+    margin: Any = _UNSET,
+    xmargin: Any = _UNSET,
+    ymargin: Any = _UNSET,
+    top: Any = _UNSET,
+    bottom: Any = _UNSET,
+    left: Any = _UNSET,
+    right: Any = _UNSET,
+    direction: Any = _UNSET,
     square: Any = _UNSET,
     index: Any = _UNSET,
     lab_lims: Any = _UNSET,
@@ -536,6 +545,14 @@ def label(
                 "pad": pad,
                 "xpad": xpad,
                 "ypad": ypad,
+                "margin": margin,
+                "xmargin": xmargin,
+                "ymargin": ymargin,
+                "top": top,
+                "bottom": bottom,
+                "left": left,
+                "right": right,
+                "direction": direction,
                 "square": square,
                 "index": index,
             }
@@ -559,6 +576,14 @@ def label(
             "pad": pad,
             "xpad": xpad,
             "ypad": ypad,
+            "margin": margin,
+            "xmargin": xmargin,
+            "ymargin": ymargin,
+            "top": top,
+            "bottom": bottom,
+            "left": left,
+            "right": right,
+            "direction": direction,
             "square": square,
             "index": index,
         }
@@ -677,11 +702,41 @@ def legend(
 ) -> Any:
     """Dispatch canonical ``legend`` or finite legacy options."""
 
-    legacy = _provided(
+    is_legacy = (
+        legacy_handles is not _UNSET
+        or legacy_labels is not _UNSET
+        or handlers is not _UNSET
+        or ncol is not _UNSET
+    )
+    if is_legacy:
+        if (legacy_handles is not _UNSET or legacy_labels is not _UNSET) and (
+            handles is not None or labels is not None
+        ):
+            raise OptionError("legend cannot combine positional and canonical entries")
+        if handlers is not _UNSET:
+            if handler_map is not None:
+                raise OptionError("legend cannot combine handlers and handler_map")
+            handler_map = handlers
+        if ncol is not _UNSET:
+            if ncols is not _UNSET:
+                raise OptionError(
+                    "legend: props cannot contain both 'ncol' and 'ncols'"
+                )
+            ncols = ncol
+        if legacy_handles is not _UNSET:
+            handles = legacy_handles
+        if legacy_labels is not _UNSET:
+            labels = legacy_labels
+        _warn("legend")
+
+    direct = _provided(
         {
-            "handlers": handlers,
+            "loc": loc,
+            "frameon": frameon,
+            "fancybox": fancybox,
+            "labelspacing": labelspacing,
+            "handlelength": handlelength,
             "ncols": ncols,
-            "ncol": ncol,
             "fontsize": fontsize,
             "title": title,
             "title_fontsize": title_fontsize,
@@ -702,59 +757,6 @@ def legend(
             "labelcolor": labelcolor,
         }
     )
-    if legacy_handles is not _UNSET:
-        legacy["_legacy_handles"] = legacy_handles
-    if legacy_labels is not _UNSET:
-        legacy["_legacy_labels"] = legacy_labels
-    if (legacy_handles is not _UNSET or legacy_labels is not _UNSET) and (
-        handles is not None or labels is not None
-    ):
-        raise OptionError("legend cannot combine positional and canonical entries")
-    if legacy and props is not None:
-        raise OptionError(
-            "gsplot.legend cannot combine canonical props with legacy options"
-        )
-    direct = _provided(
-        {
-            "loc": loc,
-            "frameon": frameon,
-            "fancybox": fancybox,
-            "labelspacing": labelspacing,
-            "handlelength": handlelength,
-        }
-    )
-    if not legacy:
-        return _legend(
-            target,
-            handles=handles,
-            labels=labels,
-            handler_map=handler_map,
-            reverse=reverse,
-            replace=replace,
-            props=props,
-            **direct,
-        )
-    positional_handles = legacy.pop("_legacy_handles", _UNSET)
-    positional_labels = legacy.pop("_legacy_labels", _UNSET)
-    if handlers is not _UNSET:
-        if handler_map is not None:
-            raise OptionError("legend cannot combine handlers and handler_map")
-        handler_map = handlers
-        legacy.pop("handlers", None)
-    translated = _translate_props(
-        "legend",
-        legacy,
-        {"ncol": "ncols"},
-    )
-    if positional_handles is not _UNSET:
-        if handles is not None:
-            raise OptionError("legend received handles twice")
-        handles = positional_handles
-    if positional_labels is not _UNSET:
-        if labels is not None:
-            raise OptionError("legend received labels twice")
-        labels = positional_labels
-    _warn("legend")
     return _legend(
         target,
         handles=handles,
@@ -762,7 +764,7 @@ def legend(
         handler_map=handler_map,
         reverse=reverse,
         replace=replace,
-        props=translated,
+        props=props,
         **direct,
     )
 
@@ -834,10 +836,10 @@ def title(
             "y": y,
         }
     )
-    if isinstance(ax, Axes):
-        if text is _UNSET or title is not _UNSET or legacy:
-            raise OptionError("canonical title requires text and props")
-        return _title(ax, text, props=props)
+    if isinstance(ax, (Axes, _AxesBase)):
+        if text is _UNSET or title is not _UNSET:
+            raise OptionError("canonical title requires an explicit text value")
+        return _title(ax, text, props=props, **legacy)
     if text is not _UNSET:
         raise TypeError("legacy Figure title accepts one text value")
     if title is not _UNSET:

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_core/plans.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import Any, Generic, Literal, TypeVar
 
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 
 from .errors import PlotError
@@ -24,7 +25,7 @@ def _operation_name(value: str) -> str:
     return value
 
 
-def _axis_root_figure(axis: Axes) -> Figure | None:
+def _axis_root_figure(axis: Any) -> Figure | None:
     """Return an Axes root Figure without requiring ``root=True`` support."""
 
     owner: Any = axis.get_figure()
@@ -47,7 +48,7 @@ class TargetPlan:
 
     operation: str
     figure: Figure
-    axes: tuple[Axes, ...]
+    axes: tuple[Axes | _AxesBase, ...]
     keys: tuple[object, ...]
     kind: TargetKind
 
@@ -61,7 +62,7 @@ class TargetPlan:
             raise PlotError(f"{self.operation}: target plan is empty or incomplete")
         if self.kind not in {"single", "sequence", "array", "mapping"}:
             raise PlotError(f"{self.operation}: target kind is invalid")
-        if any(not isinstance(axis, Axes) for axis in self.axes):
+        if any(not isinstance(axis, (Axes, _AxesBase)) for axis in self.axes):
             raise PlotError(f"{self.operation}: target contains a non-Axes value")
         if len({id(axis) for axis in self.axes}) != len(self.axes):
             raise PlotError(f"{self.operation}: target contains a duplicate Axes")

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_core/targets.py

@@ -7,6 +7,7 @@ from typing import Any, TypeVar
 
 import numpy as np
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 
 from .errors import PlotError
@@ -16,7 +17,7 @@ from .types import AxesTarget
 T = TypeVar("T")
 
 
-def _root_figure(axis: Axes, operation: str) -> Figure:
+def _root_figure(axis: Axes | _AxesBase, operation: str) -> Figure:
     """Resolve an Axes root Figure without version-specific root arguments."""
 
     owner = _axis_root_figure(axis)
@@ -30,7 +31,7 @@ def _snapshot_target(
 ) -> tuple[TargetKind, tuple[object, ...], tuple[Any, ...]]:
     """Snapshot one supported target shape without retaining its container."""
 
-    if isinstance(target, Axes):
+    if isinstance(target, (Axes, _AxesBase)):
         return "single", (target,), (target,)
     if isinstance(target, Mapping):
         items = tuple(target.items())
@@ -67,7 +68,7 @@ def normalize_axes(target: AxesTarget, *, operation: str) -> TargetPlan:
     kind, keys, values = _snapshot_target(target, operation)
     if not values:
         raise PlotError(f"{operation}: target must contain at least one Axes")
-    if any(not isinstance(value, Axes) for value in values):
+    if any(not isinstance(value, (Axes, _AxesBase)) for value in values):
         raise PlotError(f"{operation}: target contains a non-Axes value")
     axes = tuple(values)
     if len({id(axis) for axis in axes}) != len(axes):

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_core/types.py

@@ -11,6 +11,7 @@ from typing import Any, Literal, Protocol, TypeAlias, cast, overload
 
 from matplotlib.artist import Artist
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.colors import is_color_like
 from matplotlib.legend_handler import HandlerBase
 from matplotlib.typing import LineStyleType, MarkerType
@@ -25,7 +26,13 @@ ColorSpec: TypeAlias = str | RGBColor
 # Public type alias: MosaicSpec; a Matplotlib mosaic string or label rows.
 MosaicSpec: TypeAlias = str | Sequence[Sequence[str | None]]
 # Public type alias: AxesTarget; one Axes or a deterministic finite collection.
-AxesTarget: TypeAlias = Axes | Sequence[Axes] | Mapping[Any, Axes] | NDArray[Any]
+AxesTarget: TypeAlias = (
+    Axes
+    | _AxesBase
+    | Sequence[Axes | _AxesBase]
+    | Mapping[Any, Axes | _AxesBase]
+    | NDArray[Any]
+)
 # Public type alias: PerTarget; ordered or exact-key per-target values.
 PerTarget: TypeAlias = Sequence[Any] | Mapping[Any, Any]
 # Public type alias: LineStyle; a named style or finite dash-tuple form.
@@ -45,7 +52,9 @@ StyleMode: TypeAlias = Literal["auto", "paper"] | None
 # Public type alias: ZoomCorners; two explicit parent/inset connector pairs.
 ZoomCorners: TypeAlias = tuple[tuple[int, int], tuple[int, int]]
 # Public type alias: Limit; finite two-value axis limits after validation.
-Limit: TypeAlias = tuple[float, float]
+Limit: TypeAlias = (
+    tuple[float | str | None, float | str | None] | Sequence[float | str | None]
+)
 # Public type alias: Scale; supported Cartesian scale names.
 Scale: TypeAlias = Literal["linear", "log", "symlog", "logit"]
 # Public type alias: TickSpec; finite numeric tick locations after validation.
@@ -204,6 +213,7 @@ NormalizeSpec: TypeAlias = tuple[float, float] | _NormalizeProtocol
 
 
 _SCALES = {"linear", "log", "symlog", "logit"}
+_DIRECTIONS = {"in", "out", "inout"}
 _LOCATIONS = {
     "upper right",
     "upper left",
@@ -273,13 +283,13 @@ def _color(value: Any, name: str) -> ColorSpec:
     return cast(tuple[float, float, float, float], channels)
 
 
-def _limits(value: Any, name: str) -> tuple[float, float] | None:
-    """Validate finite, non-equal limits while preserving their order."""
+def _limits(value: Any, name: str) -> tuple[float | None, float | None] | None:
+    """Validate finite limits or partial limits while preserving their order."""
 
     if value is None:
         return None
     if isinstance(value, (str, bytes)):
-        if value == "*":
+        if value in ("", "*"):
             return None
         raise LayoutError(f"{name} must contain exactly two finite values")
     try:
@@ -288,15 +298,19 @@ def _limits(value: Any, name: str) -> tuple[float, float] | None:
         raise LayoutError(f"{name} must contain exactly two finite values") from exc
     if len(values) != 2:
         raise LayoutError(f"{name} must contain exactly two finite values")
-    if values[0] in (None, "*") and values[1] in (None, "*"):
-        return None
-    result = (
-        _finite(values[0], f"{name}[0]", LayoutError),
-        _finite(values[1], f"{name}[1]", LayoutError),
+    low = (
+        None
+        if values[0] in (None, "", "*")
+        else _finite(values[0], f"{name}[0]", LayoutError)
     )
-    if result[0] == result[1]:
+    high = (
+        None
+        if values[1] in (None, "", "*")
+        else _finite(values[1], f"{name}[1]", LayoutError)
+    )
+    if low is not None and high is not None and low == high:
         raise LayoutError(f"{name} values must not be equal")
-    return result
+    return (low, high)
 
 
 def _ticks(value: Any, name: str) -> tuple[float, ...] | None:
@@ -322,6 +336,22 @@ def _optional_finite(value: Any, name: str) -> float | None:
     return None if value is None else _finite(value, name, LayoutError)
 
 
+def _nonnegative_finite(value: Any, name: str, default: float = 0.05) -> float:
+    """Validate a non-negative finite margin value."""
+
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        raise LayoutError(f"{name} must be non-negative")
+    try:
+        num = float(value)
+    except (TypeError, ValueError) as exc:
+        raise LayoutError(f"{name} must be non-negative") from exc
+    if not math.isfinite(num) or num < 0:
+        raise LayoutError(f"{name} must be non-negative")
+    return num
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
 class AxisSpec:
     """Immutable Cartesian labels, limits, scales, ticks, and padding.
@@ -340,6 +370,12 @@ class AxisSpec:
         Optional minor-tick enable flags.
     xlabelpad, ylabelpad
         Optional finite label padding values.
+    xmargin, ymargin
+        Optional non-negative margin ratios for automatic endpoints.
+    top, bottom, left, right
+        Optional boolean flags for edge tick and label visibility.
+    direction
+        Optional tick direction: ``"in"``, ``"out"``, or ``"inout"``.
 
     Notes
     -----
@@ -349,15 +385,17 @@ class AxisSpec:
     Examples
     --------
     >>> import gsplot as gs
-    >>> spec = gs.AxisSpec(xlabel="time", xscale="linear")
+    >>> spec = gs.AxisSpec(xlabel="time", xscale="linear", right=False)
     >>> spec.xlabel
     'time'
+    >>> spec.right
+    False
     """
 
     xlabel: str | None = None
     ylabel: str | None = None
-    xlim: tuple[float, float] | None = None
-    ylim: tuple[float, float] | None = None
+    xlim: Limit | None = None
+    ylim: Limit | None = None
     xscale: Literal["linear", "log", "symlog", "logit"] = "linear"
     yscale: Literal["linear", "log", "symlog", "logit"] = "linear"
     xticks: tuple[float, ...] | None = None
@@ -366,6 +404,13 @@ class AxisSpec:
     yminor: bool | None = None
     xlabelpad: float | None = None
     ylabelpad: float | None = None
+    xmargin: float = 0.05
+    ymargin: float = 0.05
+    top: bool | None = None
+    bottom: bool | None = None
+    left: bool | None = None
+    right: bool | None = None
+    direction: Literal["in", "out", "inout"] | None = None
 
     def __post_init__(self) -> None:
         """Validate every field and normalize sequence-like inputs."""
@@ -394,6 +439,25 @@ class AxisSpec:
         object.__setattr__(
             self, "ylabelpad", _optional_finite(self.ylabelpad, "ylabelpad")
         )
+        object.__setattr__(
+            self, "xmargin", _nonnegative_finite(self.xmargin, "xmargin")
+        )
+        object.__setattr__(
+            self, "ymargin", _nonnegative_finite(self.ymargin, "ymargin")
+        )
+        for edge_name, edge_val in (
+            ("top", self.top),
+            ("bottom", self.bottom),
+            ("left", self.left),
+            ("right", self.right),
+        ):
+            if edge_val is not None and not isinstance(edge_val, bool):
+                raise LayoutError(f"{edge_name} must be a boolean or None")
+        if self.direction is not None:
+            if not isinstance(self.direction, str) or self.direction not in _DIRECTIONS:
+                raise LayoutError(
+                    f"direction must be one of: {', '.join(sorted(_DIRECTIONS))}"
+                )
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_figure/layout.py

@@ -531,21 +531,12 @@ def _layout_kind(figure: Figure) -> str:
 def _validate_reuse(
     figure: Figure,
     *,
-    size: SizeSpec,
-    size_inches: tuple[float, float] | None,
     layout: LayoutMode,
+    clear: bool = False,
 ) -> None:
     """Reject incompatible Figure reuse before clearing or adding Axes."""
 
-    if (
-        size not in {"auto", None}
-        and size_inches is not None
-        and not np.allclose(figure.get_size_inches(), size_inches, rtol=0, atol=1e-9)
-    ):
-        raise LayoutError(
-            "requested size does not match the reused Figure; omit size to preserve it"
-        )
-    if layout == "auto":
+    if layout == "auto" or clear:
         return
     current = _layout_kind(figure)
     if current != layout and not (
@@ -854,9 +845,8 @@ def subplots(
     if resolved_fig is not None:
         _validate_reuse(
             resolved_fig,
-            size=options["size"],
-            size_inches=size_inches,
             layout=options["layout"],
+            clear=selected_clear,
         )
 
     new_figure = resolved_fig is None
@@ -872,6 +862,8 @@ def subplots(
         )
     else:
         target = cast(Figure, resolved_fig)
+        if size_inches is not None:
+            target.set_size_inches(size_inches, forward=True)
         if selected_clear:
             target.clear()
             target.set_layout_engine(

{gsplot-0.4.0 → gsplot-0.4.1}/src/gsplot/_figure/output.py

@@ -524,24 +524,28 @@ def _formats(
     return selected, destinations
 
 
-def _save_props(props: Mapping[str, Any] | None) -> dict[str, Any]:
+def _save_props(
+    props: Mapping[str, Any] | None,
+    kwargs: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
     """Validate a closed Matplotlib savefig property mapping."""
 
-    if props is None:
-        return {}
-    if not isinstance(props, Mapping):
+    if props is not None and not isinstance(props, Mapping):
         raise OutputError("props must be a mapping")
-    if any(not isinstance(key, str) for key in props):
+    merged = dict(props or {})
+    if kwargs:
+        merged.update(kwargs)
+    if any(not isinstance(key, str) for key in merged):
         raise OutputError("props keys must be strings")
-    duplicate = sorted(set(props) & _CONTROLLED_PROPS)
+    duplicate = sorted(set(merged) & _CONTROLLED_PROPS)
     if duplicate:
         joined = ", ".join(repr(key) for key in duplicate)
         raise TypeError(f"props cannot contain gsplot-controlled key(s): {joined}")
-    unknown = sorted(set(props) - _SAVEFIG_PROPS)
+    unknown = sorted(set(merged) - _SAVEFIG_PROPS)
     if unknown:
         joined = ", ".join(repr(key) for key in unknown)
         raise OptionError(f"savefig props contains unknown key(s): {joined}")
-    return dict(props)
+    return merged
 
 
 def _is_interactive_figure(figure: Figure) -> bool:
@@ -606,6 +610,7 @@ def savefig(
     overwrite: bool = False,
     show: bool = True,
     props: Mapping[str, Any] | None = None,
+    **kwargs: Any,
 ) -> tuple[Path, ...]:
     """Save an explicit Figure and optionally display it after all writes.
 
@@ -626,6 +631,10 @@ def savefig(
     props
         A finite mapping of Matplotlib save properties; gsplot controls may
         not be supplied through this mapping.
+    **kwargs
+        Optional direct Matplotlib save properties (e.g. ``transparent``,
+        ``facecolor``, ``edgecolor``). Direct keyword arguments are merged with
+        and take precedence over ``props``.
 
     Returns
     -------
@@ -665,7 +674,7 @@ def savefig(
         if not math.isfinite(dpi_value) or dpi_value <= 0:
             raise OutputError("dpi must be a positive finite number")
         dpi = dpi_value
-    selected_props = _save_props(props)
+    selected_props = _save_props(props, kwargs)
     destination = _resolved_path(path, "path")
     selected_formats, destinations = _formats(destination, formats)
     parents = {item.parent for item in destinations}