rgrid-python 4.5.3__py3-none-any.whl

grid_py/__init__.py

@@ -0,0 +1,340 @@
+"""
+grid_py — Python port of the R grid graphics package.
+
+Provides a complete reimplementation of R's grid graphics system including
+units, viewports, grobs (graphical objects), layouts, and rendering via
+Cairo (pycairo).
+"""
+
+__version__ = "4.5.3"
+
+# --- Utilities ---
+from grid_py._utils import depth, explode, grid_pretty, n2mfrow
+
+# --- Justification ---
+from grid_py._just import valid_just, resolve_hjust, resolve_vjust, resolve_raster_size
+
+# --- Units ---
+from grid_py._units import (
+    Unit, is_unit, unit_type, unit_c, unit_length,
+    unit_pmax, unit_pmin, unit_psum, unit_rep,
+    string_width, string_height, string_ascent, string_descent,
+    absolute_size,
+    convert_unit, convert_x, convert_y, convert_width, convert_height,
+)
+
+# --- Graphical Parameters ---
+from grid_py._gpar import Gpar, get_gpar
+
+# --- Arrow ---
+from grid_py._arrow import Arrow, arrow
+
+# --- Paths ---
+from grid_py._path import GPath, VpPath, GridPath, as_path, is_closed, PATH_SEP
+
+# --- Layout ---
+from grid_py._layout import (
+    GridLayout, layout_region,
+)
+
+# --- Patterns, Masks, Clip Paths ---
+from grid_py._patterns import (
+    LinearGradient, RadialGradient, Pattern,
+    linear_gradient, radial_gradient, pattern,
+)
+from grid_py._mask import GridMask, as_mask, is_mask
+from grid_py._clippath import GridClipPath, as_clip_path, is_clip_path
+
+# --- Viewport ---
+from grid_py._viewport import (
+    Viewport, VpList, VpStack, VpTree,
+    push_viewport, pop_viewport, down_viewport, up_viewport, seek_viewport,
+    current_viewport, current_vp_path, current_vp_tree,
+    current_transform, current_rotation, current_parent,
+    data_viewport, plot_viewport, edit_viewport, show_viewport,
+)
+
+# --- State ---
+from grid_py._state import GridState, get_state
+
+# --- Display List ---
+from grid_py._display_list import DisplayList
+
+# --- Transforms ---
+from grid_py._transforms import (
+    group_translate, group_rotate, group_scale, group_shear, group_flip,
+    defn_translate, defn_rotate, defn_scale,
+    use_translate, use_rotate, use_scale,
+    viewport_translate, viewport_rotate, viewport_scale, viewport_transform,
+)
+
+# --- Grob ---
+from grid_py._grob import (
+    Grob, GTree, GList, GEdit, GEditList,
+    grob_tree, grob_name, is_grob,
+    get_grob, set_grob, add_grob, remove_grob, edit_grob,
+    force_grob, set_children, reorder_grob,
+    apply_edit, apply_edits,
+)
+
+# --- Primitives ---
+from grid_py._primitives import (
+    move_to_grob, grid_move_to,
+    line_to_grob, grid_line_to,
+    lines_grob, grid_lines,
+    polyline_grob, grid_polyline,
+    segments_grob, grid_segments,
+    arrows_grob, grid_arrows,
+    points_grob, grid_points,
+    rect_grob, grid_rect,
+    roundrect_grob, grid_roundrect,
+    circle_grob, grid_circle,
+    polygon_grob, grid_polygon,
+    path_grob, grid_path,
+    text_grob, grid_text,
+    raster_grob, grid_raster,
+    clip_grob, grid_clip,
+    null_grob, grid_null,
+    function_grob, grid_function,
+    as_path,
+    stroke_grob, grid_stroke,
+    fill_grob, grid_fill,
+    fill_stroke_grob, grid_fill_stroke,
+)
+
+# --- Coordinates ---
+from grid_py._coords import (
+    GridCoords, GridGrobCoords, GridGTreeCoords,
+    grob_coords, grob_points,
+    grid_coords, grid_grob_coords, grid_gtree_coords,
+    empty_coords, empty_grob_coords, empty_gtree_coords,
+    is_empty_coords,
+)
+
+# --- Curves ---
+from grid_py._curve import (
+    curve_grob, grid_curve,
+    xspline_grob, grid_xspline,
+    bezier_grob, grid_bezier,
+    xspline_points, bezier_points,
+    arc_curvature,
+)
+
+# --- Groups ---
+from grid_py._group import (
+    GroupGrob, DefineGrob, UseGrob,
+    group_grob, grid_group,
+    define_grob, grid_define,
+    use_grob, grid_use,
+)
+
+# --- Renderer ---
+from grid_py._renderer_base import GridRenderer
+from grid_py.renderer import CairoRenderer
+from grid_py.renderer_web import WebRenderer
+
+# --- Drawing ---
+from grid_py._draw import (
+    grid_draw, grid_newpage, grid_refresh,
+    grid_record, record_grob,
+    grid_delay, delay_grob,
+    grid_dl_apply, grid_locator,
+)
+
+# --- Edit (display list) ---
+from grid_py._edit import (
+    grid_edit, grid_get, grid_set, grid_add, grid_remove,
+    grid_gedit, grid_gget, grid_gremove,
+)
+
+# --- Listing & Search ---
+from grid_py._ls import (
+    grid_ls, grid_grep,
+    nested_listing, path_listing, grob_path_listing,
+    show_grob, get_names, child_names,
+)
+
+# --- Grab ---
+from grid_py._grab import (
+    grid_grab, grid_grab_expr,
+    grid_force, grid_revert,
+    grid_cap, grid_reorder,
+)
+
+# --- High-level ---
+from grid_py._highlevel import (
+    grid_grill, grid_show_layout, grid_show_viewport,
+    grid_abline, grid_plot_and_legend, layout_torture,
+    frame_grob, grid_frame, pack_grob, grid_pack, place_grob, grid_place,
+    xaxis_grob, grid_xaxis, yaxis_grob, grid_yaxis,
+    legend_grob, grid_legend,
+    grid_multipanel, grid_panel, grid_strip,
+    grid_top_level_vp,
+)
+
+# --- Size / Metrics ---
+from grid_py._size import (
+    calc_string_metric,
+    width_details, height_details, ascent_details, descent_details,
+    grob_width, grob_height, grob_x, grob_y,
+    grob_ascent, grob_descent,
+)
+
+# --- Typeset ---
+from grid_py._typeset import glyph_grob, grid_glyph
+
+# --- Deprecated aliases (R compatibility) ---
+convert_native = convert_unit
+grid_convert = convert_unit
+grid_convert_x = convert_x
+grid_convert_y = convert_y
+grid_convert_width = convert_width
+grid_convert_height = convert_height
+from grid_py._units import device_loc, device_dim
+
+# R names grid.collection and grid.copy were undocumented stubs
+grid_collection = grid_draw
+grid_copy = grid_draw
+
+# grid.display.list / engine.display.list
+def grid_display_list(on: bool = True) -> bool:
+    """Enable or disable the display list.
+
+    Parameters
+    ----------
+    on : bool
+        Whether to enable recording.
+
+    Returns
+    -------
+    bool
+        Previous state.
+    """
+    state = get_state()
+    prev = state._dl_on
+    state._dl_on = on
+    return prev
+
+engine_display_list = grid_display_list
+
+
+__all__ = [
+    # Utils
+    "depth", "explode", "grid_pretty", "n2mfrow",
+    # Just
+    "valid_just", "resolve_hjust", "resolve_vjust", "resolve_raster_size",
+    # Units
+    "Unit", "is_unit", "unit_type", "unit_c", "unit_length",
+    "unit_pmax", "unit_pmin", "unit_psum", "unit_rep",
+    "string_width", "string_height", "string_ascent", "string_descent",
+    "absolute_size",
+    "convert_unit", "convert_x", "convert_y", "convert_width", "convert_height",
+    # Gpar
+    "Gpar", "get_gpar",
+    # Arrow
+    "Arrow", "arrow",
+    # Path
+    "GPath", "VpPath", "GridPath", "as_path", "is_closed", "PATH_SEP",
+    # Layout
+    "GridLayout", "layout_region",
+    # Patterns
+    "LinearGradient", "RadialGradient", "Pattern",
+    "linear_gradient", "radial_gradient", "pattern",
+    # Mask
+    "GridMask", "as_mask", "is_mask",
+    # Clip path
+    "GridClipPath", "as_clip_path", "is_clip_path",
+    # Viewport
+    "Viewport", "VpList", "VpStack", "VpTree",
+    "push_viewport", "pop_viewport", "down_viewport", "up_viewport", "seek_viewport",
+    "current_viewport", "current_vp_path", "current_vp_tree",
+    "current_transform", "current_rotation", "current_parent",
+    "data_viewport", "plot_viewport", "edit_viewport", "show_viewport",
+    # State
+    "GridState", "get_state",
+    # Display list
+    "DisplayList",
+    # Transforms
+    "group_translate", "group_rotate", "group_scale", "group_shear", "group_flip",
+    "defn_translate", "defn_rotate", "defn_scale",
+    "use_translate", "use_rotate", "use_scale",
+    "viewport_translate", "viewport_rotate", "viewport_scale", "viewport_transform",
+    # Grob
+    "Grob", "GTree", "GList", "GEdit", "GEditList",
+    "grob_tree", "grob_name", "is_grob",
+    "get_grob", "set_grob", "add_grob", "remove_grob", "edit_grob",
+    "force_grob", "set_children", "reorder_grob",
+    "apply_edit", "apply_edits",
+    # Primitives
+    "move_to_grob", "grid_move_to",
+    "line_to_grob", "grid_line_to",
+    "lines_grob", "grid_lines",
+    "polyline_grob", "grid_polyline",
+    "segments_grob", "grid_segments",
+    "arrows_grob", "grid_arrows",
+    "points_grob", "grid_points",
+    "rect_grob", "grid_rect",
+    "roundrect_grob", "grid_roundrect",
+    "circle_grob", "grid_circle",
+    "polygon_grob", "grid_polygon",
+    "path_grob", "grid_path",
+    "text_grob", "grid_text",
+    "raster_grob", "grid_raster",
+    "clip_grob", "grid_clip",
+    "null_grob", "grid_null",
+    "function_grob", "grid_function",
+    # Coords
+    "GridCoords", "GridGrobCoords", "GridGTreeCoords",
+    "grob_coords", "grob_points",
+    "grid_coords", "grid_grob_coords", "grid_gtree_coords",
+    "empty_coords", "empty_grob_coords", "empty_gtree_coords",
+    "is_empty_coords",
+    # Curves
+    "curve_grob", "grid_curve",
+    "xspline_grob", "grid_xspline",
+    "bezier_grob", "grid_bezier",
+    "xspline_points", "bezier_points",
+    "arc_curvature",
+    # Groups
+    "GroupGrob", "DefineGrob", "UseGrob",
+    "group_grob", "grid_group",
+    "define_grob", "grid_define",
+    "use_grob", "grid_use",
+    # Draw
+    "grid_draw", "grid_newpage", "grid_refresh",
+    "grid_record", "record_grob",
+    "grid_delay", "delay_grob",
+    "grid_dl_apply", "grid_locator",
+    # Edit
+    "grid_edit", "grid_get", "grid_set", "grid_add", "grid_remove",
+    "grid_gedit", "grid_gget", "grid_gremove",
+    # LS
+    "grid_ls", "grid_grep",
+    "nested_listing", "path_listing", "grob_path_listing",
+    "show_grob", "get_names", "child_names",
+    # Grab
+    "grid_grab", "grid_grab_expr",
+    "grid_force", "grid_revert",
+    "grid_cap", "grid_reorder",
+    # High-level
+    "grid_grill", "grid_show_layout", "grid_show_viewport",
+    "grid_abline", "grid_plot_and_legend", "layout_torture",
+    "frame_grob", "grid_frame", "pack_grob", "grid_pack", "place_grob", "grid_place",
+    "xaxis_grob", "grid_xaxis", "yaxis_grob", "grid_yaxis",
+    "legend_grob", "grid_legend",
+    "grid_multipanel", "grid_panel", "grid_strip",
+    "grid_top_level_vp",
+    # Size
+    "calc_string_metric",
+    "grob_width", "grob_height", "grob_x", "grob_y",
+    "grob_ascent", "grob_descent",
+    # Typeset
+    "glyph_grob", "grid_glyph",
+    # Deprecated
+    "convert_native", "grid_convert",
+    "grid_convert_x", "grid_convert_y",
+    "grid_convert_width", "grid_convert_height",
+    "device_loc", "device_dim",
+    "grid_collection", "grid_copy",
+    "grid_display_list", "engine_display_list",
+]

