Add helpful hint error message if optional dependencies not yet installed.

.github/workflows/ci.yml

@@ -119,3 +119,47 @@ jobs:
               cd docs
               echo 'nb_execution_mode = "off"' >> conf.py
               make linkcheck
+
+  test-optional-deps:
+    # Ensures can install with various combinations of optional dependencies,
+    # and that some corresponding tests pass or crash appropriately.
+    # Just a single machine and single Python version should be good enough,
+    # the goal here is to spot-check that optional deps work as expected,
+    # not to run an exhaustive set of tests with each combination of deps.
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v7
+
+      - name: setup-python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: no optional deps
+        run: |
+          python -m venv "$RUNNER_TEMP/venv-none"
+          source "$RUNNER_TEMP/venv-none/bin/activate"
+          python -m pip install "." pytest
+          python -m pytest test_optional_deps/test_installed_with_no_opts.py
+
+      - name: geo only
+        run: |
+          python -m venv "$RUNNER_TEMP/venv-geo"
+          source "$RUNNER_TEMP/venv-geo/bin/activate"
+          python -m pip install ".[geo]" pytest
+          python -m pytest test_optional_deps/test_installed_with_geo.py
+
+      - name: viz only
+        run: |
+          python -m venv "$RUNNER_TEMP/venv-viz"
+          source "$RUNNER_TEMP/venv-viz/bin/activate"
+          python -m pip install ".[viz]" pytest
+          python -m pytest test_optional_deps/test_installed_with_viz.py
+
+      - name: viz and geo
+        run: |
+          python -m venv "$RUNNER_TEMP/venv-viz_and_geo"
+          source "$RUNNER_TEMP/venv-viz_and_geo/bin/activate"
+          python -m pip install ".[viz,geo]" pytest
+          python -m pytest test_optional_deps/test_installed_with_viz_and_geo.py

pyproject.toml

@@ -98,3 +98,6 @@ known-first-party = ["uxarray"]
 
 [tool.ruff.format]
 docstring-code-format = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]  # (intentionally excludes test_optional_deps)

test_optional_deps/_optional_deps_helpers.py

@@ -0,0 +1,58 @@
+"""
+File Purpose: defines helper functions to be used for testing optional dependencies.
+
+The goal here is to spot-check that optional deps work as expected,
+not to run an exhaustive set of tests with each combination of deps.
+"""
+
+
+def check_requires_no_opts():
+    """run some checks which should not require any optional dependencies"""
+    import uxarray as ux
+
+    uxds = ux.tutorial.open_dataset("quad-hexagon")
+    uxds.compute()
+
+
+def check_requires_only_viz():
+    """run some checks which should require viz optional dependencies,
+    but not any other optional dependencies.
+    """
+    import uxarray as ux
+
+    arr = ux.tutorial.open_dataset("quad-hexagon")["t2m"]
+    plot_obj = arr.plot.points()  # points() doesn't need geo projection details.
+
+    # actually try to render the plot, too:
+    import holoviews as hv
+
+    renderer = hv.renderer("matplotlib")
+    renderer.get_plot(plot_obj)
+
+
+def check_requires_only_geo():
+    """run some checks which should require geo optional dependencies,
+    but not any other optional dependencies.
+    """
+    import uxarray as ux
+
+    arr = ux.tutorial.open_dataset("quad-hexagon")["t2m"]
+    arr.to_geodataframe()
+
+    ux.Grid.from_healpix(zoom=1)
+
+
+def check_requires_viz_and_geo():
+    """run some checks which should require both viz and geo optional dependencies,
+    but not any other optional dependencies.
+    """
+    import uxarray as ux
+
+    arr = ux.tutorial.open_dataset("quad-hexagon")["t2m"]
+    plot_obj = arr.plot.polygons()  # polygons() uses geo projection details.
+
+    # actually try to render the plot, too:
+    import holoviews as hv
+
+    renderer = hv.renderer("matplotlib")
+    renderer.get_plot(plot_obj)

test_optional_deps/test_installed_with_geo.py

@@ -0,0 +1,35 @@
+"""
+Purpose: test expected behaviors when installed with only geo optional dependency.
+Tests should all pass if and only if installed accordingly, i.e. something like:
+    pip install ".[geo]"
+"""
+
+import pytest
+from _optional_deps_helpers import (
+    check_requires_no_opts,
+    check_requires_only_geo,
+    check_requires_only_viz,
+    check_requires_viz_and_geo,
+)
+
+
+def test_check_requires_no_opts():
+    """ensure success for checks which should not require any optional dependencies"""
+    check_requires_no_opts()
+
+
+def test_check_requires_only_viz():
+    """ensure failure for checks which should require viz optional dependencies"""
+    with pytest.raises(ImportError, match=r'pip install "uxarray\[viz\]"'):
+        check_requires_only_viz()
+
+
+def test_check_requires_only_geo():
+    """ensure success for checks which should require geo optional dependencies"""
+    check_requires_only_geo()
+
+
+def test_check_requires_viz_and_geo():
+    """ensure failure for checks which should require both viz and geo optional dependencies"""
+    with pytest.raises(ImportError, match=r'pip install "uxarray\[viz\]"'):
+        check_requires_viz_and_geo()

