ggplot2-python 4.0.2.9000.post2__tar.gz → 4.0.2.9000.post4__tar.gz

{ggplot2_python-4.0.2.9000.post2 → ggplot2_python-4.0.2.9000.post4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ggplot2-python
-Version: 4.0.2.9000.post2
+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.post2 → ggplot2_python-4.0.2.9000.post4}/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 |
 |----------------|-----------|-----------|

{ggplot2_python-4.0.2.9000.post2 → ggplot2_python-4.0.2.9000.post4}/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_python-4.0.2.9000.post2 → ggplot2_python-4.0.2.9000.post4}/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.