ggplot2-python 4.0.2.9000.post4__py3-none-any.whl → 4.0.2.9000.post6__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.post4"
+__version__ = "4.0.2.9000.post6"
 __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,
@@ -118,6 +123,7 @@ from ggplot2_py.geom import (
     GeomRaster,
     GeomText,
     GeomLabel,
+    GeomAbsText,
     GeomBoxplot,
     GeomViolin,
     GeomDotplot,
@@ -168,6 +174,7 @@ from ggplot2_py.geom import (
     geom_raster,
     geom_text,
     geom_label,
+    geom_abs_text,
     geom_boxplot,
     geom_violin,
     geom_dotplot,
@@ -561,6 +568,7 @@ from ggplot2_py.guide import (
     is_guide,
     is_guides,
     new_guide,
+    register_guide,
     old_guide,
     guide_geom,
     guide_train,
@@ -734,7 +742,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 +754,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",
@@ -756,7 +767,7 @@ __all__ = [
     # Geom classes
     "Geom", "GeomPoint", "GeomPath", "GeomLine", "GeomStep",
     "GeomBar", "GeomCol", "GeomRect", "GeomTile", "GeomRaster",
-    "GeomText", "GeomLabel", "GeomBoxplot", "GeomViolin", "GeomDotplot",
+    "GeomText", "GeomLabel", "GeomAbsText", "GeomBoxplot", "GeomViolin", "GeomDotplot",
     "GeomRibbon", "GeomArea", "GeomSmooth", "GeomPolygon",
     "GeomErrorbar", "GeomErrorbarh", "GeomCrossbar", "GeomLinerange", "GeomPointrange",
     "GeomSegment", "GeomCurve", "GeomSpoke",
@@ -767,7 +778,7 @@ __all__ = [
     # Geom constructors
     "geom_point", "geom_path", "geom_line", "geom_step",
     "geom_bar", "geom_col", "geom_rect", "geom_tile", "geom_raster",
-    "geom_text", "geom_label", "geom_boxplot", "geom_violin", "geom_dotplot",
+    "geom_text", "geom_label", "geom_abs_text", "geom_boxplot", "geom_violin", "geom_dotplot",
     "geom_ribbon", "geom_area", "geom_smooth", "geom_polygon",
     "geom_errorbar", "geom_errorbarh", "geom_crossbar", "geom_linerange", "geom_pointrange",
     "geom_segment", "geom_curve", "geom_spoke",
@@ -897,7 +908,7 @@ __all__ = [
     # Guides
     "Guide", "GuideAxis", "GuideAxisLogticks", "GuideAxisStack",
     "GuideAxisTheta", "GuideBins", "GuideColourbar", "GuideColoursteps",
-    "GuideCustom", "GuideLegend", "GuideNone",
+    "GuideCustom", "GuideLegend", "GuideNone", "register_guide",
     "guide_axis", "guide_legend", "guide_colourbar", "guide_colorbar",
     "guide_old_colourbar", "guide_old_colorbar",
     "guide_coloursteps", "guide_colorsteps", "guide_bins",

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_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_py/{guide_axis.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")
 
 
 # ---------------------------------------------------------------------------
@@ -243,6 +254,15 @@ def draw_axis(
     minor_tick_length = tick_length * 0.5  # R: axis.minor.ticks.length = rel(0.75)
 
     # --- Build axis line (R: GuideAxis$build_decor, lines 313-322) -----
+    # R: the line is ``element_grob(elements$line, ...)``; when ``axis.line``
+    # is ``element_blank()`` (the default in theme_grey/theme_bw) this yields a
+    # zeroGrob — i.e. *no* line.  The previous fallback dict drew a spurious
+    # grey20 line regardless, which is invisible at a panel edge but crosses
+    # the interior for a rotated radial axis.  Honour the blank element.
+    from ggplot2_py.theme_elements import calc_element as _calc_el
+    _raw_line_el = _calc_el(f"axis.line.{aes}", theme)
+    _line_blank = _raw_line_el is None or _is_blank(_raw_line_el)
+
     if cap == "none" or len(breaks) == 0:
         line_start, line_end = 0.0, 1.0
     else:
@@ -250,7 +270,9 @@ def draw_axis(
         line_end = max(breaks) if cap in ("both", "upper") else 1.0
 
     line_lwd = float(line_el.get("linewidth", 0.5)) * _PT
-    if is_horizontal:
+    if _line_blank:
+        axis_line = null_grob(name="axis.line")
+    elif is_horizontal:
         axis_line = segments_grob(
             x0=[line_start], y0=[orth_side],
             x1=[line_end], y1=[orth_side],

ggplot2_py/{guide_colourbar.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

ggplot2_py/{guide_legend.py → _guide_legend.py}

@@ -25,6 +25,8 @@ from grid_py import (
     Gpar,
     Unit,
     Viewport,
+    convert_height,
+    convert_width,
     null_grob,
     rect_grob,
     text_grob,
@@ -930,8 +932,8 @@ def package_legend_box(
         max_width_cm = 0.0
         heights_cm: List[float] = []
         for lg in legends:
-            max_width_cm = max(max_width_cm, _gtable_total_cm(lg.widths))
-            heights_cm.append(_gtable_total_cm(lg.heights))
+            max_width_cm = max(max_width_cm, _gtable_total_cm(lg.widths, "width"))
+            heights_cm.append(_gtable_total_cm(lg.heights, "height"))
         guides = gtable_col(
             name="guides",
             grobs=legends,
@@ -944,8 +946,8 @@ def package_legend_box(
         max_height_cm = 0.0
         widths_cm: List[float] = []
         for lg in legends:
-            max_height_cm = max(max_height_cm, _gtable_total_cm(lg.heights))
-            widths_cm.append(_gtable_total_cm(lg.widths))
+            max_height_cm = max(max_height_cm, _gtable_total_cm(lg.heights, "height"))
+            widths_cm.append(_gtable_total_cm(lg.widths, "width"))
         guides = gtable_row(
             name="guides",
             grobs=legends,
@@ -1040,30 +1042,23 @@ def _interleave(
     return result
 
 
-def _gtable_total_cm(unit: Optional[Unit]) -> float:
-    """Sum a Unit vector, returning cm as a float.
+def _gtable_total_cm(unit: Optional[Unit], axis: str = "height") -> float:
+    """Sum a Unit vector along *axis* (``"height"`` or ``"width"``),
+    returning cm as a float.
 
-    Falls back to simple sum of values for "cm" units; returns a
-    reasonable estimate for mixed/null units.
+    Delegates to :func:`grid_py.convert_height` / :func:`grid_py.convert_width`
+    so font-relative units (``"lines"``, ``"char"``, ``"strwidth"``,
+    ``"strheight"``) resolve against the active gp / device — matching R's
+    ``sum(convertHeight(unit, "cm", valueOnly=TRUE))`` / ``convertWidth``.
+
+    Axis matters for viewport-relative units (``"npc"``): for a
+    non-square viewport, ``convert_height`` and ``convert_width`` resolve
+    ``unit(0.5, "npc")`` to different cm values. Callers must pass the
+    axis the unit is being measured along — typically ``"width"`` for
+    gtable widths, ``"height"`` for gtable heights.
     """
     if unit is None or len(unit) == 0:
         return 0.0
-    total = 0.0
-    for i in range(len(unit)):
-        part = unit[i: i + 1]
-        vals = part.values if hasattr(part, "values") else [0.0]
-        units = part.units if hasattr(part, "units") else ["cm"]
-        v = vals[0] if vals else 0.0
-        u = units[0] if units else "cm"
-        if u == "cm":
-            total += v
-        elif u == "mm":
-            total += v / 10.0
-        elif u == "inches":
-            total += v * 2.54
-        elif u == "pt" or u == "points":
-            total += v / 72.27 * 2.54
-        else:
-            # null, npc, etc. — use the numeric value as a rough estimate
-            total += v
-    return total
+    fn = convert_width if axis == "width" else convert_height
+    cm = fn(unit, "cm", valueOnly=True)
+    return float(np.sum(np.asarray(cm)))