grid_py/_arrow.py

@@ -0,0 +1,331 @@
+"""
+Arrow head specification for grid_py -- Python port of R's ``grid::arrow()``.
+
+This module provides the :class:`Arrow` class and the :func:`arrow` factory
+function, which describe the arrow heads that can be attached to line-based
+grobs (segments, lines, curves, etc.).
+
+The implementation mirrors the behaviour of R's ``arrow()`` constructor,
+``length.arrow``, ``rep.arrow``, and ``[.arrow`` method defined in
+``src/library/grid/R/primitives.R``.
+
+Examples
+--------
+>>> from grid_py._arrow import arrow
+>>> a = arrow()
+>>> a
+Arrow(angle=[30.0], length=Unit([0.25], 'inches'), ends=[2], type=[1])
+>>> len(a)
+1
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Sequence, Union
+
+import numpy as np
+
+from ._units import Unit, unit_rep
+
+__all__ = ["Arrow", "arrow"]
+
+
+def _recycle_unit(u: Unit, n: int) -> Unit:
+    """Recycle a Unit to length *n* using indexing with modular indices."""
+    lu = len(u)
+    if lu == n:
+        return u
+    indices = [i % lu for i in range(n)]
+    return u[indices]
+
+# Valid string values for *ends* and *type*, following R's match() semantics.
+_VALID_ENDS = ("first", "last", "both")
+_VALID_TYPES = ("open", "closed")
+
+
+class Arrow:
+    """Description of an arrow head to attach to a line-based grob.
+
+    Parameters
+    ----------
+    angle : float or Sequence[float]
+        Angle of the arrow head in degrees (the angle between the shaft and
+        each edge of the arrow head).  Scalar or vector.
+    length : Unit, optional
+        Length of the arrow head measured along the edges.  Must be a
+        :class:`Unit` object.  Defaults to ``Unit(0.25, "inches")``.
+    ends : {"first", "last", "both"} or Sequence[str]
+        Which end(s) of the line should receive an arrow head.  Encoded
+        internally as integers: ``1`` = first, ``2`` = last, ``3`` = both,
+        matching R's ``match()`` convention.
+    type : {"open", "closed"} or Sequence[str]
+        Whether the arrow head is open or closed.  Encoded internally as
+        integers: ``1`` = open, ``2`` = closed.
+
+    Raises
+    ------
+    TypeError
+        If *length* is not a :class:`Unit` object.
+    ValueError
+        If *ends* or *type* contains invalid values.
+    """
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    def __init__(
+        self,
+        angle: Union[float, int, Sequence[float]] = 30,
+        length: Optional[Unit] = None,
+        ends: Union[str, Sequence[str]] = "last",
+        type: Union[str, Sequence[str]] = "open",  # noqa: A002
+    ) -> None:
+        # --- angle --------------------------------------------------------
+        if isinstance(angle, (int, float, np.integer, np.floating)):
+            self._angle: np.ndarray = np.asarray([float(angle)], dtype=np.float64)
+        else:
+            self._angle = np.asarray(angle, dtype=np.float64).ravel()
+
+        # --- length -------------------------------------------------------
+        if length is None:
+            length = Unit(0.25, "inches")
+        if not isinstance(length, Unit):
+            raise TypeError("'length' must be a Unit object")
+        self._length: Unit = length
+
+        # --- ends ---------------------------------------------------------
+        self._ends: np.ndarray = self._encode_match(ends, _VALID_ENDS, "ends")
+
+        # --- type ---------------------------------------------------------
+        self._type: np.ndarray = self._encode_match(type, _VALID_TYPES, "type")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _encode_match(
+        value: Union[str, Sequence[str]],
+        valid: tuple,
+        label: str,
+    ) -> np.ndarray:
+        """Encode string(s) to 1-based integer codes, like R's ``match()``.
+
+        Parameters
+        ----------
+        value : str or Sequence[str]
+            Input value(s).
+        valid : tuple of str
+            Allowed string values.
+        label : str
+            Name used in error messages.
+
+        Returns
+        -------
+        np.ndarray
+            1-based integer codes corresponding to *value*.
+
+        Raises
+        ------
+        ValueError
+            If any element of *value* is not in *valid*.
+        """
+        if isinstance(value, str):
+            value = [value]
+        codes: List[int] = []
+        for v in value:
+            if v not in valid:
+                raise ValueError(
+                    f"invalid '{label}' argument: {v!r}; "
+                    f"must be one of {valid}"
+                )
+            codes.append(valid.index(v) + 1)
+        arr = np.asarray(codes, dtype=np.int64)
+        if arr.size == 0:
+            raise ValueError(f"'{label}' must have length > 0")
+        return arr
+
+    # ------------------------------------------------------------------
+    # Properties (read-only access to internal data)
+    # ------------------------------------------------------------------
+
+    @property
+    def angle(self) -> np.ndarray:
+        """Arrow-head angle(s) in degrees."""
+        return self._angle
+
+    @property
+    def length(self) -> Unit:
+        """Arrow-head length as a :class:`Unit`."""
+        return self._length
+
+    @property
+    def ends(self) -> np.ndarray:
+        """Integer code(s) for which end gets an arrow (1=first, 2=last, 3=both)."""
+        return self._ends
+
+    @property
+    def type(self) -> np.ndarray:
+        """Integer code(s) for arrow type (1=open, 2=closed)."""
+        return self._type
+
+    # ------------------------------------------------------------------
+    # length (len) -- mirrors R's length.arrow
+    # ------------------------------------------------------------------
+
+    def __len__(self) -> int:
+        """Return the effective vector length of this Arrow.
+
+        Follows R's ``length.arrow`` which returns the maximum of the
+        lengths of all component vectors (angle, length, ends, type).
+
+        Returns
+        -------
+        int
+            Effective length.
+        """
+        return int(
+            max(
+                len(self._angle),
+                len(self._length),
+                len(self._ends),
+                len(self._type),
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Subscript -- mirrors R's `[.arrow`
+    # ------------------------------------------------------------------
+
+    def __getitem__(self, index: Union[int, slice, Sequence[int]]) -> "Arrow":
+        """Subset an Arrow, recycling components to a common length first.
+
+        Parameters
+        ----------
+        index : int, slice, or Sequence[int]
+            Index(es) to select.
+
+        Returns
+        -------
+        Arrow
+            A new :class:`Arrow` with the selected elements.
+        """
+        maxn = len(self)
+
+        # Recycle each component to *maxn*.
+        angle = np.resize(self._angle, maxn)
+        length = _recycle_unit(self._length, maxn)
+        ends = np.resize(self._ends, maxn)
+        type_ = np.resize(self._type, maxn)
+
+        # Apply the index.
+        new = object.__new__(Arrow)
+        new._angle = np.atleast_1d(angle[index])
+        new._length = length[index]
+        new._ends = np.atleast_1d(ends[index])
+        new._type = np.atleast_1d(type_[index])
+        return new
+
+    # ------------------------------------------------------------------
+    # rep -- mirrors R's rep.arrow
+    # ------------------------------------------------------------------
+
+    def rep(self, times: int = 1, length_out: Optional[int] = None) -> "Arrow":
+        """Repeat the Arrow, recycling components to a common length first.
+
+        Parameters
+        ----------
+        times : int, optional
+            Number of times to repeat (default ``1``).
+        length_out : int, optional
+            Desired length of the result.  If given, *times* is ignored and
+            the output is truncated or recycled to this length.
+
+        Returns
+        -------
+        Arrow
+            A new :class:`Arrow` with repeated elements.
+        """
+        maxn = len(self)
+
+        # First recycle components to the common length.
+        angle = np.resize(self._angle, maxn)
+        ends = np.resize(self._ends, maxn)
+        type_ = np.resize(self._type, maxn)
+        length = _recycle_unit(self._length, maxn)
+
+        # Then tile by *times*.
+        angle = np.tile(angle, times)
+        ends = np.tile(ends, times)
+        type_ = np.tile(type_, times)
+        length = unit_rep(length, times)
+
+        # Trim / recycle to *length_out* if requested.
+        if length_out is not None:
+            angle = np.resize(angle, length_out)
+            ends = np.resize(ends, length_out)
+            type_ = np.resize(type_, length_out)
+            length = _recycle_unit(length, length_out)
+
+        new = object.__new__(Arrow)
+        new._angle = angle
+        new._length = length
+        new._ends = ends
+        new._type = type_
+        return new
+
+    # ------------------------------------------------------------------
+    # repr
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return (
+            f"Arrow(angle={self._angle.tolist()}, "
+            f"length={self._length!r}, "
+            f"ends={self._ends.tolist()}, "
+            f"type={self._type.tolist()})"
+        )
+
+
+# ----------------------------------------------------------------------
+# Factory function
+# ----------------------------------------------------------------------
+
+
+def arrow(
+    angle: Union[float, int, Sequence[float]] = 30,
+    length: Optional[Unit] = None,
+    ends: Union[str, Sequence[str]] = "last",
+    type: Union[str, Sequence[str]] = "open",  # noqa: A002
+) -> Arrow:
+    """Create an Arrow specification.
+
+    This is the main user-facing factory function, equivalent to R's
+    ``grid::arrow()``.
+
+    Parameters
+    ----------
+    angle : float or Sequence[float], optional
+        Angle of the arrow head in degrees (default ``30``).
+    length : Unit, optional
+        Length of the arrow head edges.  Defaults to
+        ``Unit(0.25, "inches")``.
+    ends : {"first", "last", "both"} or Sequence[str], optional
+        Which end(s) of the line receive an arrow head (default ``"last"``).
+    type : {"open", "closed"} or Sequence[str], optional
+        Arrow head style (default ``"open"``).
+
+    Returns
+    -------
+    Arrow
+        A new :class:`Arrow` instance.
+
+    Examples
+    --------
+    >>> from grid_py._arrow import arrow
+    >>> a = arrow(angle=45, type="closed")
+    >>> a
+    Arrow(angle=[45.0], length=Unit([0.25], 'inches'), ends=[2], type=[2])
+    """
+    return Arrow(angle=angle, length=length, ends=ends, type=type)