From 13c12b0a6adb2555c9fff55cb512af6701ec54de Mon Sep 17 00:00:00 2001
From: Jan Petykiewicz <jan@mpxd.net>
Date: Wed, 16 Apr 2025 21:25:43 -0700
Subject: [PATCH] update docs to reflect new args
---
gridlock/draw.py | 34 ++++++++++++++++++----------------
gridlock/utils.py | 37 +++++++++++++++++++++++++++++++++++--
pyproject.toml | 1 -
3 files changed, 53 insertions(+), 19 deletions(-)
diff --git a/gridlock/draw.py b/gridlock/draw.py
index 0b93d20..9ba4623 100644
--- a/gridlock/draw.py
+++ b/gridlock/draw.py
@@ -21,30 +21,31 @@ foreground_callable_t = Callable[[NDArray, NDArray, NDArray], NDArray]
foreground_t = float | foreground_callable_t
-
class GridDrawMixin(GridPosMixin):
def draw_polygons(
self,
cell_data: NDArray,
+ foreground: Sequence[foreground_t] | foreground_t,
slab: SlabProtocol | SlabDict,
polygons: Sequence[ArrayLike],
- foreground: Sequence[foreground_t] | foreground_t,
*,
offset2d: ArrayLike = (0, 0),
) -> None:
"""
- Draw polygons on an axis-aligned plane.
+ Draw polygons on an axis-aligned slab.
Args:
cell_data: Cell data to modify (e.g. created by `Grid.allocate()`)
- center: 3-element ndarray or list specifying an offset applied to all the polygons
- polygons: List of Nx2 or Nx3 ndarrays, each specifying the vertices of a polygon
- (non-closed, clockwise). If Nx3, the `slab.axis`-th coordinate is ignored. Each
- polygon must have at least 3 vertices.
foreground: Value to draw with ('brush color'). Can be scalar, callable, or a list
of any of these (1 per grid). Callable values should take an ndarray the shape of the
grid and return an ndarray of equal shape containing the foreground value at the given x, y,
and z (natural, not grid coordinates).
+ slab: `Slab` or slab-like dict specifying the slab in which the polygons will be drawn.
+ polygons: List of Nx2 or Nx3 ndarrays, each specifying the vertices of a polygon
+ (non-closed, clockwise). If Nx3, the `slab.axis`-th coordinate is ignored. Each
+ polygon must have at least 3 vertices.
+ offset2d: 2D offset to apply to polygon coordinates -- this offset is added directly
+ to the given polygon vertex coordinates. Default (0, 0).
Raises:
GridError
@@ -200,9 +201,9 @@ class GridDrawMixin(GridPosMixin):
def draw_polygon(
self,
cell_data: NDArray,
+ foreground: Sequence[foreground_t] | foreground_t,
slab: SlabProtocol | SlabDict,
polygon: ArrayLike,
- foreground: Sequence[foreground_t] | foreground_t,
*,
offset2d: ArrayLike = (0, 0),
) -> None:
@@ -211,11 +212,13 @@ class GridDrawMixin(GridPosMixin):
Args:
cell_data: Cell data to modify (e.g. created by `Grid.allocate()`)
- slab: `Slab` in which to draw polygons.
+ foreground: Value to draw with ('brush color'). See `draw_polygons()` for details.
+ slab: `Slab` or slab-like dict specifying the slab in which the polygon will be drawn.
polygon: Nx2 or Nx3 ndarray specifying the vertices of a polygon (non-closed,
clockwise). If Nx3, the `slab.axis`-th coordinate is ignored. Must have at
least 3 vertices.
- foreground: Value to draw with ('brush color'). See `draw_polygons()` for details.
+ offset2d: 2D offset to apply to polygon coordinates -- this offset is added directly
+ to the given polygon vertex coordinates. Default (0, 0).
"""
self.draw_polygons(
cell_data = cell_data,
@@ -229,17 +232,16 @@ class GridDrawMixin(GridPosMixin):
def draw_slab(
self,
cell_data: NDArray,
- slab: SlabProtocol | SlabDict,
foreground: Sequence[foreground_t] | foreground_t,
+ slab: SlabProtocol | SlabDict,
) -> None:
"""
Draw an axis-aligned infinite slab.
Args:
cell_data: Cell data to modify (e.g. created by `Grid.allocate()`)
- slab:
- thickness: Thickness of the layer to draw
foreground: Value to draw with ('brush color'). See `draw_polygons()` for details.
+ slab: `Slab` or slab-like dict (geometrical slab specification)
"""
if isinstance(slab, dict):
slab = Slab(**slab)
@@ -282,10 +284,10 @@ class GridDrawMixin(GridPosMixin):
Args:
cell_data: Cell data to modify (e.g. created by `Grid.allocate()`)
- center: 3-element ndarray or list specifying the cuboid's center
- dimensions: 3-element list or ndarray containing the x, y, and z edge-to-edge
- sizes of the cuboid
foreground: Value to draw with ('brush color'). See `draw_polygons()` for details.
+ x: `Extent` or extent-like dict specifying the x-extent of the cuboid.
+ y: `Extent` or extent-like dict specifying the y-extent of the cuboid.
+ z: `Extent` or extent-like dict specifying the z-extent of the cuboid.
"""
if isinstance(x, dict):
x = Extent(**x)
diff --git a/gridlock/utils.py b/gridlock/utils.py
index 7a12035..8a8f11d 100644
--- a/gridlock/utils.py
+++ b/gridlock/utils.py
@@ -1,4 +1,4 @@
-from typing import Protocol, TypedDict, runtime_checkable
+from typing import Protocol, TypedDict, runtime_checkable, cast
from dataclasses import dataclass
@@ -8,6 +8,10 @@ class GridError(Exception):
class ExtentDict(TypedDict, total=False):
+ """
+ Geometrical definition of an extent (1D bounded region)
+ Must contain exactly two of `min`, `max`, `center`, or `span`.
+ """
min: float
center: float
max: float
@@ -16,6 +20,9 @@ class ExtentDict(TypedDict, total=False):
@runtime_checkable
class ExtentProtocol(Protocol):
+ """
+ Anything that looks like an `Extent`
+ """
center: float
span: float
@@ -28,6 +35,10 @@ class ExtentProtocol(Protocol):
@dataclass(init=False, slots=True)
class Extent(ExtentProtocol):
+ """
+ Geometrical definition of an extent (1D bounded region)
+ May be constructed with any two of `min`, `max`, `center`, or `span`.
+ """
center: float
span: float
@@ -88,6 +99,10 @@ class Extent(ExtentProtocol):
class SlabDict(TypedDict, total=False):
+ """
+ Geometrical definition of a slab (3D region bounded on one axis only)
+ Must contain `axis` plus any two of `min`, `max`, `center`, or `span`.
+ """
min: float
center: float
max: float
@@ -97,6 +112,9 @@ class SlabDict(TypedDict, total=False):
@runtime_checkable
class SlabProtocol(ExtentProtocol, Protocol):
+ """
+ Anything that looks like a `Slab`
+ """
axis: int
center: float
span: float
@@ -110,6 +128,10 @@ class SlabProtocol(ExtentProtocol, Protocol):
@dataclass(init=False, slots=True)
class Slab(Extent, SlabProtocol):
+ """
+ Geometrical definition of a slab (3D region bounded on one axis only)
+ May be constructed with `axis` (bounded axis) plus any two of `min`, `max`, `center`, or `span`.
+ """
axis: int
def __init__(
@@ -142,6 +164,10 @@ class Slab(Extent, SlabProtocol):
class PlaneDict(TypedDict, total=False):
+ """
+ Geometrical definition of a plane (2D unbounded region in 3D space)
+ Must contain exactly one of `x`, `y`, `z`, or both `axis` and `pos`
+ """
x: float
y: float
z: float
@@ -151,12 +177,19 @@ class PlaneDict(TypedDict, total=False):
@runtime_checkable
class PlaneProtocol(Protocol):
+ """
+ Anything that looks like a `Plane`
+ """
axis: int
pos: float
@dataclass(init=False, slots=True)
class Plane(PlaneProtocol):
+ """
+ Geometrical definition of a plane (2D unbounded region in 3D space)
+ May be constructed with any of `x=4`, `y=5`, `z=-5`, or `axis=2, pos=-5`.
+ """
axis: int
pos: float
@@ -192,7 +225,7 @@ class Plane(PlaneProtocol):
if pos is not None:
cpos = pos
else:
- cpos = (xx, yy, zz)[axis_int]
+ cpos = cast('float', (xx, yy, zz)[axis_int])
assert cpos is not None
if hasattr(cpos, '__len__'):
diff --git a/pyproject.toml b/pyproject.toml
index 1df2e8b..03d0d19 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -75,7 +75,6 @@ lint.ignore = [
"ANN002", # *args
"ANN003", # **kwargs
"ANN401", # Any
- "ANN101", # self: Self
"SIM108", # single-line if / else assignment
"RET504", # x=y+z; return x
"PIE790", # unnecessary pass