ggplot2-python 4.0.2.9000.post3__py3-none-any.whl → 4.0.2.9000.post4__py3-none-any.whl

ggplot2_py/__init__.py

@@ -7,7 +7,7 @@ approach to creating statistical visualizations.
 
 from __future__ import annotations
 
-__version__ = "4.0.2.9000.post3"
+__version__ = "4.0.2.9000.post4"
 __r_commit__ = "c02c05a"
 
 # ---------------------------------------------------------------------------
@@ -962,6 +962,11 @@ __all__ = [
     "derive", "flip_data", "flipped_names", "has_flipped_aes",
     # Plugin discovery
     "discover_extensions", "list_extensions",
+    # Python-exclusive extension surface (README quickstart uses
+    # ``from ggplot2_py import *``; these would otherwise be invisible)
+    "ggplot_defaults", "BuildStage",
+    "GeomProtocol", "StatProtocol", "ScaleProtocol",
+    "CoordProtocol", "FacetProtocol", "PositionProtocol",
 ]
 
 # ---------------------------------------------------------------------------

ggplot2_py/plot.py

@@ -17,12 +17,14 @@ from __future__ import annotations
 import contextlib
 import contextvars
 import copy
+import inspect
 import warnings
 from functools import singledispatch
 from typing import (
     Any,
     Callable,
     Dict,
+    Iterable,
     List,
     Optional,
     Sequence,
@@ -142,6 +144,14 @@ def ggplot_defaults(
     that apply to all :func:`ggplot` calls within the ``with`` block,
     without affecting code outside.
 
+    The context defaults are applied at the **end** of the :func:`ggplot`
+    factory, after the plot's intrinsic defaults
+    (``CoordCartesian(default=True)``, ``FacetNull()``, empty :class:`Theme`)
+    are set.  The context-provided ``coord`` is marked ``default=True`` so a
+    subsequent ``plot + coord_X()`` replaces it silently (matching R's
+    ``update_ggplot.Coord`` semantics on default coords —
+    ``plot-construction.R:200-215``).
+
     Parameters
     ----------
     theme : Theme or dict, optional
@@ -184,6 +194,42 @@ def _get_context_defaults() -> Dict[str, Any]:
     return _ggplot_context.get()
 
 
+def _apply_context_defaults(p: "GGPlot") -> None:
+    """Overlay scoped defaults from :func:`ggplot_defaults` onto *p*.
+
+    Called from the :func:`ggplot` factory **after** the intrinsic defaults
+    (``CoordCartesian(default=True)``, ``FacetNull()``, empty :class:`Theme`)
+    have been installed, so context values can override them cleanly.
+
+    Each ctx value is shallow-copied before assignment so callers can reuse
+    the same ``coord_fixed()`` / ``facet_wrap(...)`` instance across multiple
+    ``ggplot()`` calls without us mutating their object.
+
+    For ``coord``, ``default = True`` is preserved on the copy so that a
+    later ``+ coord_X()`` replaces it silently (matches R's
+    ``update_ggplot.Coord`` short-circuit on default coords —
+    ``plot-construction.R:202``).
+    """
+    ctx = _get_context_defaults()
+    if not ctx:
+        return
+
+    if "theme" in ctx:
+        new_theme = ctx["theme"]
+        p.theme = new_theme.copy() if hasattr(new_theme, "copy") else new_theme
+
+    if "coord" in ctx:
+        p.coordinates = copy.copy(ctx["coord"])
+        p.coordinates.default = True
+
+    if "facet" in ctx:
+        p.facet = copy.copy(ctx["facet"])
+
+    if "mapping" in ctx:
+        ctx_map = ctx["mapping"]
+        p.mapping = aes(**{**ctx_map, **p.mapping})
+
+
 # ---------------------------------------------------------------------------
 # GGPlot class
 # ---------------------------------------------------------------------------
@@ -249,19 +295,11 @@ class GGPlot:
         self._meta: Dict[str, Any] = {}
         self._build_hooks: Dict[Tuple[str, str], List[Callable]] = {}
 
-        # Apply scoped context defaults (Python-exclusive feature).
-        ctx = _get_context_defaults()
-        if ctx:
-            if "theme" in ctx and not self.theme:
-                self.theme = ctx["theme"]
-            if "coord" in ctx and self.coordinates is None:
-                self.coordinates = ctx["coord"]
-            if "facet" in ctx and self.facet is None:
-                self.facet = ctx["facet"]
-            if "mapping" in ctx:
-                # Merge: context defaults as base, explicit mapping overrides
-                merged = aes(**{**ctx["mapping"], **self.mapping})
-                self.mapping = merged
+        # NOTE: scoped-default application (``ggplot_defaults``) is intentionally
+        # NOT done here.  It happens in the :func:`ggplot` factory via
+        # :func:`_apply_context_defaults` so that direct ``GGPlot(...)`` calls
+        # and ``_clone()`` (which uses ``copy.copy`` and skips ``__init__``) are
+        # unaffected by global context.
 
     # ------------------------------------------------------------------
     # Clone
@@ -303,9 +341,14 @@ class GGPlot:
             A :class:`BuildStage` constant (e.g.
             ``BuildStage.COMPUTE_STAT``).
         fn : callable
-            ``fn(data, **ctx) -> data_or_None``.  Receives the current
-            per-layer data list.  Return a new list to replace it, or
-            ``None`` to leave it unchanged.
+            ``fn(data, **ctx) -> list_or_anything``.  Receives the current
+            per-layer data list.  Return a new ``list`` to replace it; any
+            non-list return (including ``None``) leaves the data unchanged.
+            ``**ctx`` carries stage-specific context (``layout``, ``scales``,
+            ``guides``, ``theme``) — see :class:`BuildStage` for the per-stage
+            table.  Hook signatures are introspected, so you may declare
+            only the kwargs you want (``def fn(data, layout=None)``) or use
+            ``**kw`` to receive everything.
 
         Returns
         -------
@@ -535,6 +578,11 @@ def ggplot(
     p.coordinates.default = True
     p.facet = FacetNull()
 
+    # Scoped defaults (``ggplot_defaults`` context manager) overlay the
+    # intrinsic defaults set above.  No-op when no context is active, which
+    # preserves byte-level R parity for the bare ``ggplot(df, aes(...))`` case.
+    _apply_context_defaults(p)
+
     # R parity: ``plot$labels`` stores ONLY user-set labels.  The
     # aesthetic-derived defaults (``x="carat"``, ``y="price"`` etc.)
     # are computed lazily at render time by ``_setup_plot_labels``
@@ -596,14 +644,45 @@ class BuildStage:
     These are used with :meth:`GGPlot.add_build_hook` to register
     before/after callbacks on specific pipeline stages.  This is a
     **Python-exclusive** extension point — R's ggplot2 does not expose
-    hooks on individual build stages.
-
-    Example
-    -------
-    ::
-
-        p = ggplot(df, aes("x", "y"))
-        p.add_build_hook("after", BuildStage.COMPUTE_STAT, my_callback)
+    hooks on individual build stages — but **every stage name here
+    corresponds to a real operation in R's** ``plot-build.R``
+    ``ggplot_build.ggplot()`` method, in the same order.
+
+    Per-stage available ctx kwargs
+    ------------------------------
+    The hook receives ``(data, **ctx)``.  ``data`` is always the current
+    per-layer data list.  ``**ctx`` carries side context whose set depends
+    on the stage:
+
+    ===================== =================================================
+    Stage                  ctx keys
+    ===================== =================================================
+    LAYER_DATA             (none)
+    SETUP_LAYER            (none)
+    SETUP_LAYOUT           ``layout``
+    COMPUTE_AESTHETICS     (none)
+    TRANSFORM_SCALES       ``scales``
+    TRAIN_POSITION         ``layout``, ``scales``
+    COMPUTE_STAT           ``layout``
+    MAP_STAT               (none)
+    COMPUTE_GEOM_1         (none)
+    COMPUTE_POSITION       ``layout``
+    RETRAIN_POSITION       ``layout``, ``scales``
+    SETUP_GUIDES           ``layout``, ``guides``
+    TRAIN_NONPOSITION      ``scales`` (the non-position ScalesList)
+    COMPUTE_GEOM_2         ``theme``
+    FINISH_STAT            (none)
+    FINISH_DATA            (none)
+    ===================== =================================================
+
+    Hook signature flexibility — :func:`_run_hooks` introspects each hook
+    and forwards only ctx kwargs the hook can accept, so all of these
+    coexist::
+
+        p.add_build_hook("after", BuildStage.TRAIN_POSITION, lambda data: ...)
+        p.add_build_hook("after", BuildStage.TRAIN_POSITION, lambda data, **kw: ...)
+        p.add_build_hook("after", BuildStage.TRAIN_POSITION,
+                         lambda data, layout=None, scales=None: ...)
     """
 
     LAYER_DATA = "layer_data"
@@ -624,6 +703,26 @@ class BuildStage:
     FINISH_DATA = "finish_data"
 
 
+def _hook_accepts(hook: Callable, ctx_keys: Iterable[str]) -> Dict[str, bool]:
+    """Return a ``{ctx_key: accepted}`` map for *hook*.
+
+    A key is accepted if the hook either declares it as a named parameter or
+    declares a ``**kwargs`` catch-all.  Used by :func:`_run_hooks` to forward
+    only the ctx kwargs the hook actually wants — this is what lets
+    ``lambda data: ...`` (old-style) and ``lambda data, **ctx: ...`` and
+    ``def f(data, layout=None): ...`` all coexist without TypeErrors and
+    without resorting to ``try/except``.
+    """
+    sig = inspect.signature(hook)
+    params = sig.parameters
+    has_var_keyword = any(
+        p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values()
+    )
+    if has_var_keyword:
+        return {k: True for k in ctx_keys}
+    return {k: (k in params) for k in ctx_keys}
+
+
 def _run_hooks(
     plot: GGPlot,
     timing: str,
@@ -633,6 +732,21 @@ def _run_hooks(
 ) -> List[Any]:
     """Execute registered build hooks for (*timing*, *stage*).
 
+    Each hook is invoked as ``hook(data, **selected_ctx)`` where
+    ``selected_ctx`` is the subset of *ctx* that the hook actually accepts
+    (named param or ``**kwargs``).  This keeps three call styles working
+    in parallel:
+
+    * ``lambda data: ...``                       — no ctx forwarded
+    * ``lambda data, **kw: ...``                 — every ctx kwarg forwarded
+    * ``def f(data, layout=None, scales=None)``  — only matching kwargs
+
+    Hooks may return a new per-layer data list (an actual ``list``) to
+    replace the pipeline data, or any non-list value (including ``None``)
+    to leave it unchanged.  The list-only test means hooks that accidentally
+    return a scalar (``True``, the value from ``log.setdefault``, etc.)
+    don't silently corrupt downstream stages.
+
     Parameters
     ----------
     plot : GGPlot
@@ -644,7 +758,8 @@ def _run_hooks(
     data : list
         Current per-layer data list.
     **ctx
-        Additional context (e.g. ``layout``, ``scales``) passed to hooks.
+        Additional context.  The set of keys available depends on the
+        stage — see :class:`BuildStage` for the per-stage table.
 
     Returns
     -------
@@ -654,9 +769,14 @@ def _run_hooks(
     hooks = getattr(plot, "_build_hooks", None)
     if not hooks:
         return data
-    for hook in hooks.get((timing, stage), []):
-        result = hook(data, **ctx)
-        if result is not None:
+    targets = hooks.get((timing, stage), [])
+    if not targets:
+        return data
+    for hook in targets:
+        wanted = _hook_accepts(hook, ctx.keys())
+        kwargs = {k: v for k, v in ctx.items() if wanted.get(k, False)}
+        result = hook(data, **kwargs)
+        if isinstance(result, list):
             data = result
     return data
 
@@ -776,9 +896,11 @@ def _build_ggplot(plot):
     data = by_layer(lambda l, d: l.setup_layer(d, plot), layers, data, "setting up layer")
     data = _h(plot, "after", S.SETUP_LAYER, data)
 
-    # --- Setup layout ---
+    # --- Setup layout --- (R: plot-build.R:62 ``layout$setup``)
     layout = create_layout(plot.facet, plot.coordinates, getattr(plot, "layout", None))
+    data = _h(plot, "before", S.SETUP_LAYOUT, data, layout=layout)
     data = layout.setup(data, plot.data if isinstance(plot.data, pd.DataFrame) else pd.DataFrame(), plot.plot_env)
+    data = _h(plot, "after", S.SETUP_LAYOUT, data, layout=layout)
 
     # --- Compute aesthetics ---
     data = _h(plot, "before", S.COMPUTE_AESTHETICS, data)
@@ -793,21 +915,25 @@ def _build_ggplot(plot):
     # --- Setup plot labels ---
     _setup_plot_labels(plot, layers, data)
 
-    # --- Transform scales ---
+    # --- Transform scales --- (R: plot-build.R:70 ``lapply(data, scales$transform_df)``)
+    data = _h(plot, "before", S.TRANSFORM_SCALES, data, scales=scales)
     for i in range(len(data)):
         if data[i] is not None and not data[i].empty:
             data[i] = scales.transform_df(data[i])
+    data = _h(plot, "after", S.TRANSFORM_SCALES, data, scales=scales)
 
-    # --- Train and map positions ---
+    # --- Train and map positions --- (R: plot-build.R:77-78)
     scale_x = scales.get_scales("x")
     scale_y = scales.get_scales("y")
+    data = _h(plot, "before", S.TRAIN_POSITION, data, layout=layout, scales=scales)
     layout.train_position(data, scale_x, scale_y)
     data = layout.map_position(data)
+    data = _h(plot, "after", S.TRAIN_POSITION, data, layout=layout, scales=scales)
 
     # --- Compute statistics ---
-    data = _h(plot, "before", S.COMPUTE_STAT, data)
+    data = _h(plot, "before", S.COMPUTE_STAT, data, layout=layout)
     data = by_layer(lambda l, d: l.compute_statistic(d, layout), layers, data, "computing stat")
-    data = _h(plot, "after", S.COMPUTE_STAT, data)
+    data = _h(plot, "after", S.COMPUTE_STAT, data, layout=layout)
 
     # --- Map statistics ---
     data = _h(plot, "before", S.MAP_STAT, data)
@@ -834,20 +960,24 @@ def _build_ggplot(plot):
     data = _h(plot, "after", S.COMPUTE_GEOM_1, data)
 
     # --- Compute position ---
-    data = _h(plot, "before", S.COMPUTE_POSITION, data)
+    data = _h(plot, "before", S.COMPUTE_POSITION, data, layout=layout)
     data = by_layer(lambda l, d: l.compute_position(d, layout), layers, data, "computing position")
-    data = _h(plot, "after", S.COMPUTE_POSITION, data)
+    data = _h(plot, "after", S.COMPUTE_POSITION, data, layout=layout)
 
-    # --- Reset and retrain position scales ---
+    # --- Reset and retrain position scales --- (R: plot-build.R:99-101)
     scale_x = scales.get_scales("x")
     scale_y = scales.get_scales("y")
+    data = _h(plot, "before", S.RETRAIN_POSITION, data, layout=layout, scales=scales)
     layout.reset_scales()
     layout.train_position(data, scale_x, scale_y)
     layout.setup_panel_params()
     data = layout.map_position(data)
+    data = _h(plot, "after", S.RETRAIN_POSITION, data, layout=layout, scales=scales)
 
-    # --- Setup panel guides ---
+    # --- Setup panel guides --- (R: plot-build.R:104 ``layout$setup_panel_guides``)
+    data = _h(plot, "before", S.SETUP_GUIDES, data, layout=layout, guides=plot.guides)
     layout.setup_panel_guides(plot.guides, plot.layers)
+    data = _h(plot, "after", S.SETUP_GUIDES, data, layout=layout, guides=plot.guides)
 
     # --- Complete theme ---
     # R: plot@theme <- plot_theme(plot)  (plot-build.R:107)
@@ -856,14 +986,16 @@ def _build_ggplot(plot):
     # ``calc_element`` then returns ``None`` (no bg, no grid, no titles).
     plot.theme = complete_theme(plot.theme)
 
-    # --- Train non-position scales and guides ---
+    # --- Train non-position scales and guides --- (R: plot-build.R:113 ``lapply(data, npscales$train_df)``)
     npscales = scales.non_position_scales()
     if npscales.n() > 0:
         if hasattr(npscales, "set_palettes"):
             npscales.set_palettes(plot.theme)
+        data = _h(plot, "before", S.TRAIN_NONPOSITION, data, scales=npscales)
         for d in data:
             if d is not None:
                 npscales.train_df(d)
+        data = _h(plot, "after", S.TRAIN_NONPOSITION, data, scales=npscales)
         if plot.guides is not None and hasattr(plot.guides, "build"):
             plot.guides = plot.guides.build(npscales, plot.layers, plot.labels, data, plot.theme)
         for i in range(len(data)):
@@ -874,9 +1006,9 @@ def _build_ggplot(plot):
             plot.guides = plot.guides.get_custom()
 
     # --- Compute geom 2 ---
-    data = _h(plot, "before", S.COMPUTE_GEOM_2, data)
+    data = _h(plot, "before", S.COMPUTE_GEOM_2, data, theme=plot.theme)
     data = by_layer(lambda l, d: l.compute_geom_2(d, theme=plot.theme), layers, data, "setting up geom aesthetics")
-    data = _h(plot, "after", S.COMPUTE_GEOM_2, data)
+    data = _h(plot, "after", S.COMPUTE_GEOM_2, data, theme=plot.theme)
 
     # --- Finish statistics ---
     data = _h(plot, "before", S.FINISH_STAT, data)

ggplot2_py/protocols.py

@@ -1,33 +1,54 @@
 """
 Structural typing protocols for ggplot2_py GOG components.
 
-These :class:`~typing.Protocol` definitions specify the **contracts** that
-custom Geom, Stat, Scale, Coord, Facet, and Position classes should satisfy.
-They are ``@runtime_checkable``, so you can use ``isinstance()`` to verify
-compliance without requiring inheritance from the base classes.
-
-This is a **Python-exclusive** feature — R's ggplot2 has no equivalent
-compile-time or runtime contract checking.
+These :class:`~typing.Protocol` definitions are the **machine-readable
+contract** that every Geom, Stat, Scale, Coord, Facet, and Position class —
+shipped or user-supplied — must satisfy.
+
+What this module is **not**
+---------------------------
+* It is not a replacement for the base classes (``Geom``, ``Stat``, etc.).
+  Internal code dispatches off the base classes; the Protocols are an
+  orthogonal, structural view.
+* It does **not** make the base classes interchangeable with arbitrary
+  duck-typed objects in the build pipeline — the singledispatch + auto-
+  registration machinery still keys on the concrete base classes.
+
+What this module **is**
+-----------------------
+1. **Static-typing aid.**  Extension authors writing ``MyStat(Stat)`` get
+   mypy / pyright errors when they omit ``compute_group``, return the
+   wrong type, etc.  The signatures here mirror the base classes
+   verbatim — R's ``ggproto`` field signatures, transitively.
+2. **Live contract test.**  ``tests/test_protocols_contract.py`` iterates
+   every shipped subclass and asserts ``isinstance(instance, XxxProtocol)``.
+   Signature drift in a base class — or accidental method removal in a
+   subclass — fails CI immediately.  Without that test these Protocols
+   would just be documentation; with it they are an executable spec.
+
+R parity
+--------
+R has no Protocol mechanism (``ggproto`` is structural duck-typing all the
+way down), so the Protocols themselves are Python-exclusive.  However each
+method signature here is **derived from the corresponding R ``ggproto``
+field** by going through the Python base class (``Geom`` / ``Stat`` / …),
+which was ported from the R prototype.  So the contract is transitively
+R-aligned.
 
 Usage
 -----
-Mypy / pyright will flag violations statically::
+Static (mypy / pyright)::
 
     class MyStat(Stat):
         required_aes = ("x",)
-        # Missing compute_group → type error
+        # Forgetting compute_group is a static type error.
 
-At runtime you can check::
+Runtime (rare; the contract test in ``tests/`` already covers shipped
+classes — extension authors needing dynamic checks can do)::
 
     from ggplot2_py.protocols import StatProtocol
-    assert isinstance(my_stat, StatProtocol)
-
-Notes
------
-These protocols describe the *minimum* interface required for each
-component to participate in the GOG pipeline.  They do **not** replace
-the base classes (``Geom``, ``Stat``, etc.) — they complement them by
-enabling structural (duck-typed) checking.
+    if not isinstance(my_stat, StatProtocol):
+        raise TypeError("Stat extension is missing required methods")
 """
 
 from __future__ import annotations
@@ -36,6 +57,7 @@ from typing import (
     Any,
     Dict,
     List,
+    Optional,
     Protocol,
     Sequence,
     Tuple,
@@ -56,116 +78,125 @@ __all__ = [
 
 
 # ---------------------------------------------------------------------------
-# Geom
+# Geom — signatures from ``ggplot2_py.geom.Geom``
 # ---------------------------------------------------------------------------
 
 @runtime_checkable
 class GeomProtocol(Protocol):
-    """Contract for geometry objects.
-
-    A conforming Geom must declare its aesthetic requirements and provide
-    at least ``draw_panel`` or ``draw_group`` for rendering.
-    """
+    """Contract for geometry objects.  Mirrors ``Geom`` (geom.py:462)."""
 
     required_aes: Union[Tuple[str, ...], List[str]]
-    default_aes: Any  # Mapping or dict
-    draw_key: Any  # callable
+    default_aes: Any            # Mapping or dict
+    draw_key: Any               # callable (class-level attribute)
 
-    def setup_params(self, data: pd.DataFrame, params: dict) -> dict: ...
-    def setup_data(self, data: pd.DataFrame, params: dict) -> pd.DataFrame: ...
-    def draw_panel(self, data: pd.DataFrame, panel_params: dict,
-                   coord: Any, **kwargs: Any) -> Any: ...
+    def setup_params(self, data: pd.DataFrame, params: Dict[str, Any]) -> Dict[str, Any]: ...
+    def setup_data(self, data: pd.DataFrame, params: Dict[str, Any]) -> pd.DataFrame: ...
+    def draw_panel(self, *args: Any, **kwargs: Any) -> Any: ...
 
 
 # ---------------------------------------------------------------------------
-# Stat
+# Stat — signatures from ``ggplot2_py.stat.Stat``
 # ---------------------------------------------------------------------------
 
 @runtime_checkable
 class StatProtocol(Protocol):
-    """Contract for statistical transformation objects.
+    """Contract for statistical transformation objects.  Mirrors ``Stat``
+    (stat.py base class).
 
-    A conforming Stat must declare its aesthetic requirements and provide
-    ``compute_group`` (or ``compute_panel`` / ``compute_layer``).
+    The Protocol pins the three methods most likely to be user-overridden;
+    a Stat may also override ``compute_layer`` or ``compute_panel`` instead
+    of (or in addition to) ``compute_group``.
     """
 
     required_aes: Union[Tuple[str, ...], List[str]]
     default_aes: Any
 
-    def setup_params(self, data: pd.DataFrame, params: dict) -> dict: ...
-    def setup_data(self, data: pd.DataFrame, params: dict) -> pd.DataFrame: ...
-    def compute_group(self, data: pd.DataFrame, scales: Any,
-                      **params: Any) -> pd.DataFrame: ...
+    def setup_params(self, data: pd.DataFrame, params: Dict[str, Any]) -> Dict[str, Any]: ...
+    def setup_data(self, data: pd.DataFrame, params: Dict[str, Any]) -> pd.DataFrame: ...
+    def compute_group(self, data: pd.DataFrame, scales: Any, **params: Any) -> pd.DataFrame: ...
 
 
 # ---------------------------------------------------------------------------
-# Scale
+# Scale — signatures from ``ggplot2_py.scale.Scale``
+#
+# The base class accepts optional ``limits`` on ``map`` / ``get_breaks`` /
+# ``get_labels``.  The Protocol matches those signatures verbatim — narrower
+# signatures (omitting the optional kwargs) caused the original drift.
 # ---------------------------------------------------------------------------
 
 @runtime_checkable
 class ScaleProtocol(Protocol):
-    """Contract for scale objects.
-
-    A conforming Scale mediates between data space and aesthetic space
-    via train / transform / map.
-    """
+    """Contract for scale objects.  Mirrors ``Scale`` (scale.py:410)."""
 
-    aesthetics: Any  # list of str
+    aesthetics: Any             # list of str
 
     def train(self, x: Any) -> None: ...
     def transform(self, x: Any) -> Any: ...
-    def map(self, x: Any) -> Any: ...
-    def get_breaks(self) -> Any: ...
-    def get_labels(self, breaks: Any = None) -> Any: ...
+    def map(self, x: Any, limits: Optional[Any] = ...) -> Any: ...
+    def get_breaks(self, limits: Optional[Any] = ...) -> Any: ...
+    def get_labels(self, breaks: Optional[Any] = ...) -> Any: ...
     def clone(self) -> Any: ...
 
 
 # ---------------------------------------------------------------------------
-# Coord
+# Coord — signatures from ``ggplot2_py.coord.Coord``
 # ---------------------------------------------------------------------------
 
 @runtime_checkable
 class CoordProtocol(Protocol):
-    """Contract for coordinate system objects.
+    """Contract for coordinate system objects.  Mirrors ``Coord``
+    (coord.py:494).
 
-    A conforming Coord transforms data positions into viewport positions
-    and renders background / axes.
+    ``setup_params`` takes ``Any`` (not ``list``) because the call sites
+    pass per-layer data lists, single DataFrames, or panel-level dicts
+    depending on the Coord subclass.
     """
 
-    def setup_params(self, data: list) -> dict: ...
-    def transform(self, data: pd.DataFrame, panel_params: dict) -> pd.DataFrame: ...
-    def setup_panel_params(self, scale_x: Any, scale_y: Any,
-                           params: dict = ...) -> dict: ...
+    def setup_params(self, data: Any) -> Dict[str, Any]: ...
+    def transform(self, data: pd.DataFrame, panel_params: Dict[str, Any]) -> pd.DataFrame: ...
+    def setup_panel_params(
+        self,
+        scale_x: Any,
+        scale_y: Any,
+        params: Optional[Dict[str, Any]] = ...,
+    ) -> Dict[str, Any]: ...
 
 
 # ---------------------------------------------------------------------------
-# Facet
+# Facet — signatures from ``ggplot2_py.facet.Facet``
 # ---------------------------------------------------------------------------
 
 @runtime_checkable
 class FacetProtocol(Protocol):
-    """Contract for faceting specification objects.
-
-    A conforming Facet computes panel layout and assigns data to panels.
-    """
-
-    def compute_layout(self, data: list, params: dict) -> pd.DataFrame: ...
-    def map_data(self, data: pd.DataFrame, layout: pd.DataFrame,
-                 params: dict) -> pd.DataFrame: ...
+    """Contract for faceting specification objects.  Mirrors ``Facet``
+    (facet.py:490)."""
+
+    def compute_layout(
+        self,
+        data: List[pd.DataFrame],
+        params: Dict[str, Any],
+    ) -> pd.DataFrame: ...
+    def map_data(
+        self,
+        data: pd.DataFrame,
+        layout: pd.DataFrame,
+        params: Dict[str, Any],
+    ) -> pd.DataFrame: ...
 
 
 # ---------------------------------------------------------------------------
-# Position
+# Position — signatures from ``ggplot2_py.position.Position``
 # ---------------------------------------------------------------------------
 
 @runtime_checkable
 class PositionProtocol(Protocol):
-    """Contract for position adjustment objects.
-
-    A conforming Position adjusts data coordinates (e.g. dodge, stack)
-    after stat computation but before coordinate transformation.
-    """
-
-    def setup_params(self, data: pd.DataFrame) -> dict: ...
-    def compute_layer(self, data: pd.DataFrame, params: dict,
-                      layout: Any) -> pd.DataFrame: ...
+    """Contract for position adjustment objects.  Mirrors ``Position``
+    (position.py:200)."""
+
+    def setup_params(self, data: pd.DataFrame) -> Dict[str, Any]: ...
+    def compute_layer(
+        self,
+        data: pd.DataFrame,
+        params: Dict[str, Any],
+        layout: Any,
+    ) -> pd.DataFrame: ...

ggplot2_py/save.py

@@ -8,9 +8,9 @@ formats via Cairo.
 from __future__ import annotations
 
 import os
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, Optional, Union
 
-from ggplot2_py._compat import cli_abort, cli_warn, cli_inform
+from ggplot2_py._compat import cli_abort, cli_inform
 
 __all__ = [
     "ggsave",
@@ -204,7 +204,7 @@ def ggsave(
         If the target directory does not exist and *create_dir* is
         ``False``.
     """
-    from grid_py import grid_draw, grid_newpage, get_state
+    from grid_py import grid_draw, get_state
     from grid_py.renderer import CairoRenderer
 
     # Resolve DPI
@@ -255,6 +255,11 @@ def ggsave(
     if is_ggplot(plot):
         built = ggplot_build(plot)
         gtable = ggplot_gtable(built)
+    elif hasattr(plot, "to_gtable"):
+        # patchwork-python composes plots as a Patchwork object with an
+        # explicit to_gtable() method. Draw that gtable rather than handing
+        # the wrapper to grid_draw(), which cannot render it directly.
+        gtable = plot.to_gtable()
     else:
         gtable = plot
 

ggplot2_py/scale.py

@@ -1151,15 +1151,66 @@ class ScaleDiscrete(Scale):
         x_str = [str(v) for v in np.asarray(x)]
         limits_str = [str(l) for l in limits]
 
+        na_val = self.na_value if self.na_translate else np.nan
+
+        # ---- Named-palette path (R: ggplot2/R/scale-.R:1322-1340) -------
+        # When the palette function returned a *named* mapping (i.e. a
+        # ``dict`` carrying value→aesthetic pairs), R's algorithm is:
+        #
+        #   pal_names <- names(pal)
+        #   if (!is.null(pal_names)) {
+        #     pal[is.na(match(pal_names, limits))] <- na_value   # (a)
+        #     pal <- vec_set_names(pal, NULL)
+        #     limits <- pal_names                                 # (b)
+        #   }
+        #   pal <- c(pal, na_value)                               # (c)
+        #   pal_match <- vec_slice(
+        #     pal, match(as.character(x), limits, nomatch = vec_size(pal))
+        #   )                                                     # (d)
+        #
+        # Crucially:
+        #   * (a) blanks pal entries whose names are *not* in the original
+        #     limits — so an out-of-data category looked up explicitly via
+        #     map(value) returns na_value rather than the user's colour;
+        #   * (b) reassigns ``limits`` to ``pal_names`` so the subsequent
+        #     match is by name (encoded as a position lookup against the
+        #     full named-vector key list);
+        #   * (c) appends na_value as a sentinel at position ``len(pal)``;
+        #   * (d) ``match`` returns ``len(pal)`` for unmatched x, which
+        #     ``vec_slice`` turns into the appended na_value.
+        #
+        # The Python translation below is structurally identical; only
+        # surface idioms differ (dict comprehension instead of
+        # ``vec_slice`` / ``match``).
         if isinstance(pal, dict):
-            pal_list = list(pal.values())
-        elif isinstance(pal, np.ndarray):
+            pal_named = {str(k): v for k, v in pal.items()}
+            limits_set = set(limits_str)
+            # (a) blank entries whose name is not in the original limits.
+            pal_filtered = [
+                (v if k in limits_set else na_val)
+                for k, v in pal_named.items()
+            ]
+            # (b) limits ← pal_names.
+            new_limits = list(pal_named.keys())
+            # (c) append na_value sentinel for unmatched positions.
+            sentinel_idx = len(pal_filtered)
+            pal_with_sentinel = pal_filtered + [na_val]
+            # (d) positional lookup via match(x, new_limits).
+            result = []
+            for v in x_str:
+                try:
+                    idx = new_limits.index(v)
+                except ValueError:
+                    idx = sentinel_idx
+                result.append(pal_with_sentinel[idx])
+            return np.array(result)
+
+        # ---- Unnamed-palette path (R: same map(), pal_names is NULL) ----
+        if isinstance(pal, np.ndarray):
             pal_list = list(pal)
         else:
             pal_list = list(pal) if hasattr(pal, "__iter__") else [pal]
 
-        na_val = self.na_value if self.na_translate else np.nan
-
         result = []
         for v in x_str:
             if v in limits_str:

ggplot2_py/scales/__init__.py

@@ -371,11 +371,33 @@ def _manual_scale(
                 named_values[b] = values_list[i]
         values = named_values
 
+    # Mirror R `manual_scale` (ggplot2/R/scale-manual.R:183-188):
+    #
+    #   pal <- function(n) {
+    #     if (n > length(values)) {
+    #       cli::cli_abort("Insufficient values in manual scale. ...")
+    #     }
+    #     values
+    #   }
+    #
+    # In R `values` is a (possibly named) atomic vector and the palette
+    # always returns it whole — names included; the count check is a
+    # guard, not a slice.  ``ScaleDiscrete$map`` then dispatches on
+    # ``names(pal)`` to decide name vs position lookup.  We mirror that
+    # split here: dict → named palette branch (returned as-is), list →
+    # unnamed branch (sliced to ``n`` to match the existing call sites
+    # that index positionally).  In both branches we keep R's
+    # ``n > length(values)`` abort so misuse fails the same way.
     if isinstance(values, dict):
-        _vals = values
+        _vals = dict(values)
+        _n_vals = len(_vals)
 
-        def pal(n: int) -> list:
-            return list(_vals.values())[:n] if len(_vals) >= n else list(_vals.values())
+        def pal(n: int) -> dict:
+            if n > _n_vals:
+                cli_abort(
+                    f"Insufficient values in manual scale. {n} needed but only {_n_vals} provided."
+                )
+            return _vals
     else:
         _vals_list = list(values)
 

{ggplot2_python-4.0.2.9000.post3.dist-info → ggplot2_python-4.0.2.9000.post4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ggplot2-python
-Version: 4.0.2.9000.post3
+Version: 4.0.2.9000.post4
 Summary: Python port of the R ggplot2 package (tracks R ggplot2 4.0.2.9000)
 Project-URL: Homepage, https://github.com/Bio-Babel/ggplot2-python
 Project-URL: Repository, https://github.com/Bio-Babel/ggplot2-python
@@ -48,17 +48,17 @@ Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocstrings[python]; extra == 'docs'
 Description-Content-Type: text/markdown
 
-# ggplot2_py <a href="https://github.com/R2pyBioinformatics/ggplot2_py"><img src="assets/ggplot2_py_logo.png" align="right" height="138" alt="ggplot2_py logo" /></a>
+# ggplot2-python <a href="https://github.com/Bio-Babel/ggplot2-python"><img src="assets/ggplot2_py_logo.png" align="right" height="138" alt="ggplot2-python logo" /></a>
 
 [![PyPI](https://img.shields.io/pypi/v/ggplot2-python)](https://pypi.org/project/ggplot2-python/)
 
-AI-assisted Python port of the R **ggplot2** package — Create Elegant Data Visualisations Using the Grammar of Graphics.
+AI-assisted port of the python **ggplot2** package — Create Elegant Data Visualisations Using the Grammar of Graphics.
 
 ## Overview
 
-ggplot2_py implements the grammar of graphics in Python, faithfully porting R's ggplot2 using pandas DataFrames as the data container and a Cairo-based rendering backend. It supports 47 geoms, 32 stats, faceting, coordinate systems, themes, guides, and 130+ scales.
+ggplot2-python implements the grammar of graphics in Python, faithfully porting R's ggplot2 using pandas DataFrames as the data container and a Cairo-based rendering backend. It supports 47 geoms, 32 stats, faceting, coordinate systems, themes, guides, and 130+ scales.
 
-Beyond a direct port, ggplot2_py adds **Python-exclusive features** that extend the Grammar of Graphics with Python-native idioms while preserving full orthogonality of GOG components.
+Beyond a direct port, ggplot2-python adds **Python-exclusive features** that extend the Grammar of Graphics with Python-native idioms while preserving full orthogonality of GOG components.
 
 ## Python-Exclusive Features
 
@@ -73,6 +73,7 @@ These capabilities have no R equivalent and leverage Python-specific language fe
 | **Auto-registration** | `__init_subclass__` | `class GeomStar(Geom): ...` auto-registers; no manual wiring needed |
 | **Protocol contracts** | `typing.Protocol` | `isinstance(my_geom, GeomProtocol)` — structural type checking for extensions |
 | **Scoped defaults** | `contextvars.ContextVar` | `with ggplot_defaults(theme=theme_minimal()): ...` — thread-safe scoped defaults |
+| **Functional composition** | `sum` / `reduce` over `__add__` | `sum(parts, start=ggplot(data))` — compose plots without the `+` operator, useful for programmatic plot construction |
 
 ## Installation
 
@@ -85,7 +86,7 @@ For a local development:
 
 ```bash
 git clone https://github.com/Bio-Babel/ggplot2-python.git
-cd ggplot2_py
+cd ggplot2-python
 pip install -e ".[dev]"
 ```
 
@@ -145,6 +146,46 @@ with ggplot_defaults(theme=theme_minimal()):
 # Outside: no defaults
 ```
 
+### Functional composition with `sum()` / `reduce()` (Python-exclusive)
+
+The `+` operator is the canonical ggplot2 syntax.  Because `GGPlot.__add__` is defined and every component family is registered with
+the `update_ggplot` singledispatch generic, **Python's iterable-composition
+idioms also work directly** — useful for programmatic plot building, list
+comprehensions, or just function-style code:
+
+```python
+# 1) `sum(parts, start=ggplot(data))` — the canonical function-style form
+def fnplot(data, *parts):
+    return sum(parts, start=ggplot(data))
+
+fnplot(
+    mpg,
+    aes(x="displ", y="hwy", colour="class"),
+    geom_point(),
+    geom_smooth(method="lm"),
+    facet_wrap("drv"),
+    theme_minimal(),
+)
+
+# 2) `sum` over an iterable, no helper needed:
+sum(
+    [aes(x="displ", y="hwy"), geom_point(), theme_minimal()],
+    start=ggplot(mpg),
+)
+
+# 3) `functools.reduce` — the canonical Python composition operator:
+from functools import reduce
+from operator import add
+reduce(add, [aes(x="displ", y="hwy"), geom_point(), theme_minimal()], ggplot(mpg))
+
+# 4) List on the RHS of `+` — recursive add via the list-dispatch:
+ggplot(mpg, aes("displ", "hwy")) + [geom_point(), geom_smooth(), theme_minimal()]
+```
+
+> One caveat: Python's built-in `sum` has the signature
+> `sum(iterable, /, start=0)` — it accepts *one* iterable plus an optional
+> `start`, **not** variadic arguments.  `sum(a, b, c, d)` raises `TypeError`;
+
 ## Tutorials
 
 ### User Tutorials
@@ -160,11 +201,11 @@ with ggplot_defaults(theme=theme_minimal()):
 - [Build Hooks](tutorials/build_hooks.ipynb) — intercepting the 16-stage build pipeline
 
 ### Developer Guide
-- [Developer Guide: Extending ggplot2_py](tutorials/developer_guide.ipynb) — comprehensive guide covering ggproto system, custom Stat/Geom creation, Protocol contracts, singledispatch, hooks, auto-registration, context manager, and packaging
+- [Developer Guide: Extending ggplot2-python](tutorials/developer_guide.ipynb) — comprehensive guide covering ggproto system, custom Stat/Geom creation, Protocol contracts, singledispatch, hooks, auto-registration, context manager, and packaging
 
 ## Extension Architecture
 
-ggplot2_py is designed as an **extensible platform**. The following table summarises all extension points:
+ggplot2-python is designed as an **extensible platform**. The following table summarises all extension points:
 
 | Extension point | Mechanism | How to use |
 |----------------|-----------|-----------|

{ggplot2_python-4.0.2.9000.post3.dist-info → ggplot2_python-4.0.2.9000.post4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ggplot2_py/__init__.py,sha256=_mjXxq88zWT_Vw5R_L89MBmIYs7ijslG3zZBCkYOXU4,29435
+ggplot2_py/__init__.py,sha256=kGTScY1HIhRm_caC48k6fj2CKmuf_tbxEDw35aPgcXE,29720
 ggplot2_py/_compat.py,sha256=G3f5pkIluuEF4F9Th25H03dON2hAKeFH6UJAnzUV2fM,12187
 ggplot2_py/_defaults.py,sha256=AzvkO4xCwscJutFdUxfk0KATdthR5yjzFs59FIcQr_w,6039
 ggplot2_py/_make_constructor.py,sha256=qwGBd3S1CYMfRsYNpVfvpzIlSAhNz_IMH6f5Ggo5Ix4,15481
@@ -23,14 +23,14 @@ ggplot2_py/labels.py,sha256=8JkSdSdpICcItyBv5RPh4PmzF4TzOnF5_umTHhul5Ro,8306
 ggplot2_py/layer.py,sha256=BjyWkbL1NNWGrBODpKuo-nYYqGs-jTxw3LKHq2ynbls,32748
 ggplot2_py/layout.py,sha256=QkaGP3anrQYS8vIFMlsz3jKmblHUTYGSevCXIMGlDns,25341
 ggplot2_py/limits.py,sha256=e1WezeXnqPUKn6aaNgyDkLkF1JbxustqfQorKrmjPHI,8219
-ggplot2_py/plot.py,sha256=tLjwLsR6dU5MIfWDXVigZxlY2wP46RIxj_ye_4EFCzg,42346
+ggplot2_py/plot.py,sha256=WPhTYF48klfAB063XFOlTqZvyB1w5Kiff-UhUYnER2Q,49276
 ggplot2_py/plot_render.py,sha256=DP0gnDV-s_UHHBYiFdHgKgkhjLgO3oEZOO2vPGiMUKo,62864
 ggplot2_py/position.py,sha256=L2NSJ9TsVMlV1PjJtMsgFAuqi-f9fQ7epPdFVeKgtOk,34854
-ggplot2_py/protocols.py,sha256=7d34T7v7NLg3N1bSEPmmPFrV-5BZvnzBsbpiqnDatZA,5353
+ggplot2_py/protocols.py,sha256=wUjEobsa_k65E5Put1fTXHgejnAIwkF6dBsIE63LaAE,7276
 ggplot2_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ggplot2_py/qplot.py,sha256=gZ6BWdU2bZwN1zwJCi9unOeWGDVEmV_FQPqb2X6-2TU,6551
-ggplot2_py/save.py,sha256=CVj-oZzdzUm14JQv6nQsaxgJcurDr1M-4Rjs2U0xoqQ,9055
-ggplot2_py/scale.py,sha256=Izn3dpjY9eE7cPHPmljk5XtpdbL1aA5zR-cmhrCk4Gc,88101
+ggplot2_py/save.py,sha256=-VK4iN5JPri8pN2c0bvznaoTHncMQ_tmsDTqff8bdRs,9308
+ggplot2_py/scale.py,sha256=9L6tDzQebchrIdhw4KR6qi8c0OcGgVbawl9anMDaLbs,90650
 ggplot2_py/stat.py,sha256=A83Gar5D6110UBvIa4EneLGP4wSlT2aXtp6Wf0DVdT0,212407
 ggplot2_py/theme.py,sha256=VHESBgKu64hw88Wxri2N5A19Uj3GeWkYim1hKcyDbk4,14066
 ggplot2_py/theme_defaults.py,sha256=BgvjPovcXN-oRcdyfYmT7hV9PhQG6XzcjzJ66Ruvb6E,37070
@@ -49,9 +49,9 @@ ggplot2_py/resources/msleep.csv,sha256=Cm5ArhLjOFXbU5Ubo3slSyZgv36TCjMECQY9L9dY2
 ggplot2_py/resources/presidential.csv,sha256=-IVpCt0WvBwYerzte6KOaDBpThxj2GIx49ChOoRcdfk,555
 ggplot2_py/resources/seals.csv,sha256=VEuSEBLz3Fj14eBdM6hp6M6GpH2lqN5ekT_d2Mk1rK0,57035
 ggplot2_py/resources/txhousing.csv,sha256=RdHoH5W9bud_DzsefIc8yNOFaxMl6IDDKMiP68aoIoY,523993
-ggplot2_py/scales/__init__.py,sha256=n1NLGW0cOeFxOYkj_yS2rvec4p9N1ZJBsugPG2TOHgY,100013
+ggplot2_py/scales/__init__.py,sha256=ZXNYhLv1yVvjfu0K7awXR31aUq3Xe6E_JQ4melGnsok,100966
 ggplot2_py/stats/__init__.py,sha256=X_WSwq3jS2iJPGy7jEu_tXSQvVrIvC-5pm4ag2qTLVI,222
-ggplot2_python-4.0.2.9000.post3.dist-info/METADATA,sha256=iLJmmFph2oZLXvGkDhU11o3OkKk72VvdQCj8ivRvIO0,8336
-ggplot2_python-4.0.2.9000.post3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-ggplot2_python-4.0.2.9000.post3.dist-info/licenses/LICENSE,sha256=E0GJjw07cYRmJYj_8UZKbhevWQ-Swd3nVR6qBddvz9c,39
-ggplot2_python-4.0.2.9000.post3.dist-info/RECORD,,
+ggplot2_python-4.0.2.9000.post4.dist-info/METADATA,sha256=JODWYbilr8t5ox3fLqkSh00iUz4to5HjrIWcCJFfusA,9976
+ggplot2_python-4.0.2.9000.post4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ggplot2_python-4.0.2.9000.post4.dist-info/licenses/LICENSE,sha256=E0GJjw07cYRmJYj_8UZKbhevWQ-Swd3nVR6qBddvz9c,39
+ggplot2_python-4.0.2.9000.post4.dist-info/RECORD,,