ggplot2-python 4.0.2.9000.post3__tar.gz → 4.0.2.9000.post5__tar.gz

{ggplot2_python-4.0.2.9000.post3 → ggplot2_python-4.0.2.9000.post5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ggplot2-python
-Version: 4.0.2.9000.post3
+Version: 4.0.2.9000.post5
 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 |
 |----------------|-----------|-----------|
@@ -177,5 +218,10 @@ ggplot2_py is designed as an **extensible platform**. The following table summar
 | Custom `+` types | `@update_ggplot.register(MyClass)` | Register any Python class for the `+` operator |
 | Custom plot types | `@ggplot_build.register(MyPlot)` | Override the entire build pipeline |
 | Build hooks | `plot.add_build_hook(timing, stage, fn)` | Intercept data at any pipeline stage |
+| Per-plot `+` hooks | `register_pre_add_hook(plot, hook)` | Per-plot transformer fires on the next `+`; supports stateful, self-removing hooks (R: `+.<dynamic_class>`) |
+| Plot-env constructor injection | `plot.plot_env.push({...})` | Override `find_scale` / `add_defaults` per-plot — install a custom `scale_<aes>_<type>` constructor (R: `find_global`) |
+| Instance-as-parent ggproto | `ggproto("Name", instance, method=fn)` | Clone a Geom/Stat/Scale instance with method overrides (R: `ggproto(NULL, inst, method = fn)`) |
+| Explicit method binding | `bind_method(obj, name, fn)` | Bind an arbitrary callable as a method when its first arg isn't named `self` |
+| Extension toolkit | `from ggplot2_py.extension import …` | Pre-built helpers (`clone_layer`, `rename_aes_in_*`, `protect`, `palette_for_aes`, …) for cross-cutting extensions |
 | Protocol validation | `isinstance(obj, GeomProtocol)` | Verify structural conformance |
 | Scoped defaults | `with ggplot_defaults(theme=...):` | Thread-safe scoped defaults |

{ggplot2_python-4.0.2.9000.post3 → ggplot2_python-4.0.2.9000.post5}/README.md

@@ -1,14 +1,14 @@
-# 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
 
@@ -23,6 +23,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
 
@@ -35,7 +36,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]"
 ```
 
@@ -95,6 +96,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
@@ -110,11 +151,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 |
 |----------------|-----------|-----------|
@@ -127,5 +168,10 @@ ggplot2_py is designed as an **extensible platform**. The following table summar
 | Custom `+` types | `@update_ggplot.register(MyClass)` | Register any Python class for the `+` operator |
 | Custom plot types | `@ggplot_build.register(MyPlot)` | Override the entire build pipeline |
 | Build hooks | `plot.add_build_hook(timing, stage, fn)` | Intercept data at any pipeline stage |
+| Per-plot `+` hooks | `register_pre_add_hook(plot, hook)` | Per-plot transformer fires on the next `+`; supports stateful, self-removing hooks (R: `+.<dynamic_class>`) |
+| Plot-env constructor injection | `plot.plot_env.push({...})` | Override `find_scale` / `add_defaults` per-plot — install a custom `scale_<aes>_<type>` constructor (R: `find_global`) |
+| Instance-as-parent ggproto | `ggproto("Name", instance, method=fn)` | Clone a Geom/Stat/Scale instance with method overrides (R: `ggproto(NULL, inst, method = fn)`) |
+| Explicit method binding | `bind_method(obj, name, fn)` | Bind an arbitrary callable as a method when its first arg isn't named `self` |
+| Extension toolkit | `from ggplot2_py.extension import …` | Pre-built helpers (`clone_layer`, `rename_aes_in_*`, `protect`, `palette_for_aes`, …) for cross-cutting extensions |
 | Protocol validation | `isinstance(obj, GeomProtocol)` | Verify structural conformance |
 | Scoped defaults | `with ggplot_defaults(theme=...):` | Thread-safe scoped defaults |

{ggplot2_python-4.0.2.9000.post3 → ggplot2_python-4.0.2.9000.post5}/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.post5"
 __r_commit__ = "c02c05a"
 
 # ---------------------------------------------------------------------------
@@ -23,7 +23,10 @@ from ggplot2_py.ggproto import (
     ggproto,
     ggproto_parent,
     is_ggproto,
+    fetch_ggproto,
+    bind_method,
 )
+from ggplot2_py._env import PlotEnv
 
 # ---------------------------------------------------------------------------
 # Aesthetics
@@ -62,6 +65,8 @@ from ggplot2_py.plot import (
     ggplotGrob,
     ggplot_add,
     add_gg,
+    register_pre_add_hook,
+    unregister_pre_add_hook,
     get_last_plot,
     set_last_plot,
     last_plot,
@@ -734,7 +739,8 @@ __all__ = [
     # Version
     "__version__",
     # Core
-    "GGProto", "ggproto", "ggproto_parent", "is_ggproto",
+    "GGProto", "ggproto", "ggproto_parent", "is_ggproto", "fetch_ggproto",
+    "bind_method", "PlotEnv",
     "Waiver", "waiver", "is_waiver",
     # Aesthetics
     "aes", "after_stat", "after_scale", "stage", "vars",
@@ -745,7 +751,9 @@ __all__ = [
     "Layer", "layer", "is_layer",
     # Plot
     "ggplot", "is_ggplot", "ggplot_build", "ggplot_gtable", "ggplotGrob",
-    "ggplot_add", "add_gg", "get_last_plot", "set_last_plot", "last_plot",
+    "ggplot_add", "add_gg",
+    "register_pre_add_hook", "unregister_pre_add_hook",
+    "get_last_plot", "set_last_plot", "last_plot",
     "print_plot", "get_alt_text", "update_ggplot",
     # Introspection
     "get_layer_data", "get_layer_grob", "get_panel_scales",
@@ -962,6 +970,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_python-4.0.2.9000.post3 → ggplot2_python-4.0.2.9000.post5}/ggplot2_py/_compat.py

@@ -8,6 +8,8 @@ ggplot2 relies on, adapted for idiomatic Python usage.
 from __future__ import annotations
 
 import importlib
+import logging
+import sys
 import warnings
 from typing import Any, NoReturn, Optional
 
@@ -41,6 +43,40 @@ __all__ = [
 # ---------------------------------------------------------------------------
 # CLI messaging helpers (rlang / cli replacements)
 # ---------------------------------------------------------------------------
+#
+# R distinguishes three output channels:
+#
+#   * ``cli::cli_abort`` — error stream (``stop``)        → Python ``raise``
+#   * ``cli::cli_warn``  — warning stream (``warning``)   → ``warnings.warn(..., UserWarning)``
+#   * ``cli::cli_inform``— message stream (``message``)   → ``logging.INFO``
+#
+# In R these are three separate streams: ``suppressWarnings`` does not
+# silence messages, ``suppressMessages`` does not silence warnings, and
+# the test framework's ``expect_message`` / ``expect_warning`` discriminate
+# between them.  This Python port matches that split — informational
+# output (e.g. ``ggsave``'s "Saving …", ``stat_bin``'s "using bins = 30")
+# routes through the standard :mod:`logging` module at INFO level so
+# pytest does not count it as a warning, ``warnings.catch_warnings``
+# does not capture it, and ``logging.getLogger("ggplot2_py").setLevel(
+# logging.WARNING)`` mirrors R's ``suppressMessages``.
+
+#: Package-level logger.  Library convention says "do not configure the
+#: root logger" — instead we attach a single :class:`logging.StreamHandler`
+#: to *this* logger and set :attr:`Logger.propagate` to ``False``, so the
+#: handler runs even when the user has not called
+#: :func:`logging.basicConfig` and ours never duplicates onto theirs.
+_logger: logging.Logger = logging.getLogger("ggplot2_py")
+if not _logger.handlers:
+    _handler = logging.StreamHandler(stream=sys.stderr)
+    # R's ``message()`` prints the bare message text (no level/timestamp
+    # prefix); mirror that to keep ggplot2_py output indistinguishable
+    # from the R original.
+    _handler.setFormatter(logging.Formatter("%(message)s"))
+    _handler.setLevel(logging.INFO)
+    _logger.addHandler(_handler)
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+
 
 def cli_abort(
     message: str,
@@ -81,7 +117,13 @@ def cli_warn(
     call: Optional[str] = None,
     **kwargs: Any,
 ) -> None:
-    """Issue a ``UserWarning`` with a formatted message.
+    """Issue a ``UserWarning`` — R *warning* stream equivalent.
+
+    Counterpart of :func:`cli_inform`: this function targets the
+    Python warning stream (matching R ``cli::cli_warn`` / ``warning()``),
+    while informational output goes through :mod:`logging` at INFO
+    level.  Keeping the two streams separate preserves R's
+    ``suppressWarnings`` / ``suppressMessages`` granularity.
 
     Parameters
     ----------
@@ -105,24 +147,39 @@ def cli_inform(
     call: Optional[str] = None,
     **kwargs: Any,
 ) -> None:
-    """Emit an informational message via Python's :mod:`warnings`.
+    """Emit an informational message at ``logging.INFO`` level.
+
+    R analogue: ``cli::cli_inform`` / ``rlang::inform`` write to R's
+    *message* stream — informational output that is **distinct from**
+    R's *warning* stream (see :func:`cli_warn`).  Python's natural
+    equivalent is the :mod:`logging` module at INFO level:
 
-    Mirrors R ``cli::cli_inform`` / ``rlang::inform`` which always write
-    to stderr regardless of session type. Routing through ``warnings``
-    lets pytest, ``warnings.catch_warnings``, and user filters capture
-    or silence the message — matching the way R lets users wrap
-    ``suppressMessages({...})`` around an expression.
+    * pytest does not count INFO records as warnings (its
+      ``--strict-warnings`` flag and "warnings summary" only track
+      :mod:`warnings`);
+    * ``warnings.catch_warnings`` does not capture them;
+    * the user opt-out parallels R's ``suppressMessages`` —
+      ``logging.getLogger("ggplot2_py").setLevel(logging.WARNING)``
+      silences cli_inform output without affecting cli_warn.
+
+    By default the package logger has a :class:`logging.StreamHandler`
+    attached at INFO level (R-faithful: ``cli_inform`` messages are
+    visible to stderr unless explicitly suppressed).
 
     Parameters
     ----------
     message : str
-        Informational message.
+        Informational message.  May contain ``{name}``-style placeholders.
     call : str, optional
         Name of the calling function (unused; matches R signature).
     **kwargs : Any
         Substitution values for placeholders in *message*.
     """
-    warnings.warn(message, UserWarning, stacklevel=2)
+    try:
+        formatted = message.format(**kwargs) if kwargs else message
+    except (KeyError, IndexError):
+        formatted = message
+    _logger.info(formatted)
 
 
 # ---------------------------------------------------------------------------

ggplot2_python-4.0.2.9000.post5/ggplot2_py/_env.py

@@ -0,0 +1,160 @@
+"""
+PlotEnv — layered namespace lookup for scale/guide constructors.
+
+Port of R's ``find_global(name, env, mode = "function")`` (R ref:
+``ggplot2/R/scale-type.R:39-54``).  Quoting the R source:
+
+    Look for object first in parent environment and if not found, then in
+    ggplot2 namespace environment.  This makes it possible to override
+    default scales by setting them in the parent environment.
+
+In R, ``plot@plot_env`` is the environment where the plot was constructed
+(typically ``parent.frame()`` at ``ggplot()`` call time), and a chain of
+environments terminates in ``asNamespace("ggplot2")``.  ggnewscale
+exploits this by **injecting** ``scale_<bumped_aes>_<type>`` functions
+into ``plot@plot_env`` (R ref:
+``ggnewscale/R/rename-aes.R:87-104``), so that when build-time
+default-scale resolution runs, the injected constructor wins.
+
+In Python, the closest equivalent is a list-of-namespaces walked in
+order, with the ``ggplot2_py.scales`` module as the implicit fallback
+layer.  :class:`PlotEnv` encapsulates that — call sites pass a
+``PlotEnv`` to :func:`find_scale` / ``ScalesList.add_defaults`` /
+``ScalesList.add_missing``, and lookups walk the user-pushed layers
+first.
+
+A *namespace* is anything that responds to attribute access **or**
+mapping ``__getitem__``.  ``dict``, ``types.ModuleType``,
+``types.SimpleNamespace``, ``argparse.Namespace``, and arbitrary
+objects implementing ``__getattr__`` all work.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional
+
+__all__ = ["PlotEnv"]
+
+
+class PlotEnv:
+    """Layered scale/guide-constructor lookup table for a plot.
+
+    Mirrors the *effective* behaviour of R's ``plot@plot_env`` + the
+    ``find_global`` walk: lookups proceed through the user-pushed
+    layers in **last-pushed-first-checked** order (LIFO), then fall
+    back to the ``ggplot2_py.scales`` module.
+
+    Each layer may be any object that supports either attribute access
+    (``getattr(layer, name)``) or mapping access (``layer[name]``); the
+    first that yields a non-``None`` value wins.
+
+    Examples
+    --------
+    >>> env = PlotEnv()
+    >>> env.push({"scale_colour_continuous": my_factory})
+    >>> env.lookup("scale_colour_continuous") is my_factory
+    True
+
+    The implicit fallback to ``ggplot2_py.scales`` is intentionally
+    **not** included in :attr:`layers` so that :meth:`clone` produces
+    an env with the same user-visible chain.
+    """
+
+    def __init__(self, *layers: Any) -> None:
+        # Layers are stored in **push order**.  Lookup walks them in
+        # reverse so that the most recently pushed layer wins, matching
+        # R's environment-chain semantics (the immediate parent is
+        # checked before more ancestral ones).
+        self._layers: List[Any] = [l for l in layers if l is not None]
+
+    # -- Mutation ----------------------------------------------------------
+
+    def push(self, layer: Any) -> None:
+        """Add a new lookup layer.  Last-pushed wins on conflicts.
+
+        Parameters
+        ----------
+        layer : object
+            Any dict-like or attribute-bearing namespace.
+        """
+        if layer is None:
+            return
+        self._layers.append(layer)
+
+    def pop(self) -> Optional[Any]:
+        """Remove and return the most-recently-pushed layer, or ``None``
+        if the chain is empty.
+        """
+        if not self._layers:
+            return None
+        return self._layers.pop()
+
+    # -- Query -------------------------------------------------------------
+
+    def lookup(self, name: str) -> Optional[Callable]:
+        """Resolve *name* through the layer chain, then the
+        ``ggplot2_py.scales`` fallback module.
+
+        Returns the first hit, or ``None`` if nothing matches.
+
+        Notes
+        -----
+        The fallback layer is searched **last** even when the lookup
+        chain is non-empty — matching R's
+        ``c(env, list(as_namespace("ggplot2")))`` (R ref:
+        ``scale-type.R:44``).
+        """
+        for layer in reversed(self._layers):
+            val = _ns_get(layer, name)
+            if val is not None:
+                return val
+        # Fallback: the package's own scale-constructor module.  Import
+        # lazily to avoid an import cycle with scale.py at load time —
+        # the cycle only matters during module construction; at call
+        # time every module is loaded so the import never raises.
+        from ggplot2_py import scales as _scales_mod
+        return getattr(_scales_mod, name, None)
+
+    def __contains__(self, name: str) -> bool:
+        return self.lookup(name) is not None
+
+    # -- Plumbing ----------------------------------------------------------
+
+    def clone(self) -> "PlotEnv":
+        """Return a new :class:`PlotEnv` with the same layer chain.
+
+        The layers themselves are **not** deep-copied — mirrors R env
+        semantics where ``plot_clone`` does not snapshot the
+        environment contents.
+        """
+        new = PlotEnv()
+        new._layers = list(self._layers)
+        return new
+
+    @property
+    def layers(self) -> List[Any]:
+        """Read-only view of the layer chain (in push order)."""
+        return list(self._layers)
+
+    def __repr__(self) -> str:
+        return f"<PlotEnv layers={len(self._layers)}>"
+
+
+def _ns_get(layer: Any, name: str) -> Any:
+    """Resolve *name* on *layer*, trying mapping then attribute access.
+
+    Returns the found value, or ``None`` if absent.  Catches only the
+    natural "key absent" / "unsupported indexing" cases — anything else
+    propagates so real bugs surface (per the project rule against
+    over-broad fallback logic).
+    """
+    # Mapping path (dict and dict-like).  ``str``/``bytes`` are
+    # excluded because their ``__getitem__`` is positional and would
+    # raise ``TypeError`` for non-integer keys.
+    if hasattr(layer, "__getitem__") and not isinstance(layer, (str, bytes)):
+        try:
+            return layer[name]
+        except (KeyError, TypeError):
+            pass
+    # Attribute path (modules, SimpleNamespace, regular objects).
+    return getattr(layer, name, None)

ggplot2_python-4.0.2.9000.post3/ggplot2_py/guide_axis.py → ggplot2_python-4.0.2.9000.post5/ggplot2_py/_guide_axis.py

@@ -55,8 +55,8 @@ _PT: float = 72.27 / 25.4
 # Helpers
 # ---------------------------------------------------------------------------
 
-def _unit_to_cm(u: Unit) -> float:
-    """Convert a Unit (possibly compound/sum) to cm.
+def _unit_to_cm(u: Unit, axis: str = "height") -> float:
+    """Convert a Unit (possibly compound/sum) to cm along *axis*.
 
     ``convert_height/width`` can't handle compound ``"sum"`` units
     without a viewport context.  This helper decomposes them into
@@ -70,8 +70,17 @@ def _unit_to_cm(u: Unit) -> float:
 
     The ``data`` element is itself a multi-element Unit with the
     individual operands.
+
+    Parameters
+    ----------
+    u : Unit
+        Unit to convert.
+    axis : {"height", "width"}
+        Axis to measure along — needed for viewport-relative units
+        (``"npc"``) which resolve differently per axis in non-square
+        viewports.  Compound sums propagate the axis to children.
     """
-    from grid_py import convert_height
+    from grid_py import convert_height, convert_width
 
     units = getattr(u, "_units", None)
     values = getattr(u, "_values", None)
@@ -79,6 +88,8 @@ def _unit_to_cm(u: Unit) -> float:
     if units is None or values is None:
         return 0.0
 
+    fn = convert_width if axis == "width" else convert_height
+
     total_cm = 0.0
     n = len(u)
     for i in range(n):
@@ -88,7 +99,7 @@ def _unit_to_cm(u: Unit) -> float:
             # The operands are stored as a multi-element Unit in data[i]
             inner = data[i] if data and i < len(data) else None
             if inner is not None and isinstance(inner, Unit):
-                total_cm += _unit_to_cm(inner)
+                total_cm += _unit_to_cm(inner, axis)
             continue
 
         # Skip context-dependent units we can't resolve statically
@@ -99,7 +110,7 @@ def _unit_to_cm(u: Unit) -> float:
         val = float(values[i]) if i < len(values) else 0.0
         leaf = Unit(val, unit_type)
         try:
-            cm = convert_height(leaf, "cm", valueOnly=True)
+            cm = fn(leaf, "cm", valueOnly=True)
             total_cm += float(np.sum(cm))
         except Exception:
             pass
@@ -125,12 +136,12 @@ def _width_cm(x: Any) -> float:
     # For compound (sum) units, convert_width returns bogus results;
     # decompose and convert leaf-by-leaf instead.
     if _has_sum_unit(u):
-        return _unit_to_cm(u)
+        return _unit_to_cm(u, "width")
     try:
         result = convert_width(u, "cm", valueOnly=True)
         return float(np.sum(result))
     except Exception:
-        return _unit_to_cm(u)
+        return _unit_to_cm(u, "width")
 
 
 def _height_cm(x: Any) -> float:
@@ -143,12 +154,12 @@ def _height_cm(x: Any) -> float:
     else:
         return 0.0
     if _has_sum_unit(u):
-        return _unit_to_cm(u)
+        return _unit_to_cm(u, "height")
     try:
         result = convert_height(u, "cm", valueOnly=True)
         return float(np.sum(result))
     except Exception:
-        return _unit_to_cm(u)
+        return _unit_to_cm(u, "height")
 
 
 # ---------------------------------------------------------------------------

ggplot2_python-4.0.2.9000.post3/ggplot2_py/guide_colourbar.py → ggplot2_python-4.0.2.9000.post5/ggplot2_py/_guide_colourbar.py

@@ -681,7 +681,7 @@ def assemble_colourbar(
             gt = gtable_add_grob(gt, label_tree, t=1, l=1, clip="off", name="labels")
 
     # Add title
-    from ggplot2_py.guide_legend import add_legend_title
+    from ggplot2_py._guide_legend import add_legend_title
     gt = add_legend_title(gt, title_grob, position="top")
 
     # Add padding