test_optional_deps/test_installed_with_no_opts.py

@@ -0,0 +1,38 @@
+"""
+Purpose: test expected behaviors when installed without any optional dependencies.
+Tests should all pass if and only if installed accordingly, i.e. something like:
+    pip install "."
+"""
+
+import pytest
+from _optional_deps_helpers import (
+    check_requires_no_opts,
+    check_requires_only_geo,
+    check_requires_only_viz,
+    check_requires_viz_and_geo,
+)
+
+
+def test_check_requires_no_opts():
+    """ensure success for checks which should not require any optional dependencies"""
+    check_requires_no_opts()
+
+
+def test_check_requires_only_viz():
+    """ensure failure for checks which should require viz optional dependencies"""
+    with pytest.raises(ImportError, match=r'pip install "uxarray\[viz\]"'):
+        check_requires_only_viz()
+
+
+def test_check_requires_only_geo():
+    """ensure failure for checks which should require geo optional dependencies"""
+    with pytest.raises(ImportError, match=r'pip install "uxarray\[geo\]"'):
+        check_requires_only_geo()
+
+
+def test_check_requires_viz_and_geo():
+    """ensure failure for checks which should require both viz and geo optional dependencies"""
+    with pytest.raises(ImportError):
+        # ^no match "uxarray[geo,viz]" here; might crash in a viz-only or a geo-only method,
+        # even though the check itself ultimately requires both viz and geo.
+        check_requires_viz_and_geo()

test_optional_deps/test_installed_with_viz.py

@@ -0,0 +1,35 @@
+"""
+Purpose: test expected behaviors when installed with only viz optional dependency.
+Tests should all pass if and only if installed accordingly, i.e. something like:
+    pip install ".[viz]"
+"""
+
+import pytest
+from _optional_deps_helpers import (
+    check_requires_no_opts,
+    check_requires_only_geo,
+    check_requires_only_viz,
+    check_requires_viz_and_geo,
+)
+
+
+def test_check_requires_no_opts():
+    """ensure success for checks which should not require any optional dependencies"""
+    check_requires_no_opts()
+
+
+def test_check_requires_only_viz():
+    """ensure success for checks which should require viz optional dependencies"""
+    check_requires_only_viz()
+
+
+def test_check_requires_only_geo():
+    """ensure failure for checks which should require geo optional dependencies"""
+    with pytest.raises(ImportError, match=r'pip install "uxarray\[geo\]"'):
+        check_requires_only_geo()
+
+
+def test_check_requires_viz_and_geo():
+    """ensure failure for checks which should require both viz and geo optional dependencies"""
+    with pytest.raises(ImportError, match=r'pip install "uxarray\[geo\]"'):
+        check_requires_viz_and_geo()

test_optional_deps/test_installed_with_viz_and_geo.py

@@ -0,0 +1,32 @@
+"""
+Purpose: test expected behaviors when installed with geo and viz optional dependencies.
+Tests should all pass if and only if installed accordingly, i.e. something like:
+    pip install ".[geo,viz]"
+"""
+
+from _optional_deps_helpers import (
+    check_requires_no_opts,
+    check_requires_only_geo,
+    check_requires_only_viz,
+    check_requires_viz_and_geo,
+)
+
+
+def test_check_requires_no_opts():
+    """ensure success for checks which should not require any optional dependencies"""
+    check_requires_no_opts()
+
+
+def test_check_requires_only_viz():
+    """ensure success for checks which should require viz optional dependencies"""
+    check_requires_only_viz()
+
+
+def test_check_requires_only_geo():
+    """ensure success for checks which should require geo optional dependencies"""
+    check_requires_only_geo()
+
+
+def test_check_requires_viz_and_geo():
+    """ensure success for checks which should require both viz and geo optional dependencies"""
+    check_requires_viz_and_geo()

uxarray/core/dataarray.py

@@ -39,6 +39,7 @@
 from uxarray.plot.accessor import UxDataArrayPlotAccessor
 from uxarray.remap.accessor import RemapAccessor
 from uxarray.subset import DataArraySubsetAccessor
+from uxarray.utils.imports import _raise_hint_if_optional_deps_missing
 
 if TYPE_CHECKING:
     import cartopy.crs as ccrs
