rgrid-python 4.5.3.post3__py3-none-any.whl → 4.5.3.post5__py3-none-any.whl

grid_py/__init__.py

@@ -6,7 +6,7 @@ units, viewports, grobs (graphical objects), layouts, and rendering via
 Cairo (pycairo).
 """
 
-__version__ = "4.5.3.post3"
+__version__ = "4.5.3.post5"
 
 # --- Utilities ---
 from grid_py._utils import depth, explode, grid_pretty, n2mfrow

grid_py/_colour.py

@@ -761,8 +761,15 @@ def parse_r_colour(c: Any) -> Tuple[float, float, float, float]:
         s = c.strip()
         low = s.lower()
 
-        # Transparent / NA
-        if low in ("transparent", "na", "none", ""):
+        # R's ``col2rgb("transparent", alpha=TRUE)`` returns (255, 255, 255, 0)
+        # — by R convention the RGB channels are white even though α=0
+        # makes the colour invisible.  Mirror exactly so hex round-trips
+        # and downstream tooling that compares against R's encoding agree.
+        if low == "transparent":
+            return (1.0, 1.0, 1.0, 0.0)
+        # NA / none / "" are Python-port-specific transparent sentinels not
+        # defined as parseable colours in R (``col2rgb('NA')`` errors).
+        if low in ("na", "none", ""):
             return (0.0, 0.0, 0.0, 0.0)
 
         # Hex colour

grid_py/_draw.py

@@ -25,6 +25,7 @@ from ._state import get_state
 from ._display_list import DisplayList, DLDrawGrob
 from ._units import Unit
 from ._utils import grid_pretty as _grid_pretty
+from ._primitives import valid_pch
 
 __all__ = [
     "grid_draw",
@@ -215,7 +216,12 @@ def _draw_arrow_heads(
     try:
         l_w = float(renderer.resolve_w(length_unit, gp=gp))
         l_h = float(renderer.resolve_h(length_unit, gp=gp))
-    except Exception:
+    except (ValueError, AttributeError, TypeError) as exc:
+        warnings.warn(
+            f"arrow length cannot be resolved ({exc}); arrow head skipped",
+            UserWarning,
+            stacklevel=2,
+        )
         return
     length_dev = min(l_w, l_h)
     if not (length_dev > 0):
@@ -302,8 +308,16 @@ def _render_grob(
 
     # ---- rect -----------------------------------------------------------
     if cls == "rect":
-        xs = renderer.resolve_x_array(getattr(grob, "x", [0.0]), gp=gp)
-        ys = renderer.resolve_y_array(getattr(grob, "y", [0.0]), gp=gp)
+        # Use paired resolve_loc_array so that under a rotated viewport
+        # each rect's anchor (x_i, y_i) is mapped through the full 2-D
+        # CTM together, not via two independent 1-D projections (which
+        # silently drop the rotation contribution from the orthogonal
+        # axis — see _renderer_base.resolve_x_array docstring).
+        xs, ys = renderer.resolve_loc_array(
+            getattr(grob, "x", [0.0]),
+            getattr(grob, "y", [0.0]),
+            gp=gp,
+        )
         ws = renderer.resolve_w_array(getattr(grob, "width", [1.0]), gp=gp)
         hs = renderer.resolve_h_array(getattr(grob, "height", [1.0]), gp=gp)
         hj, vj = _resolve_just(grob)
@@ -326,9 +340,11 @@ def _render_grob(
 
     # ---- roundrect ------------------------------------------------------
     elif cls == "roundrect":
+        ax, ay = renderer.resolve_loc(
+            getattr(grob, "x", 0.0), getattr(grob, "y", 0.0), gp=gp,
+        )
         renderer.draw_roundrect(
-            x=renderer.resolve_x(getattr(grob, "x", 0.0), gp=gp),
-            y=renderer.resolve_y(getattr(grob, "y", 0.0), gp=gp),
+            x=ax, y=ay,
             w=renderer.resolve_w(getattr(grob, "width", 1.0), gp=gp),
             h=renderer.resolve_h(getattr(grob, "height", 1.0), gp=gp),
             r=renderer.resolve_w(getattr(grob, "r", 0.0), gp=gp),
@@ -339,17 +355,22 @@ def _render_grob(
 
     # ---- circle ---------------------------------------------------------
     elif cls == "circle":
+        cx, cy = renderer.resolve_loc(
+            getattr(grob, "x", 0.5), getattr(grob, "y", 0.5), gp=gp,
+        )
         renderer.draw_circle(
-            x=renderer.resolve_x(getattr(grob, "x", 0.5), gp=gp),
-            y=renderer.resolve_y(getattr(grob, "y", 0.5), gp=gp),
+            x=cx, y=cy,
             r=renderer.resolve_w(getattr(grob, "r", 0.5), gp=gp),
             gp=gp,
         )
 
     # ---- lines / polyline ------------------------------------------------
     elif cls in ("lines", "polyline"):
-        x = renderer.resolve_x_array(getattr(grob, "x", [0.0, 1.0]), gp=gp)
-        y = renderer.resolve_y_array(getattr(grob, "y", [0.0, 1.0]), gp=gp)
+        x, y = renderer.resolve_loc_array(
+            getattr(grob, "x", [0.0, 1.0]),
+            getattr(grob, "y", [0.0, 1.0]),
+            gp=gp,
+        )
         id_ = getattr(grob, "id", None)
         id_lengths = getattr(grob, "id_lengths", None)
         # R polylineGrob supports either `id` (per-point group) or
@@ -363,12 +384,36 @@ def _render_grob(
             id_ = np.atleast_1d(np.asarray(id_, dtype=int))
         renderer.draw_polyline(x, y, id_=id_, gp=gp)
 
+        # R linesGrob / polylineGrob carry an optional ``arrow=`` (port
+        # of src/grid.c::L_lines / L_polyline arrowhead emission).  The
+        # earlier code consumed it for ``segmentsGrob`` only, silently
+        # dropping it on lines / polyline — symptom: an arrow= argument
+        # produced a bare line.  Apply ``_draw_arrow_heads`` per
+        # polyline (each unique id) here, with the same reference-point
+        # convention segments uses.
+        arr = getattr(grob, "arrow", None)
+        if arr is not None:
+            if id_ is not None:
+                for uid in np.unique(id_):
+                    mask = id_ == uid
+                    if int(np.sum(mask)) >= 2:
+                        _draw_arrow_heads(
+                            np.asarray(x)[mask], np.asarray(y)[mask],
+                            arr, renderer, gp,
+                        )
+            elif len(x) >= 2:
+                _draw_arrow_heads(
+                    np.asarray(x), np.asarray(y), arr, renderer, gp,
+                )
+
     # ---- segments --------------------------------------------------------
     elif cls == "segments":
-        x0 = renderer.resolve_x_array(getattr(grob, "x0", []), gp=gp)
-        y0 = renderer.resolve_y_array(getattr(grob, "y0", []), gp=gp)
-        x1 = renderer.resolve_x_array(getattr(grob, "x1", []), gp=gp)
-        y1 = renderer.resolve_y_array(getattr(grob, "y1", []), gp=gp)
+        x0, y0 = renderer.resolve_loc_array(
+            getattr(grob, "x0", []), getattr(grob, "y0", []), gp=gp,
+        )
+        x1, y1 = renderer.resolve_loc_array(
+            getattr(grob, "x1", []), getattr(grob, "y1", []), gp=gp,
+        )
         renderer.draw_segments(x0=x0, y0=y0, x1=x1, y1=y1, gp=gp)
 
         # Each segment may carry its own arrowhead (``arrow=`` parameter on
@@ -387,8 +432,11 @@ def _render_grob(
     elif cls == "xspline":
         from ._curve import _calc_xspline_points  # lazy to avoid import cycle
 
-        x = renderer.resolve_x_array(getattr(grob, "x", [0.0, 1.0]), gp=gp)
-        y = renderer.resolve_y_array(getattr(grob, "y", [0.0, 1.0]), gp=gp)
+        x, y = renderer.resolve_loc_array(
+            getattr(grob, "x", [0.0, 1.0]),
+            getattr(grob, "y", [0.0, 1.0]),
+            gp=gp,
+        )
         shape_raw = getattr(grob, "shape", 0.0)
         open_ = bool(getattr(grob, "open_", True))
         rep_ends = bool(getattr(grob, "repEnds", True))
@@ -469,8 +517,9 @@ def _render_grob(
 
     # ---- polygon ---------------------------------------------------------
     elif cls == "polygon":
-        px = renderer.resolve_x_array(getattr(grob, "x", []), gp=gp)
-        py = renderer.resolve_y_array(getattr(grob, "y", []), gp=gp)
+        px, py = renderer.resolve_loc_array(
+            getattr(grob, "x", []), getattr(grob, "y", []), gp=gp,
+        )
         pid = getattr(grob, "id", None)
         if pid is not None:
             # R semantics: polygonGrob(id=...) draws separate polygons
@@ -504,9 +553,8 @@ def _render_grob(
         else:
             labels = [str(label_raw)]
 
-        # Resolve x/y to arrays
-        xx = renderer.resolve_x_array(x_unit, gp=gp)
-        yy = renderer.resolve_y_array(y_unit, gp=gp)
+        # Resolve x/y as pairs so rotation contribution is preserved.
+        xx, yy = renderer.resolve_loc_array(x_unit, y_unit, gp=gp)
 
         # Normalise rot to array
         if isinstance(rot_raw, (list, tuple, np.ndarray)):
@@ -548,16 +596,20 @@ def _render_grob(
     # ---- points ----------------------------------------------------------
     elif cls == "points":
         pch_raw = getattr(grob, "pch", 19)
-        # pch may be a scalar or per-point array — pass through as-is
-        if isinstance(pch_raw, (np.ndarray, list, tuple)):
-            pch_val = np.asarray(pch_raw, dtype=int)
-        elif isinstance(pch_raw, (int, float, np.integer, np.floating)):
-            pch_val = int(pch_raw)
-        else:
-            pch_val = 19
+        # pch may be a scalar (int or single character such as "."/"A")
+        # or a per-point array (possibly MIXED int/str, e.g.
+        # [".", 19, "A"]).  R keeps character pch as character and
+        # coerces numeric pch to int (grid:::valid.pch).  Normalise via
+        # the same helper and pass the result through *unchanged* — the
+        # renderer dispatches symbol-vs-glyph per point.  Do NOT force
+        # ``dtype=int`` (that crashes on "."), and do NOT substitute a
+        # silent default for non-numeric scalars (that masks bugs).
+        pch_val = valid_pch(pch_raw)
+        pts_x, pts_y = renderer.resolve_loc_array(
+            getattr(grob, "x", []), getattr(grob, "y", []), gp=gp,
+        )
         renderer.draw_points(
-            x=renderer.resolve_x_array(getattr(grob, "x", []), gp=gp),
-            y=renderer.resolve_y_array(getattr(grob, "y", []), gp=gp),
+            x=pts_x, y=pts_y,
             size=renderer.resolve_w(getattr(grob, "size", 1.0), gp=gp),
             pch=pch_val,
             gp=gp,
@@ -565,18 +617,63 @@ def _render_grob(
 
     # ---- pathgrob --------------------------------------------------------
     elif cls == "pathgrob":
-        x = renderer.resolve_x_array(getattr(grob, "x", []), gp=gp)
-        y = renderer.resolve_y_array(getattr(grob, "y", []), gp=gp)
-        path_id = getattr(grob, "pathId", None)
+        x, y = renderer.resolve_loc_array(
+            getattr(grob, "x", []), getattr(grob, "y", []), gp=gp,
+        )
+        # R ``pathGrob`` carries two grouping levels (src/grid.c::L_path):
+        #
+        #   - id / id_lengths : per-point SUB-PATH identifier — each
+        #     unique value is one closed Cairo sub-path.
+        #   - path_id / path_id_lengths : per-sub-path COMPOUND grouping
+        #     — each compound is filled+stroked independently with its
+        #     own fill rule application.
+        #
+        # The earlier port read ``grob.pathId`` (camelCase, never stored
+        # by path_grob) and ignored ``grob.id`` entirely, so every path
+        # collapsed into a single 8-vertex sub-path that connected the
+        # two rectangles into a bow-tie.  Read both attributes properly
+        # here and pass the per-point sub-path identifier through to
+        # ``draw_path`` (which iterates unique values).
+        sub_id = getattr(grob, "id", None)
+        sub_id_lengths = getattr(grob, "id_lengths", None)
+        if sub_id is None and sub_id_lengths is not None:
+            lengths = np.atleast_1d(np.asarray(sub_id_lengths, dtype=int))
+            sub_id = np.repeat(np.arange(1, len(lengths) + 1), lengths)
+        if sub_id is None:
+            sub_id = np.ones(len(x), dtype=int)
+        else:
+            sub_id = np.atleast_1d(np.asarray(sub_id, dtype=int))
+
+        # Optional second-level compound grouping.  R fills each
+        # compound separately with its own fill-rule application.  Most
+        # uses (and every current test) have a single compound; we
+        # iterate when more are supplied.
+        path_id = getattr(grob, "path_id", None)
+        path_id_lengths = getattr(grob, "path_id_lengths", None)
+        if path_id is None and path_id_lengths is not None:
+            lengths = np.atleast_1d(np.asarray(path_id_lengths, dtype=int))
+            path_id = np.repeat(np.arange(1, len(lengths) + 1), lengths)
+        rule = getattr(grob, "rule", "winding")
+
         if path_id is None:
-            path_id = np.ones(len(x), dtype=int)
+            renderer.draw_path(
+                x=x, y=y, path_id=sub_id, rule=rule, gp=gp,
+            )
         else:
-            path_id = np.atleast_1d(np.asarray(path_id, dtype=int))
-        renderer.draw_path(
-            x=x, y=y, path_id=path_id,
-            rule=getattr(grob, "rule", "winding"),
-            gp=gp,
-        )
+            # Map per-point compound id from per-sub-path path_id.
+            path_id_arr = np.atleast_1d(np.asarray(path_id, dtype=int))
+            unique_subs = np.unique(sub_id)
+            sub_to_compound = {int(s): int(path_id_arr[k % len(path_id_arr)])
+                               for k, s in enumerate(unique_subs)}
+            point_compound = np.asarray(
+                [sub_to_compound[int(s)] for s in sub_id], dtype=int,
+            )
+            for ck in np.unique(point_compound):
+                mask = point_compound == ck
+                renderer.draw_path(
+                    x=x[mask], y=y[mask], path_id=sub_id[mask],
+                    rule=rule, gp=gp,
+                )
 
     # ---- rastergrob ------------------------------------------------------
     elif cls == "rastergrob":
@@ -585,8 +682,9 @@ def _render_grob(
             image = getattr(grob, "image", None)
         if image is not None:
             hj, vj = _resolve_just(grob)
-            raw_x = renderer.resolve_x(getattr(grob, "x", 0.0), gp=gp)
-            raw_y = renderer.resolve_y(getattr(grob, "y", 0.0), gp=gp)
+            raw_x, raw_y = renderer.resolve_loc(
+                getattr(grob, "x", 0.0), getattr(grob, "y", 0.0), gp=gp,
+            )
             raw_w = renderer.resolve_w(getattr(grob, "width", 1.0), gp=gp)
             raw_h = renderer.resolve_h(getattr(grob, "height", 1.0), gp=gp)
             # `renderer.draw_raster` expects the *top-left* corner in y-down

grid_py/_gpar.py

@@ -20,14 +20,12 @@ __all__ = ["Gpar", "gpar", "get_gpar"]
 # Constants
 # ---------------------------------------------------------------------------
 
-_VALID_LTY: set[str] = {
-    "solid",
-    "dashed",
-    "dotted",
-    "dotdash",
-    "longdash",
-    "twodash",
-}
+# Derived from grid_py._lty so there is exactly one source of truth for
+# the named-lty set.  ``"blank"`` is added because R par/grid accepts it
+# even though it has no hex equivalent (it short-circuits the stroke).
+from ._lty import valid_named_lty as _valid_named_lty
+
+_VALID_LTY: frozenset[str] = _valid_named_lty()
 
 _VALID_LINEEND: set[str] = {"round", "butt", "square"}
 
@@ -77,9 +75,12 @@ def _as_list(value: Any) -> list:
     return [value]
 
 
-def _is_hex_lty(s: str) -> bool:
-    """Return True when *s* looks like a valid hex-string line-type spec."""
-    return all(c in "0123456789abcdefABCDEF" for c in s) and len(s) > 0
+# NOTE: ``_is_hex_lty`` used to live here.  It has been removed because
+# hex-string validity is now decided by ``grid_py._lty.resolve_lty``,
+# which is the single source of truth for both "is this lty valid?" and
+# "what dash array does it expand to?".  Keeping a separate validator
+# here would create the same kind of dual-source landmine that
+# motivated B7 in the first place.
 
 
 def _resolve_fontface(value: Any) -> int:
@@ -254,14 +255,19 @@ class Gpar:
                     ) from exc
 
             elif name == "lty":
+                # Validation delegates to grid_py._lty so accept/reject
+                # decisions match the renderer-time resolver exactly.
+                # ``resolve_lty`` raises ValueError on bad input with a
+                # message already containing the offending value, so we
+                # let it propagate (no try/except — principle 4).
+                from ._lty import is_blank_lty, resolve_lty
                 for v in vals:
-                    if isinstance(v, str):
-                        if v not in _VALID_LTY and not _is_hex_lty(v):
-                            raise ValueError(
-                                f"invalid line type '{v}'; must be one of "
-                                f"{sorted(_VALID_LTY)} or a hex string"
-                            )
-                    elif not isinstance(v, (int, float, np.integer, np.floating)):
+                    if is_blank_lty(v):
+                        continue
+                    if isinstance(v, (str, int, float, np.integer, np.floating)) \
+                       and not isinstance(v, bool):
+                        resolve_lty(v)   # raises ValueError if invalid
+                    else:
                         raise TypeError(
                             f"'lty' must be str or numeric, got {type(v).__name__}"
                         )
@@ -462,6 +468,26 @@ class Gpar:
         gp._params = merged
         return gp
 
+    # -- mod (R: mod.gpar) -------------------------------------------------
+
+    def _mod(self, new_gp: "Gpar") -> "Gpar":
+        """Edit-time merge (R ``mod.gpar`` — gpar.R:298-304).
+
+        Plain key overwrite — ``new_gp``'s keys replace ``self``'s keys,
+        unmentioned keys are kept unchanged. Unlike :meth:`_merge`
+        (which mirrors R ``set.gpar`` and multiplies cumulative
+        params like ``cex`` / ``alpha`` / ``lex``), this method is the
+        one used by ``editGrob`` and does NOT multiply — R's
+        ``mod.gpar`` does a single ``gp[names(newgp)] <- newgp``.
+        """
+        if not self._params:
+            return new_gp
+        merged = copy.deepcopy(self._params)
+        merged.update(copy.deepcopy(new_gp._params))
+        gp = object.__new__(Gpar)
+        gp._params = merged
+        return gp
+
     # -- display -----------------------------------------------------------
 
     def __repr__(self) -> str:

grid_py/_grob.py

@@ -1157,12 +1157,15 @@ def _edit_this_grob(grob: Grob, specs: dict[str, Any]) -> Grob:
         if not key:
             continue
         if key == "gp":
-            # Special handling: merge gpar
+            # Special handling — R editGrob uses ``mod.gpar`` (gpar.R:298-304)
+            # which does a plain key overwrite (``gp[names(newgp)] <- newgp``)
+            # *without* the cumulative cex/alpha/lex multiplication that
+            # viewport-push's ``set.gpar`` applies. ``Gpar._mod`` is the
+            # mirror; ``Gpar._merge`` is the cumulative one.
             if value is None:
                 grob._gp = None
             elif grob._gp is not None:
-                # Merge new gp on top of existing
-                grob._gp = grob._gp.merge(value) if hasattr(grob._gp, "merge") else value
+                grob._gp = grob._gp._mod(value)
             else:
                 grob._gp = value
         elif key == "name":

grid_py/_lty.py

@@ -0,0 +1,197 @@
+"""Linetype resolution — R-faithful port of GE_LTYpar + CairoLineType.
+
+This is the single source of truth for translating any R-accepted lty
+specification (named string, R integer 0..6, hex string of length
+{2,4,6,8}) into a Cairo / SVG ready dash array.  Both the Cairo and the
+Web renderers consume the same ``resolve_lty`` output, so any lty
+behaviour fix lands in exactly one place.
+
+R reference (R 4.5.3):
+    src/include/R_ext/GraphicsEngine.h:406-412   (LTY_* constants)
+    src/main/engine.c::GE_LTYpar                 (string -> 32-bit int)
+    src/library/grDevices/src/cairoFns.c::CairoLineType
+                                                 (int -> dash array)
+
+The cairo-dash scaling factor is *1.0*: ``set_dash([nibble * lwd, ...])``.
+This was empirically verified by reverse-engineering R's cairo PNG output
+(lty="44" at lwd in {1, 1.5, 2, 4, 6, 8} matches ``period = 2*nibble*lwd
++ 2*cap``, where cap ~= lwd for the default lineend="round").  A 0.75
+factor that appeared in early drafts of this file was a memory error
+(possibly conflated with a non-cairo R device) and would cause every
+dash pattern to shrink by 25 %.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Union
+
+import numpy as np
+
+__all__ = [
+    "resolve_lty",
+    "is_blank_lty",
+    "valid_named_lty",
+]
+
+
+# ---------------------------------------------------------------------------
+# R-gold constants (verbatim from R source, do not edit without R reference)
+# ---------------------------------------------------------------------------
+
+# GraphicsEngine.h:407-412 — every named lty is *also* expressible as a
+# hex string, so resolve_lty has a single parser code path.  Low nibble
+# of the integer constant sits in the leftmost character of the hex
+# string (R's GE_LTYpar packs bits low-to-high as it scans left-to-right).
+#   LTY_SOLID    = 0          ""
+#   LTY_DASHED   = 0x44       "44"
+#   LTY_DOTTED   = 0x31       -> low nibble 1, high nibble 3 -> "13"
+#   LTY_DOTDASH  = 0x3431                                     "1343"
+#   LTY_LONGDASH = 0x37                                       "73"
+#   LTY_TWODASH  = 0x2622                                     "2262"
+_LTY_NAMED_TO_HEX: dict[str, str] = {
+    "solid":    "",
+    "dashed":   "44",
+    "dotted":   "13",
+    "dotdash":  "1343",
+    "longdash": "73",
+    "twodash":  "2262",
+}
+
+# R ?par integer codes (user-facing).  Note that "user-facing 0" is BLANK,
+# *not* the internal LTY_SOLID=0 constant: GE_LTYpar maps user 0 -> internal
+# LTY_BLANK (-1) and user 1 -> internal LTY_SOLID (0).
+_LTY_INT_TO_NAME: dict[int, str] = {
+    1: "solid",
+    2: "dashed",
+    3: "dotted",
+    4: "dotdash",
+    5: "longdash",
+    6: "twodash",
+}
+
+# R-gold (empirically verified): GE_LTYpar rejects any hex string whose
+# length is not in {2, 4, 6, 8}.  Single nibble "F" -> "invalid line
+# type: must be length 2, 4, 6 or 8".
+_LTY_VALID_HEX_LENS: frozenset[int] = frozenset({2, 4, 6, 8})
+
+LtyInput = Union[str, int, float, None, list, tuple, np.ndarray]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def valid_named_lty() -> frozenset[str]:
+    """Set of R named lty values accepted by Gpar (includes ``"blank"``)."""
+    return frozenset(_LTY_NAMED_TO_HEX.keys()) | {"blank"}
+
+
+def is_blank_lty(value: LtyInput) -> bool:
+    """True iff *value* represents R LTY_BLANK (caller should skip stroke).
+
+    Mirrors R par convention:
+      * user-facing integer 0   -> blank
+      * "blank" (string)        -> blank
+      * NA / None inside a Gpar list sentinel  -> blank
+      * **but** scalar ``None`` (no lty supplied) -> not blank (= solid)
+      * **but** string ``"0"`` -> not blank (R rejects len-1 hex; see
+        resolve_lty); we follow R's quirk and only treat *integer* 0 as
+        blank, not string "0".
+    """
+    if value is None:
+        return False
+    raw = value[0] if isinstance(value, (list, tuple, np.ndarray)) and len(value) else value
+    if raw is None:
+        return True
+    if isinstance(raw, (int, float, np.integer, np.floating)) and not isinstance(raw, bool):
+        return int(raw) == 0
+    return str(raw).lower() == "blank"
+
+
+def resolve_lty(value: LtyInput, lwd: float = 1.0) -> Optional[list[float]]:
+    """Resolve any R-accepted lty input into a Cairo-ready dash array.
+
+    Parameters
+    ----------
+    value : str | int | float | None | sequence
+        - ``None``                       -> solid
+        - One of ``valid_named_lty()``   -> the canonical hex pattern
+        - Hex string, length in {2,4,6,8} with chars [0-9A-Fa-f]
+        - Integer in 1..6 (R par convention; 0 is BLANK and must be
+          caught by ``is_blank_lty`` *before* calling this function)
+        - List/tuple/ndarray: first element is used (R recycling rule
+          is the caller's job)
+
+    Returns
+    -------
+    None or list[float]
+        - ``None`` for solid (no dashing)
+        - Otherwise the cairo ``set_dash`` array.  Each element is
+          ``hex_digit * lwd`` user-space units (or whatever space the
+          caller's ``lwd`` lives in — caller must keep lwd and dash in
+          the same coordinate system).
+
+    Raises
+    ------
+    ValueError
+        On unrecognised input.  Caller must invoke ``is_blank_lty``
+        first; passing a blank-representing value here raises.
+    """
+    if value is None:
+        return None
+    raw = value[0] if isinstance(value, (list, tuple, np.ndarray)) and len(value) else value
+    if raw is None:
+        # Caller forgot to short-circuit via is_blank_lty.  Fail loud
+        # (per principle 4 — do not silently convert blank to solid).
+        raise ValueError(
+            "blank lty (NA sentinel) must be handled by caller via is_blank_lty()"
+        )
+
+    # R integer path — par convention 1..6 (0 is BLANK, handled by caller).
+    if isinstance(raw, (int, float, np.integer, np.floating)) and not isinstance(raw, bool):
+        i = int(raw)
+        if i == 0:
+            raise ValueError(
+                "lty=0 is BLANK; caller must check is_blank_lty() before resolve_lty()"
+            )
+        if i not in _LTY_INT_TO_NAME:
+            raise ValueError(f"Invalid integer lty: {i!r} (must be in 1..6)")
+        raw = _LTY_INT_TO_NAME[i]
+
+    s = str(raw)
+
+    # Named lty -> canonical hex (single parser path below for both forms)
+    if s in _LTY_NAMED_TO_HEX:
+        s = _LTY_NAMED_TO_HEX[s]
+
+    if s == "":
+        return None   # solid
+
+    # Hex string validation — R GE_LTYpar rules (empirically verified):
+    #   non-hex char        -> "invalid hex digit in 'color' or 'lty'"
+    #   length not in 2/4/6/8 -> "invalid line type: must be length 2, 4, 6 or 8"
+    if not all(c in "0123456789abcdefABCDEF" for c in s):
+        raise ValueError(f"Invalid lty: {s!r} (invalid hex digit)")
+    if len(s) not in _LTY_VALID_HEX_LENS:
+        raise ValueError(
+            f"Invalid lty: {s!r} (length {len(s)} not in {{2,4,6,8}})"
+        )
+
+    # Cairo dash expansion — equivalent to R cairoFns.c::CairoLineType:
+    #     while (l < 8 && lty != 0) {
+    #         dt = lty & 15;
+    #         if (dt == 0) break;     // zero nibble terminates pattern
+    #         ls[l] = dt * lwd;       // scale factor 1.0 (R-verified)
+    #         lty = lty >> 4;
+    #         l++;
+    #     }
+    # R's length pre-check guarantees s is len 2/4/6/8, so the only place a
+    # zero nibble appears is at the *end* of a longer pattern (e.g. "4400"
+    # legitimately means [4, 4] then stop).
+    dashes: list[float] = []
+    for c in s:
+        d = int(c, 16)
+        if d == 0:
+            break
+        dashes.append(d * lwd)
+    return dashes if dashes else None

