TYP: Include proper type hints for static type checkers; remove PlottableType and redefinee lower pyvista dependency lower bound.

Author: ryder-davidson

pyproject.toml

@@ -54,7 +54,7 @@ classifiers = [
 requires-python = ">=3.10"
 dependencies = [
   "numpy>=2.1.0",
-  "pyvista>=0.47.0",
+  "pyvista>=0.46.0",
   "psi-io>=2.0.6",
   "sunpy>=6.0.3",
   "astropy>=6.1.3",

pyvisual/core/_typing.py

@@ -24,7 +24,13 @@
 from os import PathLike
 from pathlib import Path
 
-from typing import Literal
+from typing import Literal, Union, TypeAlias
+
+from pyvista import VectorLike
+
+PlottableType: TypeAlias = Union[
+    VectorLike[float], 'DataSet', 'MultiBlock', 'PartitionedDataSet', str, Path
+]
 
 PathType = str | Path | PathLike[str]
 """Type alias for filesystem path arguments.

pyvisual/core/mesh3d.py

@@ -124,7 +124,7 @@ def build_point_polydata(d1: np.ndarray,
                          d2: np.ndarray,
                          d3: np.ndarray,
                          axis: int,
-                         frame: Optional[MeshFramesType] = None):
+                         frame: Optional[MeshFramesType] = None) -> pv.PolyData:
     """Build an unconnected :class:`pyvista.PolyData` point cloud from coordinate arrays.
 
     Each element of ``d1``, ``d2``, ``d3`` along ``axis`` defines one point.
@@ -160,7 +160,7 @@ def build_spline_polydata(d1: np.ndarray,
                           d2: np.ndarray,
                           d3: np.ndarray,
                           axis: int,
-                          frame: Optional[MeshFramesType] = None):
+                          frame: Optional[MeshFramesType] = None) -> pv.PolyData:
     """Build a line-connected :class:`pyvista.PolyData` of splines from coordinate arrays.
 
     After moving ``axis`` to the leading dimension, the arrays are reshaped to
@@ -201,7 +201,7 @@ def build_slice_polydata(d1: np.ndarray,
                          d2: np.ndarray,
                          d3: np.ndarray,
                          axis: int,
-                         frame: Optional[MeshFramesType] = None):
+                         frame: Optional[MeshFramesType] = None) -> pv.PolyData:
     """Build a quad-faced :class:`pyvista.PolyData` surface patch from coordinate arrays.
 
     The coordinate arrays are moved so that ``axis`` is the leading dimension,
@@ -260,7 +260,7 @@ def build_surface_polydata(d1: np.ndarray,
                            axis: int,
                            method: SurfaceReconstructionType = 'reconstruct_surface',
                            frame: Optional[MeshFramesType] = None,
-                           **kwargs):
+                           **kwargs) -> pv.PolyData:
     """Build a surface mesh from scattered coordinate arrays using a reconstruction method.
 
     First assembles a point cloud via :func:`build_point_polydata`, then applies
@@ -315,7 +315,7 @@ def build_thompson_sphere(d1: float,
                           d3: float,
                           theta_resolution: int = 180,
                           phi_resolution: int = 360,
-                          frame: Optional[MeshFramesType] = None):
+                          frame: Optional[MeshFramesType] = None) -> pv.PolyData:
     """Build a Thomson sphere centered halfway between the origin and an observer position.
 
     The Thomson sphere for a given observer has:

pyvisual/core/mixins.py

