ggplot2-python 4.0.2.9000.post2__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.post1"
+__version__ = "4.0.2.9000.post4"
 __r_commit__ = "c02c05a"
 
 # ---------------------------------------------------------------------------
@@ -153,6 +153,10 @@ from ggplot2_py.geom import (
     GeomQuantile,
     GeomJitter,
     GeomSf,
+    GeomCustomAnn,
+    GeomLogticks,
+    GeomRasterAnn,
+    translate_shape_string,
     geom_point,
     geom_path,
     geom_line,
@@ -420,12 +424,14 @@ from ggplot2_py.scales import (
     scale_size_datetime,
     scale_radius,
     scale_shape,
+    scale_shape_continuous,
     scale_shape_discrete,
     scale_shape_binned,
     scale_shape_identity,
     scale_shape_manual,
     scale_shape_ordinal,
     scale_linetype,
+    scale_linetype_continuous,
     scale_linetype_discrete,
     scale_linetype_binned,
     scale_linetype_identity,
@@ -492,7 +498,11 @@ from ggplot2_py.facet import (
     facet_grid,
     facet_wrap,
     is_facet,
+    wrap_dims,
+    max_height,
+    max_width,
 )
+from ggplot2_py.layout import Layout
 
 # ---------------------------------------------------------------------------
 # Position adjustments
@@ -549,6 +559,14 @@ from ggplot2_py.guide import (
     guide_none,
     guides,
     is_guide,
+    is_guides,
+    new_guide,
+    old_guide,
+    guide_geom,
+    guide_train,
+    guide_merge,
+    guide_transform,
+    guide_gengrob,
 )
 
 # ---------------------------------------------------------------------------
@@ -567,6 +585,7 @@ from ggplot2_py.theme import (
     reset_theme_settings,
     update_theme,
     replace_theme,
+    from_theme,
 )
 from ggplot2_py.theme_elements import (
     Element,
@@ -582,6 +601,7 @@ from ggplot2_py.theme_elements import (
     el_def,
     merge_element,
     is_theme_element,
+    is_margin,
     Margin,
     margin,
     margin_auto,
@@ -603,6 +623,17 @@ from ggplot2_py.theme_defaults import (
     theme_classic,
     theme_void,
     theme_test,
+    theme_sub_axis,
+    theme_sub_axis_x,
+    theme_sub_axis_y,
+    theme_sub_axis_top,
+    theme_sub_axis_bottom,
+    theme_sub_axis_left,
+    theme_sub_axis_right,
+    theme_sub_legend,
+    theme_sub_panel,
+    theme_sub_plot,
+    theme_sub_strip,
 )
 
 # ---------------------------------------------------------------------------
@@ -668,7 +699,19 @@ from ggplot2_py.autoplot import autoplot, autolayer
 # ---------------------------------------------------------------------------
 # Utility re-exports (matching R namespace)
 # ---------------------------------------------------------------------------
-from ggplot2_py._utils import resolution, remove_missing
+from ggplot2_py._utils import (
+    resolution, remove_missing,
+    cut_interval, cut_number, cut_width,
+    transform_position, fill_alpha, pattern_alpha,
+)
+from ggplot2_py._defaults import (
+    update_geom_defaults, update_stat_defaults,
+    reset_geom_defaults, reset_stat_defaults,
+    get_geom_defaults,
+)
+from ggplot2_py._make_constructor import make_constructor
+# zeroGrob alias for R parity (ggplot2 imports it from grid)
+from grid_py import null_grob as zeroGrob
 
 # grid re-exports (matching R: importFrom(grid, unit, arrow))
 from grid_py import Unit as unit, arrow
@@ -739,6 +782,9 @@ __all__ = [
     "geom_sf", "geom_sf_label", "geom_sf_text",
     "geom_qq", "geom_qq_line",
     "is_geom",
+    "GeomMap", "GeomQuantile",
+    "GeomCustomAnn", "GeomLogticks", "GeomRasterAnn",
+    "translate_shape_string",
     # Stat classes
     "Stat", "StatIdentity", "StatBin", "StatCount", "StatDensity",
     "StatSmooth", "StatBoxplot", "StatSummary", "StatSummaryBin",
@@ -796,21 +842,51 @@ __all__ = [
     "scale_color_viridis_c", "scale_color_viridis_d",
     "scale_color_grey", "scale_color_identity", "scale_color_manual",
     "scale_alpha", "scale_alpha_continuous", "scale_alpha_discrete",
+    "scale_alpha_binned", "scale_alpha_identity", "scale_alpha_manual",
+    "scale_alpha_ordinal", "scale_alpha_date", "scale_alpha_datetime",
     "scale_size", "scale_size_continuous", "scale_size_area",
-    "scale_shape", "scale_shape_discrete",
-    "scale_linetype", "scale_linetype_discrete",
-    "scale_linewidth", "scale_linewidth_continuous",
+    "scale_size_binned", "scale_size_binned_area",
+    "scale_size_discrete", "scale_size_identity", "scale_size_manual",
+    "scale_size_ordinal", "scale_size_date", "scale_size_datetime",
+    "scale_radius",
+    "scale_shape", "scale_shape_continuous", "scale_shape_discrete",
+    "scale_shape_binned", "scale_shape_identity", "scale_shape_manual",
+    "scale_shape_ordinal",
+    "scale_linetype", "scale_linetype_continuous", "scale_linetype_discrete",
+    "scale_linetype_binned", "scale_linetype_identity", "scale_linetype_manual",
+    "scale_linewidth", "scale_linewidth_continuous", "scale_linewidth_discrete",
+    "scale_linewidth_binned", "scale_linewidth_identity", "scale_linewidth_manual",
+    "scale_linewidth_ordinal",
+    "scale_linewidth_date", "scale_linewidth_datetime",
     "scale_stroke", "scale_stroke_continuous",
+    # Binned / stepped / fermenter / distiller / ordinal / date colour & fill scales
+    "scale_colour_binned", "scale_colour_distiller", "scale_colour_fermenter",
+    "scale_colour_ordinal", "scale_colour_steps", "scale_colour_steps2",
+    "scale_colour_stepsn", "scale_colour_viridis_b",
+    "scale_colour_date", "scale_colour_datetime",
+    "scale_color_binned", "scale_color_distiller", "scale_color_fermenter",
+    "scale_color_ordinal", "scale_color_steps", "scale_color_steps2",
+    "scale_color_stepsn", "scale_color_viridis_b",
+    "scale_color_date", "scale_color_datetime",
+    "scale_fill_binned", "scale_fill_distiller", "scale_fill_fermenter",
+    "scale_fill_ordinal", "scale_fill_steps", "scale_fill_steps2",
+    "scale_fill_stepsn", "scale_fill_viridis_b",
+    "scale_fill_date", "scale_fill_datetime",
+    # Time / identity / manual variants
+    "scale_x_time", "scale_y_time",
+    "scale_continuous_identity", "scale_discrete_identity", "scale_discrete_manual",
     # Coords
     "Coord", "CoordCartesian", "CoordFixed", "CoordFlip",
     "CoordPolar", "CoordQuickmap", "CoordRadial", "CoordTrans", "CoordTransform",
     "coord_cartesian", "coord_equal", "coord_fixed", "coord_flip",
     "coord_polar", "coord_quickmap", "coord_radial", "coord_sf", "coord_trans", "coord_transform",
     "CoordSf",
-    "coord_munch", "is_coord",
+    "coord_munch", "is_coord", "sf_transform_xy",
     # Facets
     "Facet", "FacetNull", "FacetGrid", "FacetWrap",
-    "facet_null", "facet_grid", "facet_wrap", "is_facet",
+    "facet_null", "facet_grid", "facet_wrap", "is_facet", "wrap_dims",
+    "max_height", "max_width",
+    "Layout",
     # Positions
     "Position", "PositionIdentity", "PositionDodge", "PositionDodge2",
     "PositionJitter", "PositionJitterdodge", "PositionNudge",
@@ -826,20 +902,31 @@ __all__ = [
     "guide_old_colourbar", "guide_old_colorbar",
     "guide_coloursteps", "guide_colorsteps", "guide_bins",
     "guide_custom", "guide_none", "guides", "is_guide",
+    "guide_axis_logticks", "guide_axis_stack", "guide_axis_theta",
+    "is_guides", "new_guide", "old_guide",
+    "guide_geom", "guide_train", "guide_merge", "guide_transform",
+    "guide_gengrob",
     # Themes
     "theme", "is_theme", "complete_theme",
     "theme_get", "theme_set", "theme_update", "theme_replace",
     "set_theme", "get_theme", "reset_theme_settings",
+    "update_theme", "replace_theme", "from_theme",
     "Element", "element_blank", "element_line", "element_rect",
     "element_text", "element_point", "element_polygon", "element_geom",
     "element_grob", "element_render", "merge_element",
-    "Margin", "margin", "Rel", "rel",
+    "el_def", "is_theme_element", "is_margin",
+    "Margin", "margin", "margin_auto", "margin_part", "Rel", "rel",
     "calc_element", "get_element_tree", "register_theme_elements",
     "theme_grey", "theme_gray", "theme_bw", "theme_linedraw",
     "theme_light", "theme_dark", "theme_minimal", "theme_classic",
     "theme_void", "theme_test",
+    "theme_sub_axis", "theme_sub_axis_x", "theme_sub_axis_y",
+    "theme_sub_axis_top", "theme_sub_axis_bottom",
+    "theme_sub_axis_left", "theme_sub_axis_right",
+    "theme_sub_legend", "theme_sub_panel", "theme_sub_plot",
+    "theme_sub_strip",
     # Labels, limits
-    "labs", "xlab", "ylab", "ggtitle",
+    "labs", "xlab", "ylab", "ggtitle", "update_labels",
     "lims", "xlim", "ylim", "expand_limits",
     # Annotations
     "annotate", "annotation_custom", "annotation_raster", "annotation_logticks",
@@ -861,10 +948,25 @@ __all__ = [
     "autoplot", "autolayer",
     # Utilities
     "resolution", "remove_missing",
+    "cut_interval", "cut_number", "cut_width",
+    "transform_position", "fill_alpha", "pattern_alpha",
+    "update_geom_defaults", "update_stat_defaults",
+    "reset_geom_defaults", "reset_stat_defaults",
+    "get_geom_defaults",
+    "make_constructor",
     "unit", "arrow", "alpha",
-    "PT", "STROKE",
+    "PT", "STROKE", "zeroGrob",
+    # Submodule namespaces and remaining R-exported helpers already
+    # defined at top level (just need to surface for ``import *``).
+    "stat", "labeller",
+    "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/_compat.py

@@ -32,6 +32,8 @@ __all__ = [
     "Waiver",
     "is_waiver",
     "waiver",
+    "NA",
+    "is_na",
     "caller_arg",
 ]
 
@@ -103,22 +105,24 @@ def cli_inform(
     call: Optional[str] = None,
     **kwargs: Any,
 ) -> None:
-    """Emit an informational message (no-op by default).
+    """Emit an informational message via Python's :mod:`warnings`.
 
-    In interactive sessions this could print; in batch mode it stays silent.
-    Override by monkey-patching if verbose output is desired.
+    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.
 
     Parameters
     ----------
     message : str
         Informational message.
     call : str, optional
-        Name of the calling function.
+        Name of the calling function (unused; matches R signature).
     **kwargs : Any
         Substitution values for placeholders in *message*.
     """
-    # Intentionally silent – mirrors rlang::inform() in non-interactive R.
-    pass
+    warnings.warn(message, UserWarning, stacklevel=2)
 
 
 # ---------------------------------------------------------------------------
@@ -436,6 +440,49 @@ def waiver() -> Waiver:
     return Waiver()
 
 
+# ---------------------------------------------------------------------------
+# NA sentinel (R parity)
+# ---------------------------------------------------------------------------
+#
+# R distinguishes ``NULL`` (unspecified, inherits from parent) from ``NA``
+# (explicitly absent, must NOT inherit). Python collapses both onto
+# ``None`` by default, which silently breaks theme inheritance — e.g.
+# ``element_rect(fill="grey92", colour=NA)`` should keep the missing
+# border on merge, but Python would replace ``None`` with the parent
+# ``rect`` element's ``"black"``. This sentinel preserves R's NA
+# semantics through ``combine_elements``.
+
+class _NA:
+    """Sentinel for R's ``NA`` — explicitly absent, never inherited."""
+
+    _instance: Optional["_NA"] = None
+
+    def __new__(cls) -> "_NA":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "NA"
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, _NA)
+
+    def __hash__(self) -> int:
+        return 0
+
+
+NA = _NA()
+
+
+def is_na(x: Any) -> bool:
+    """Return True iff *x* is the singleton :data:`NA` sentinel."""
+    return isinstance(x, _NA)
+
+
 def is_waiver(x: Any) -> bool:
     """Check whether *x* is a ``Waiver`` sentinel.
 

ggplot2_py/_defaults.py

@@ -0,0 +1,169 @@
+"""Geom / stat default-aesthetic modifiers — port of R's
+``geom-update-defaults.R``.
+
+Lets users override ``Geom*.default_aes`` (and the analogous Stat
+defaults) globally for the lifetime of a Python session, with a cache
+that lets the user roll back via ``reset_geom_defaults`` /
+``reset_stat_defaults``.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ggplot2_py.aes import rename_aes
+from ggplot2_py.geom import Geom
+from ggplot2_py.stat import Stat
+
+__all__ = [
+    "update_geom_defaults",
+    "update_stat_defaults",
+    "reset_geom_defaults",
+    "reset_stat_defaults",
+    "get_geom_defaults",
+]
+
+
+# Cached pristine copies — populated lazily on first override so reset
+# can restore the originals. R's equivalent: ``cache_defaults``.
+_cache_geom: Dict[str, Any] = {}
+_cache_stat: Dict[str, Any] = {}
+
+
+def _resolve(name_or_cls: Any, registry: Dict[str, Any], kind: str) -> Any:
+    """Resolve a name or class to the registered Geom/Stat class.
+
+    Mirrors R ``validate_subclass``: accepts a string (snake-case
+    suffix), a Geom/Stat subclass, or a layer-constructor function.
+    """
+    if isinstance(name_or_cls, str):
+        cls = registry.get(name_or_cls) or registry.get(name_or_cls.lower())
+        if cls is None:
+            raise ValueError(f"No registered {kind} named {name_or_cls!r}.")
+        return cls
+    if isinstance(name_or_cls, type):
+        return name_or_cls
+    # A bound layer constructor returns a Layer; in R the function is
+    # passed to validate_subclass which sniffs the geom/stat off it.
+    raise TypeError(
+        f"Expected a string name or {kind} class; got {type(name_or_cls).__name__}."
+    )
+
+
+def _snake_key(cls: Any, prefix: str) -> str:
+    """``GeomPoint -> "point"``, used as the cache key."""
+    name = cls.__name__
+    if name.startswith(prefix):
+        name = name[len(prefix):]
+    # CamelCase → snake_case
+    out = []
+    for i, c in enumerate(name):
+        if c.isupper() and i > 0:
+            out.append("_")
+        out.append(c.lower())
+    return "".join(out) or name
+
+
+def _update(cls: Any, new: Any, cache: Dict[str, Any]) -> Any:
+    """Common update path for both geom and stat defaults."""
+    key = _snake_key(cls, "Geom" if cache is _cache_geom else "Stat")
+    old = dict(cls.default_aes) if hasattr(cls.default_aes, "items") else dict(cls.default_aes or {})
+
+    if new is None:
+        # Reset path — restore from cache, drop entry.
+        cached = cache.pop(key, None)
+        if cached is not None:
+            cls.default_aes = type(cls.default_aes)(**cached) if hasattr(type(cls.default_aes), "__init__") else dict(cached)
+        return old
+
+    # First override: snapshot the pristine defaults so we can roll back.
+    if key not in cache:
+        cache[key] = old
+
+    new_dict = rename_aes_dict(new)
+    merged = {**old}
+    for k, v in new_dict.items():
+        merged[k] = v
+    # Replace in the same container type the class originally used.
+    cls.default_aes = type(cls.default_aes)(**merged) if hasattr(type(cls.default_aes), "__init__") else merged
+    return old
+
+
+def rename_aes_dict(new: Any) -> Dict[str, Any]:
+    """Apply :func:`rename_aes` to a Mapping or plain dict."""
+    if hasattr(new, "items"):
+        items = list(new.items())
+    else:
+        items = list(new)
+    keys = [k for k, _ in items]
+    canonical = rename_aes({k: None for k in keys})
+    name_map = {k: c for k, c in zip(keys, list(canonical.keys()))}
+    return {name_map[k]: v for k, v in items}
+
+
+def update_geom_defaults(geom: Any, new: Any) -> Any:
+    """Modify a Geom's ``default_aes``.  Pass ``None`` to roll back.
+
+    Mirrors R ``update_geom_defaults`` (geom-update-defaults.R:57-59).
+    """
+    cls = _resolve(geom, Geom._registry, "geom")
+    return _update(cls, new, _cache_geom)
+
+
+def update_stat_defaults(stat: Any, new: Any) -> Any:
+    """Modify a Stat's ``default_aes``.  Pass ``None`` to roll back.
+
+    Mirrors R ``update_stat_defaults`` (geom-update-defaults.R:63-65).
+    """
+    cls = _resolve(stat, Stat._registry, "stat")
+    return _update(cls, new, _cache_stat)
+
+
+def reset_geom_defaults() -> None:
+    """Roll back every prior ``update_geom_defaults`` call.
+
+    Mirrors R ``reset_geom_defaults`` (geom-update-defaults.R:120).
+    """
+    for key in list(_cache_geom.keys()):
+        cls = Geom._registry.get(key) or Geom._registry.get(key.lower())
+        if cls is not None:
+            _update(cls, None, _cache_geom)
+
+
+def reset_stat_defaults() -> None:
+    """Roll back every prior ``update_stat_defaults`` call.
+
+    Mirrors R ``reset_stat_defaults`` (geom-update-defaults.R:124).
+    """
+    for key in list(_cache_stat.keys()):
+        cls = Stat._registry.get(key) or Stat._registry.get(key.lower())
+        if cls is not None:
+            _update(cls, None, _cache_stat)
+
+
+def get_geom_defaults(geom: Any, theme: Optional[Any] = None) -> Dict[str, Any]:
+    """Return the resolved default aesthetics for *geom*.
+
+    Mirrors R ``get_geom_defaults`` (geom-update-defaults.R:96-116).
+    Accepts a class, a registered name, or a layer-constructor
+    function.  ``theme`` is honoured for ``FromTheme`` defaults.
+    """
+    if callable(geom) and not isinstance(geom, type):
+        # Layer constructor (geom_point) — call to obtain the Layer
+        layer = geom()
+        cls = type(getattr(layer, "geom", None) or geom)
+        if hasattr(layer, "aes_params"):
+            base = dict(cls.default_aes) if hasattr(cls.default_aes, "items") else dict(cls.default_aes or {})
+            base.update(layer.aes_params or {})
+            return base
+    if isinstance(geom, str):
+        cls = _resolve(geom, Geom._registry, "geom")
+    elif isinstance(geom, type):
+        cls = geom
+    else:
+        cls = type(geom)
+
+    base = dict(cls.default_aes) if hasattr(cls.default_aes, "items") else dict(cls.default_aes or {})
+    if theme is not None:
+        from ggplot2_py.geom import _eval_from_theme
+        base = dict(_eval_from_theme(cls.default_aes, theme))
+    return base