@@ -473,6 +474,7 @@ def to_raster(
         >>> ax.imshow(raster, origin="lower", extent=ax.get_xlim() + ax.get_ylim())
 
         """
+        _raise_hint_if_optional_deps_missing("cartopy")
         from cartopy.mpl.geoaxes import GeoAxes
 
         from uxarray.constants import INT_DTYPE
@@ -517,6 +519,7 @@ def _is_default_extent() -> bool:
 
             if _is_default_extent():
                 try:
+                    _raise_hint_if_optional_deps_missing("cartopy")
                     import cartopy.crs as ccrs
 
                     lon_min = float(self.uxgrid.node_lon.min(skipna=True).values)

uxarray/cross_sections/sample.py

@@ -1,6 +1,8 @@
 import numpy as np
 from numba import njit, prange
 
+from uxarray.utils.imports import _raise_hint_if_optional_deps_missing
+
 
 @njit(parallel=True)
 def _fill_numba(flat_orig, face_idx, n_face, n_steps):
@@ -16,6 +18,7 @@ def _fill_numba(flat_orig, face_idx, n_face, n_steps):
 def sample_geodesic(
     start: tuple[float, float], end: tuple[float, float], steps: int
 ) -> tuple[np.ndarray, np.ndarray]:
+    _raise_hint_if_optional_deps_missing("pyproj")
     from pyproj import Geod
 
     lon0, lat0 = start

uxarray/errors.py

@@ -38,3 +38,10 @@ class GridsMismatchError(ValueError):
 
 class YacNotAvailableError(RuntimeError):
     """Raised when the YAC backend is requested but unavailable."""
+
+
+# # # ----- Miscellaneous Errors ----- # # #
+
+
+class OptionalDependencyNotFoundError(ModuleNotFoundError):
+    """indicates functionality relies on a not-yet-installed optional dependency."""

uxarray/grid/geometry.py

@@ -15,6 +15,7 @@
 )
 from uxarray.grid.point_in_face import _face_contains_point
 from uxarray.grid.utils import _get_cartesian_face_edge_nodes
+from uxarray.utils.imports import _raise_hint_if_optional_deps_missing
 
 POLE_POINTS_XYZ = {
     "North": np.array([0.0, 0.0, 1.0]),
@@ -116,6 +117,7 @@ def _build_polygon_shells(
 ):
     """Builds an array of polygon shells, which can be used with Shapely to
     construct polygons."""
+    _raise_hint_if_optional_deps_missing("cartopy")
     import cartopy.crs as ccrs
 
     closed_face_nodes = _pad_closed_face_nodes(
@@ -145,6 +147,7 @@ def _correct_central_longitude(node_lon, node_lat, projection):
     """Shifts the central longitude of an unstructured grid, which moves the
     antimeridian when visualizing, which is used when projections have a
     central longitude other than 0.0."""
+    _raise_hint_if_optional_deps_missing("cartopy")
     import cartopy.crs as ccrs
 
     if projection:
@@ -169,6 +172,7 @@ def _correct_central_longitude(node_lon, node_lat, projection):
 def _grid_to_polygon_geodataframe(grid, periodic_elements, projection, project, engine):
     """Converts the faces of a ``Grid`` into a ``spatialpandas.GeoDataFrame``
     or ``geopandas.GeoDataFrame`` with a geometry column of polygons."""
+    _raise_hint_if_optional_deps_missing("geopandas", "spatialpandas")
     import geopandas
     import shapely
     import spatialpandas
@@ -260,6 +264,7 @@ def _build_geodataframe_without_antimeridian(
     """Builds a ``spatialpandas.GeoDataFrame`` or
     ``geopandas.GeoDataFrame``excluding any faces that cross the
     antimeridian."""
+    _raise_hint_if_optional_deps_missing("geopandas", "spatialpandas")
     import geopandas
     import shapely
     import spatialpandas
@@ -296,6 +301,7 @@ def _build_geodataframe_with_antimeridian(
 ):
     """Builds a ``spatialpandas.GeoDataFrame`` or ``geopandas.GeoDataFrame``
     including any faces that cross the antimeridian."""
+    _raise_hint_if_optional_deps_missing("geopandas", "spatialpandas")
     import geopandas
     import spatialpandas
     from spatialpandas.geometry import MultiPolygonArray
@@ -441,6 +447,7 @@ def _grid_to_matplotlib_polycollection(
     grid, periodic_elements, projection=None, **kwargs
 ):
     """Constructs and returns a ``matplotlib.collections.PolyCollection``"""
+    _raise_hint_if_optional_deps_missing("cartopy", "matplotlib")
     import cartopy.crs as ccrs
     from matplotlib.collections import PolyCollection
 
@@ -647,6 +654,7 @@ def _grid_to_matplotlib_linecollection(
     grid, periodic_elements, projection=None, **kwargs
 ):
     """Constructs and returns a ``matplotlib.collections.LineCollection``"""
+    _raise_hint_if_optional_deps_missing("cartopy", "matplotlib")
     import cartopy.crs as ccrs
     from matplotlib.collections import LineCollection
 

uxarray/grid/grid.py

@@ -100,6 +100,7 @@
 from uxarray.io.utils import _parse_grid_type
 from uxarray.plot.accessor import GridPlotAccessor
 from uxarray.subset import GridSubsetAccessor
+from uxarray.utils.imports import _raise_hint_if_optional_deps_missing
 
 if TYPE_CHECKING:
     import cartopy.crs as ccrs
@@ -2296,7 +2297,7 @@ def to_geodataframe(
         gdf : spatialpandas.GeoDataFrame or geopandas.GeoDataFrame
             The output ``GeoDataFrame`` with a filled out "geometry" column of polygons.
         """
-
+        _raise_hint_if_optional_deps_missing("spatialpandas")
         from spatialpandas import GeoDataFrame
 
         if engine not in ["spatialpandas", "geopandas"]: