Move navy_land.nc to resources dir and move _get_resource_path to utils.py

- Update unit tests for `_get_resource_path()` to cover all cases
- Refactor `_get_resource_path` for maintainability and readability -- remove unnecessary args, simplify logic, remove ModuleNotFoundError
- Update docstring of `pcmdi_land_sea_mask()` with source to `navy_land.nc`
- Update `pcmdi_land_sea_mask()` to not decode time for navy_land.nc to prevent logger warning since it has no time axis
- Update `.gitignore` to noy ignore `xcdat/resources` dir
- Update `pyproject.toml` `tools.setuptools.package-data`

Author: tomvothecoder

.gitignore

@@ -113,6 +113,9 @@ ENV/
 # Input data
 *.nc
 
+# But keep any netCDF files in the resources directory
+!xcdat/resources/*.nc
+
 # Anaconda
 conda-build/
 

pyproject.toml

@@ -61,7 +61,7 @@ dev = ["types-python-dateutil", "pre-commit", "ruff", "mypy"]
 include = ["xcdat", "xcdat.*"]
 
 [tool.setuptools.package-data]
-"xcdat" = ["*.nc"]
+"xcdat" = ["resources/navy_land.nc"]
 
 [tool.setuptools.dynamic]
 version = { attr = "xcdat.__version__" }

tests/test_mask.py

@@ -1,4 +1,3 @@
-import re
 import sys
 from unittest import mock
 
@@ -344,48 +343,6 @@ def test_pcmdi_land_sea_mask_multiple_iterations(_improve_mask, ds):
     xr.testing.assert_equal(output, expected)
 
 
-def test_get_resource_path(monkeypatch, tmp_path):
-    mock_file = tmp_path / "navy_land.nc"
-    mock_file.touch()
-
-    mock_as_file = mock.MagicMock()
-    mock_as_file.return_value.__enter__.return_value = mock_file
-
-    monkeypatch.setattr(mask.resources, "as_file", mock_as_file)
-
-    path = mask._get_resource_path("navy_land.nc")
-
-    assert path == mock_file
-
-
-def test_get_resource_path_fallback_from_exception(monkeypatch, tmp_path):
-    mock_file = tmp_path / "xcdat" / "navy_land.nc"
-    mock_file.parent.mkdir(parents=True, exist_ok=True)
-    mock_file.touch()
-
-    mock_as_file = mock.MagicMock()
-    mock_as_file.side_effect = FileNotFoundError("Resource not found")
-
-    monkeypatch.setattr(mask.resources, "as_file", mock_as_file)
-
-    path = mask._get_resource_path("navy_land.nc", tmp_path)
-
-    assert re.match(r".*xcdat/navy_land.nc", str(path))
-
-
-def test_get_resource_path_fallback_missing(monkeypatch, tmp_path):
-    mock_as_file = mock.MagicMock()
-    mock_as_file.side_effect = FileNotFoundError("Resource not found")
-
-    monkeypatch.setattr(mask.resources, "as_file", mock_as_file)
-
-    with pytest.raises(
-        RuntimeError,
-        match=r"Resource file 'navy_land.nc' not found in package or at .*",
-    ):
-        mask._get_resource_path("navy_land.nc", tmp_path)
-
-
 def test_is_circular():
     # Circular
     lon = xr.DataArray(data=np.array([0, 90, 180, 270]), dims=["lon"])

tests/test_utils.py

@@ -1,7 +1,16 @@
+from importlib import resources
+from pathlib import Path
+from unittest import mock
+
 import pytest
 import xarray as xr
 
-from xcdat.utils import _validate_min_weight, compare_datasets, str_to_bool
+from xcdat.utils import (
+    _get_resource_path,
+    _validate_min_weight,
+    compare_datasets,
+    str_to_bool,
+)
 
 
 class TestCompareDatasets:
@@ -123,3 +132,48 @@ def test_returns_valid_min_weight(self):
         result = _validate_min_weight(1)
 
         assert result == 1
+
+
+class TestGetResourcePath:
+    def test_get_resource_path_local(self):
+        # Mock the resources.files to simulate the local file structure
+        with mock.patch("xcdat.utils.resources.files") as mock_files:
+            mock_files.return_value = mock.Mock()
+            mock_files.return_value.joinpath.return_value = (
+                Path.cwd() / "xcdat" / "resources" / "navy_land.nc"
+            )
+            expected_path = mock_files.return_value.joinpath(
+                "resources", "navy_land.nc"
+            )
+
+            path = _get_resource_path("navy_land.nc")
+
+            assert path == expected_path
+
+    @pytest.mark.skipif(
+        not pytest.importorskip("xcdat", reason="xcdat is not installed"),
+        reason="xcdat is not installed",
+    )
+    def test_get_resource_path(self):
+        # Locate the actual resources directory in the xcdat package
+        resource_files = resources.files("xcdat")
+        expected_path = resource_files / "resources" / "navy_land.nc"
+
+        path = _get_resource_path("navy_land.nc")
+
+        assert path == expected_path
+
+    def test_raises_runtime_error_if_file_not_found(self):
+        with mock.patch("xcdat.utils.resources.files") as mock_files:
+            mock_files.return_value = mock.Mock()
+            mock_files.return_value.joinpath.return_value = Path(
+                "/nonexistent/path/navy_land.nc"
+            )
+            with mock.patch(
+                "xcdat.utils.resources.as_file", side_effect=FileNotFoundError
+            ):
+                with pytest.raises(
+                    RuntimeError,
+                    match="Resource file 'navy_land.nc' not found in package",
+                ):
+                    _get_resource_path("navy_land.nc")

xcdat/mask.py

@@ -1,5 +1,3 @@
-from importlib import resources
-from pathlib import Path
 from typing import Any, Callable
 
 import numpy as np
@@ -11,6 +9,7 @@
 from xcdat.axis import get_dim_coords
 from xcdat.regridder.accessor import obj_to_grid_ds
 from xcdat.regridder.grid import create_grid
+from xcdat.utils import _get_resource_path
 
 logger = _setup_custom_logger(__name__)
 
@@ -342,10 +341,12 @@ def pcmdi_land_sea_mask(
     source: xr.Dataset | None = None,
     source_data_var: str | None = None,
 ) -> xr.DataArray:
-    """Generate a land-sea mask using the PCMDI method.
+    """
+    Generate a land-sea mask using the PCMDI method.
 
-    This method uses a high-resolution land-sea mask and regrids it to the
-    resolution of the input DataArray. It then iteratively improves the mask.
+    This method uses a high-resolution land-sea mask and regrids it to the resolution
+    of the input DataArray. It then iteratively improves the mask based on specified
+    thresholds.
 
     Parameters
     ----------
@@ -356,18 +357,31 @@ def pcmdi_land_sea_mask(
     threshold2 : float, optional
         The second threshold for improving the mask, by default 0.3.
     source : xr.Dataset | None, optional
-        The Dataset containing the variable to use as the high resolution source.
+        A custom Dataset containing the variable to use as the high-resolution source.
+        If not provided, a default high-resolution land-sea mask is used.
     source_data_var : str | None, optional
-        Name of the variable in `source` to use as the high resolution source.
+        The name of the variable in `source` to use as the high-resolution source.
+        If `source` is not provided, this defaults to "sftlf".
 
     Returns
     -------
     xr.DataArray
-        The land-sea mask.
+        The generated land-sea mask.
+
+    Raises
+    ------
+    ValueError
+        If `source` is provided but `source_data_var` is None.
+
+    Notes
+    -----
+    By default, the `navy_land.nc` file is used as the high-resolution land-sea mask.
+    This file is sourced from the PCMDI (Program for Climate Model Diagnosis and
+    Intercomparison) Metrics Package. It is available at:
+    https://github.com/PCMDI/pcmdi_metrics/blob/main/share/data/navy_land.nc
 
     Examples
     --------
-
     Generate a land-sea mask using the PCMDI method:
 
     >>> import xcdat
@@ -376,12 +390,16 @@ def pcmdi_land_sea_mask(
 
     Generate a land-sea mask using the PCMDI method with custom thresholds:
 
-    >>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(ds["tas"], threshold1=0.3, threshold2=0.4)
+    >>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(
+    ...     ds["tas"], threshold1=0.3, threshold2=0.4
+    ... )
 
-    Generate a land-sea mask using the PCMDI method with a custom high resolution source:
+    Generate a land-sea mask using the PCMDI method with a custom high-res source:
 
-    >>> highres_ds = xcdata.open_dataset("/path/to/file")
-    >>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(ds["tas"], source=highres_ds, source_data_var="highres")
+    >>> highres_ds = xcdat.open_dataset("/path/to/file")
+    >>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(
+    ...     ds["tas"], source=highres_ds, source_data_var="highres"
+    ... )
     """
     if source is not None and source_data_var is None:
         raise ValueError(
@@ -391,9 +409,11 @@ def pcmdi_land_sea_mask(
     if source is None:
         source_data_var = "sftlf"
 
-        resource_path = str(_get_resource_path("navy_land.nc", Path.cwd()))
+        resource_path = str(_get_resource_path("navy_land.nc"))
 
-        source = open_dataset(resource_path)
+        # Turn off time decoding to prevent logger warning since this dataset
+        # does not have a time axis.
+        source = open_dataset(resource_path, decode_times=False)
 
     source_regrid = source.regridder.horizontal(
         source_data_var, obj_to_grid_ds(da), tool="regrid2"
@@ -435,44 +455,6 @@ def pcmdi_land_sea_mask(
     return mask[source_data_var]
 
 
-def _get_resource_path(filename: str, default_path: Path | None = None) -> Path:
-    """Get the path to a resource file.
-
-    Parameters
-    ----------
-    filename : str
-        The name of the resource file.
-
-    Returns
-    -------
-    Path
-        The path to the resource file.
-    """
-    if default_path is None:
-        default_path = Path.cwd()
-
-    resource_path: Path | None = None
-
-    try:
-        with resources.as_file(resources.files("xcdat").joinpath(filename)) as x:
-            resource_path = x
-    except (ModuleNotFoundError, FileNotFoundError) as e:
-        logger.warning(e)
-        resource_path = None
-
-    if resource_path and resource_path.exists():
-        return resource_path
-
-    resource_path = default_path / "xcdat" / filename
-
-    if not resource_path.exists():
-        raise RuntimeError(
-            f"Resource file {filename!r} not found in package or at {resource_path!s}."
-        )
-
-    return resource_path
-
-
 def _is_circular(lon: xr.DataArray, lon_bnds: xr.DataArray) -> bool:
     """Check if a longitude axis is circular.
 

xcdat/navy_land.nc renamed to xcdat/resources/navy_land.nc

@@ -1,9 +1,14 @@
-import importlib
 import json
+from importlib import import_module, resources
+from pathlib import Path
 
 import xarray as xr
 from dask.array.core import Array
 
+from xcdat._logger import _setup_custom_logger
+
+logger = _setup_custom_logger(__name__)
+
 
 def compare_datasets(ds1: xr.Dataset, ds2: xr.Dataset) -> dict[str, list[str]]:
     """Compares the keys and values of two datasets.
@@ -101,7 +106,7 @@ def _has_module(modname: str) -> bool:  # pragma: no cover
     bool
     """
     try:
-        importlib.import_module(modname)
+        import_module(modname)
         has = True
     except ImportError:
         has = False
@@ -188,3 +193,38 @@ def _validate_min_weight(min_weight: float | None) -> float:
         )
 
     return min_weight
+
+
+def _get_resource_path(filename: str) -> Path:
+    """Get the path to a resource file from within the package.
+
+    Parameters
+    ----------
+    filename : str
+        The name of the resource file.
+
+    Returns
+    -------
+    Path
+        The path to the resource file.
+
+    Raises
+    ------
+    RuntimeError
+        If the resource file is not found in the package.
+    """
+    try:
+        resource_files = resources.files("xcdat")
+        resource_path = resource_files.joinpath("resources", filename)
+
+        with resources.as_file(resource_path) as resolved_path:
+            if resolved_path.exists():
+                return resolved_path
+    except FileNotFoundError as e:
+        logger.warning(
+            f"File not found while locating resource {filename!r}. Error: {e}"
+        )
+
+    raise RuntimeError(
+        f"Resource file {filename!r} not found in package: {resource_path!s}."
+    )