@@ -802,9 +802,9 @@ def add_1d_slice(self,
             raise ValueError("1D slices requires exactly two fixed scales.")
         try:
             axis = next(i for i, s in enumerate(mesh_shape) if s > 1)
-        except StopIteration:
+        except StopIteration as e:
             msg = f"Could not infer slice axis from input shapes: {mesh_shape}"
-            raise ValueError(msg)
+            raise ValueError(msg) from e
         return self._add_grid_set(r, t, p, data,
                                   axis, dataid,
                                   slice_type='splines',
@@ -899,9 +899,9 @@ def add_2d_slice(self,
             raise ValueError("2D slices requires exactly one fixed scale.")
         try:
             axis = next(i for i, s in enumerate(mesh_shape) if s == 1)
-        except StopIteration:
+        except StopIteration as e:
             msg = f"Could not infer slice axis from input shapes: {mesh_shape}"
-            raise ValueError(msg)
+            raise ValueError(msg) from e
         return self._add_grid_set(r, t, p, data,
                                   axis, dataid,
                                   slice_type='slices',
@@ -1309,7 +1309,7 @@ def observer_viewup(self) -> SphericalCoordinate:
 
     @observer_viewup.setter
     @render_scene
-    def observer_viewup(self, args):
+    def observer_viewup(self, args) -> None:
         r, t, p = args
         self.camera.up = spherical_to_cartesian(r, t, p)
 
@@ -1344,7 +1344,7 @@ def observer_position(self) -> SphericalCoordinate:
 
     @observer_position.setter
     @render_scene
-    def observer_position(self, args):
+    def observer_position(self, args) -> None:
         r, t, p = args
         self.camera.position = spherical_to_cartesian(r, t, p)
 
@@ -1363,7 +1363,7 @@ def observer_focus(self) -> SphericalCoordinate:
 
     @observer_focus.setter
     @render_scene
-    def observer_focus(self, args):
+    def observer_focus(self, args) -> None:
         r, t, p = args
         self.camera.focal_point = spherical_to_cartesian(r, t, p)
 
@@ -1401,7 +1401,7 @@ def observer_orientation(self) -> ObserverOrientation:
 
     @observer_orientation.setter
     @render_scene
-    def observer_orientation(self, arg):
+    def observer_orientation(self, arg) -> None:
         p_angle = arg
         current_p_angle = camera_roll_wrt_solar_north(*self.camera_position)
         self.camera.roll += (p_angle - current_p_angle)
@@ -1520,7 +1520,7 @@ def observer_los_view(self) -> tuple[float, float, float, float]:
 
     @observer_los_view.setter
     @render_scene
-    def observer_los_view(self, args):
+    def observer_los_view(self, args) -> None:
         x0, x1, y0, y1 = args
 
         elongation = (x0 + x1) / 2
@@ -1604,7 +1604,7 @@ def observer_fov_view(self) -> Optional[float]:
 
     @observer_fov_view.setter
     @render_scene
-    def observer_fov_view(self, args):
+    def observer_fov_view(self, args) -> None:
         rmin = abs(args)
         dobs = self.observer_position.r
         if rmin < dobs:

pyvisual/core/parsers.py

@@ -51,8 +51,8 @@
 import numpy as np
 import pyvista as pv
 from pyvista import algorithm_to_mesh_handler
-from pyvista.plotting._typing import PlottableType
 
+from pyvisual.core._typing import PlottableType
 from pyvisual.core.constants import FRAME_ALIASES
 from pyvisual.utils.helpers import atleast_1dnull
 from pyvisual.utils.geometry import (
@@ -248,7 +248,8 @@ def decorator(self,
     return decorator
 
 
-def generate_transforms(mframe, pframe):
+def generate_transforms(mframe: str,
+                        pframe: str) -> list[Callable]:
     """Return a list of coordinate-conversion functions from ``mframe`` to ``pframe``.
 
     Looks up the ``(canonical_mframe, canonical_pframe)`` pair in
@@ -285,7 +286,7 @@ def generate_transforms(mframe, pframe):
     return transforms
 
 
-def validate_mesh_type(mesh: PlottableType):
+def validate_mesh_type(mesh: PlottableType) -> PlottableType:
     """Ensure ``mesh`` is a valid PyVista dataset, wrapping it if necessary.
 
     Resolves any VTK algorithm objects via
@@ -317,7 +318,9 @@ def validate_mesh_type(mesh: PlottableType):
     return mesh
 
 
-def apply_mesh_transform(mesh: PlottableType, mframe, pframe):
+def apply_mesh_transform(mesh: PlottableType,
+                         mframe: str,
+                         pframe: str) -> PlottableType:
     """Convert mesh point coordinates from ``mframe`` to ``pframe`` in-place on a copy.
 
     If the mesh stores a ``'MESH_FRAME'`` key in :attr:`pyvista.DataSet.user_dict`
@@ -368,7 +371,7 @@ def apply_mesh_transform(mesh: PlottableType, mframe, pframe):
 
 def parse_stack_mesh(r: np.ndarray,
                      t: np.ndarray,
-                     p: np.ndarray):
+                     p: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """Validate that three coordinate arrays share an identical shape.
 
     Used by :class:`~pyvisual.core.mixins.StackMeshMixin` methods to confirm that
@@ -402,7 +405,7 @@ def parse_stack_mesh(r: np.ndarray,
 
 def parse_grid_mesh(r: np.ndarray,
                     t: np.ndarray,
-                    p: np.ndarray):
+                    p: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """Validate and optionally broadcast coordinate arrays for a structured grid.
 
     Accepts two input conventions:

pyvisual/utils/data.py

@@ -192,7 +192,7 @@ def fetch_datasets(domains: Iterable[str] | str = 'cor',
     return Filepaths(*(FETCHER.fetch(f"cr2282-thermo2-{dom}/{var}002.h5") for dom, var in req_pairs))
 
 
-def fetch_theme():
+def fetch_theme() -> Path:
     """Return the path to the bundled PyVisual PyVista theme file.
 
     Resolves ``pyvisual_theme.json`` from the package's ``_assets`` directory

pyvisual/utils/geometry.py

@@ -298,7 +298,7 @@ def cartesian_to_spherical_vec(vr: ArrayLike,
                                vt: ArrayLike,
                                vp: ArrayLike,
                                t: ArrayLike,
-                               p: ArrayLike):
+                               p: ArrayLike) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """Rotate vector components from the local spherical basis to the Cartesian basis.
 
     Given a vector expressed in the local orthonormal spherical basis
@@ -396,7 +396,7 @@ def spherical_to_cartesian_vec(vx: ArrayLike,
                                vy: ArrayLike,
                                vz: ArrayLike,
                                t: ArrayLike,
-                               p: ArrayLike):
+                               p: ArrayLike) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """Rotate vector components from the Cartesian basis to the local spherical basis.
 
     Given a vector expressed in the global Cartesian basis
@@ -493,8 +493,7 @@ def rotate_position_about_x(
     x: ArrayLike,
     y: ArrayLike,
     z: ArrayLike,
-    angle: float,
-) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
+    angle: float,) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """Rotate Cartesian position vectors about the :math:`+x` axis.
 
     Applies a right-handed rotation by ``angle`` degrees about :math:`+x`
@@ -567,8 +566,7 @@ def rotate_position_about_y(
     x: ArrayLike,
     y: ArrayLike,
     z: ArrayLike,
-    angle: float,
-) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
+    angle: float,) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """Rotate Cartesian position vectors about the :math:`+y` axis.
 
     Applies a right-handed rotation by ``angle`` degrees about :math:`+y`
@@ -641,8 +639,7 @@ def rotate_position_about_z(
     x: ArrayLike,
     y: ArrayLike,
     z: ArrayLike,
-    angle: float,
-) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
+    angle: float,) -> tuple[ArrayLike, ArrayLike, ArrayLike]:
     """Rotate Cartesian position vectors about the :math:`+z` axis.
 
     Applies a right-handed rotation by ``angle`` degrees about :math:`+z`
@@ -712,7 +709,7 @@ def rotate_position_about_z(
 
 
 def clip_angle(angle: ArrayLike,
-               max_value: float = 180):
+               max_value: float = 180) -> np.ndarray | float:
     """Wrap an angle in degrees to a half-open interval of width 360°.
 
     Reduces ``angle`` modulo :math:`360°` and then shifts the result into
@@ -766,7 +763,7 @@ def thompson_sphere(elong: ArrayLike,
                     obs_lon: ArrayLike,
                     obs_lat: ArrayLike,
                     r_obs_rs: ArrayLike,
-                    obs_pangle: ArrayLike = 0.0):
+                    obs_pangle: ArrayLike = 0.0) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """Compute the 3-D intersection of a line of sight with the Thompson sphere.
 
     The `Thompson sphere
@@ -911,7 +908,7 @@ def thompson_sphere(elong: ArrayLike,
 
 
 def los_rmin2angle(rmin_rs: ArrayLike,
-                   d_obs_rs: float):
+                   d_obs_rs: float) -> np.ndarray | float:
     """Convert a LOS impact parameter :math:`r_{min}` to a helioprojective angle.
 
     The *impact parameter* :math:`r_{min}` is the distance of closest approach
@@ -986,7 +983,7 @@ def los_rmin2angle(rmin_rs: ArrayLike,
 
 
 def los_angle2rmin(angle_deg: ArrayLike,
-                   d_obs_rs: float):
+                   d_obs_rs: float) -> np.ndarray | float:
     """Convert a helioprojective angle to a LOS impact parameter :math:`r_{min}`.
 
     The inverse of :func:`los_rmin2angle`.  Given the helioprojective
@@ -1568,7 +1565,7 @@ def spacecraft_trajectory(
     return np.stack(ephemeris, axis=0)
 
 
-def _norm(x, eps=1e-12):
+def _norm(x: ArrayLike, eps: float = 1e-12):
     """Normalise a vector, returning ``None`` for near-zero inputs.
 
     Parameters
@@ -1596,8 +1593,7 @@ def camera_roll_wrt_solar_north(
     focal_point: tuple[float, float, float],
     view_up: tuple[float, float, float],
     world_up: tuple[float, float, float] = SOLAR_NORTH,
-    degrees: bool = True,
-):
+    degrees: bool = True,) -> float:
     """Compute the camera roll angle relative to a world "up” direction.
 
     The roll is the signed rotation **about the view axis**

pyvisual/utils/helpers.py

@@ -11,7 +11,7 @@
 
 
 def atleast_1dnull(*args,
-                   astuple: bool = False):
+                   astuple: bool = False) -> np.ndarray | None | tuple[np.ndarray | None, ...]:
     """:func:`numpy.atleast_1d` that passes ``None`` values through unchanged.
 
     A thin wrapper around :func:`numpy.atleast_1d` that treats ``None`` as a