grid_py/_patterns.py

@@ -914,8 +914,13 @@ def _resolve_linear_gradient(grad: LinearGradient) -> ResolvedPattern:
             "stops": grad.stops,
             "extend": grad.extend,
         }
-    except Exception:
-        # Fallback: store the original gradient for later resolution
+    except (ValueError, AttributeError, TypeError, IndexError):
+        # Documented deferred-resolution fallback: when the gradient's
+        # endpoint Units can't be resolved against the current
+        # renderer state (e.g. ``"npc"`` outside a viewport), stash the
+        # original gradient so the renderer can resolve it later. R's
+        # ``resolvePattern.GridLinearGradient`` (patterns.R:401-418)
+        # delegates the same way via lazy attr lookup.
         ref = {"type": "linear_gradient", "pattern": grad}
 
     return ResolvedPattern(grad, ref)
@@ -949,7 +954,8 @@ def _resolve_radial_gradient(grad: RadialGradient) -> ResolvedPattern:
             "stops": grad.stops,
             "extend": grad.extend,
         }
-    except Exception:
+    except (ValueError, AttributeError, TypeError, IndexError):
+        # Deferred-resolution fallback — see ``_resolve_linear_gradient``.
         ref = {"type": "radial_gradient", "pattern": grad}
 
     return ResolvedPattern(grad, ref)
@@ -974,7 +980,8 @@ def _resolve_tiling_pattern(pat: Pattern) -> ResolvedPattern:
             "width": float(wh["w"][0]), "height": float(wh["h"][0]),
             "extend": pat.extend,
         }
-    except Exception:
+    except (ValueError, AttributeError, TypeError, IndexError):
+        # Deferred-resolution fallback — see ``_resolve_linear_gradient``.
         ref = {"type": "tiling_pattern", "pattern": pat}
 
     return ResolvedPattern(pat, ref)