diff --git a/pyproject.toml b/pyproject.toml index 1252f70a..f2da0e27 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -181,6 +181,22 @@ warn_unused_configs = true module = [] ignore_missing_imports = true +[tool.numpydoc_validation] +checks = [ + "all", # report on all checks, except the below + "ES01", + "EX01", + "GL01", + "SA01" +] +exclude = [ + # don't report on objects that match any of these regex + '\.undocumented_method$', + '\.__repr__$', + # any object starting with an underscore is a private object + '\._\w+' +] + [tool.pytest.ini_options] addopts = [ "--verbose", diff --git a/xhydro/cc.py b/xhydro/cc.py index faf92334..0723b93a 100644 --- a/xhydro/cc.py +++ b/xhydro/cc.py @@ -1,4 +1,5 @@ """Module to compute climate change statistics using xscen functions.""" +import xarray # Special imports from xscen from xscen import ( # FIXME: To be replaced with climatological_op once available @@ -17,8 +18,20 @@ # FIXME: To be deleted once climatological_op is available in xscen -def climatological_op(ds, **kwargs): - """Compute climatological operation. +def climatological_op(ds: xarray.Dataset, **kwargs: dict) -> xarray.Dataset: + r"""Compute climatological operation. + + Parameters + ---------- + ds : xarray.Dataset + Input dataset. + \*\*kwargs : dict + Keyword arguments passed to :py:func:`xscen.aggregate.climatological_mean`. + + Returns + ------- + xarray.Dataset + Output dataset. Notes ----- diff --git a/xhydro/indicators.py b/xhydro/indicators.py index 9d0a3b8f..455a657b 100644 --- a/xhydro/indicators.py +++ b/xhydro/indicators.py @@ -64,36 +64,37 @@ def get_yearly_op( missing_options: Optional[dict] = None, interpolate_na: bool = False, ) -> xr.Dataset: - """ - Compute yearly operations on a variable. + """Compute yearly operations on a variable. Parameters ---------- - ds: xr.Dataset + ds : xr.Dataset Dataset containing the variable to compute the operation on. - op: str + op : str Operation to compute. One of ["max", "min", "mean", "sum"]. - input_var: str + input_var : str Name of the input variable. Defaults to "streamflow". - window: int + window : int Size of the rolling window. A "mean" operation is performed on the rolling window before the call to xclim. This parameter cannot be used with the "sum" operation. - timeargs: dict, optional + timeargs : dict, optional Dictionary of time arguments for the operation. Keys are the name of the period that will be added to the results (e.g. "winter", "summer", "annual"). Values are up to two dictionaries, with both being optional. The first is {'freq': str}, where str is a frequency supported by xarray (e.g. "YS", "AS-JAN", "AS-DEC"). It needs to be a yearly frequency. Defaults to "AS-JAN". - The second is an indexer as supported by :py:func:`xclim.core.calendar.select_time`. Defaults to {}, which means the whole year. + The second is an indexer as supported by :py:func:`xclim.core.calendar.select_time`. + Defaults to {}, which means the whole year. See :py:func:`xclim.core.calendar.select_time` for more information. - Examples: {"winter": {"freq": "AS-DEC", "date_bounds": ['12-01', '02-28']}}, {"jan": {"freq": "YS", "month": 1}}, {"annual": {}}. - missing: str + Examples: {"winter": {"freq": "AS-DEC", "date_bounds": ["12-01", "02-28"]}}, {"jan": {"freq": "YS", "month": 1}}, {"annual": {}}. + missing : str How to handle missing values. One of "skip", "any", "at_least_n", "pct", "wmo". See :py:func:`xclim.core.missing` for more information. - missing_options: dict, optional + missing_options : dict, optional Dictionary of options for the missing values' method. See :py:func:`xclim.core.missing` for more information. - interpolate_na: bool - Whether to interpolate missing values before computing the operation. Only used with the "sum" operation. Defaults to False. + interpolate_na : bool + Whether to interpolate missing values before computing the operation. Only used with the "sum" operation. + Defaults to False. Returns ------- @@ -105,7 +106,6 @@ def get_yearly_op( ----- If you want to perform a frequency analysis on a frequency that is finer than annual, simply use multiple timeargs (e.g. 1 per month) to create multiple distinct variables. - """ missing_options = missing_options or {} timeargs = timeargs or {"annual": {}} @@ -174,7 +174,8 @@ def get_yearly_op( and freq != "AS-DEC" ): warnings.warn( - "The frequency is not AS-DEC, but the season indexer includes DJF. This will lead to misleading results." + "The frequency is not AS-DEC, but the season indexer includes DJF. " + "This will lead to misleading results." ) elif ( "doy_bounds" in indexer.keys() diff --git a/xhydro/testing/helpers.py b/xhydro/testing/helpers.py index 7ae68913..287243df 100644 --- a/xhydro/testing/helpers.py +++ b/xhydro/testing/helpers.py @@ -98,7 +98,18 @@ def generate_registry( def load_registry(file: Optional[Union[str, Path]] = None) -> dict[str, str]: - """Load the registry file for the test data.""" + """Load the registry file for the test data. + + Parameters + ---------- + file : str or Path, optional + Path to the registry file. If not provided, the registry file found within the package data will be used. + + Returns + ------- + dict + Dictionary of filenames and hashes. + """ # Get registry file from package_data if file is None: registry_file = ilr.files("xhydro").joinpath("testing/registry.txt") @@ -157,8 +168,25 @@ def populate_testing_data( temp_folder: Optional[Path] = None, branch: str = TESTDATA_BRANCH, _local_cache: Path = _default_cache_dir, -): - """Populate the local cache with the testing data.""" +) -> None: + """Populate the local cache with the testing data. + + Parameters + ---------- + registry : str or Path, optional + Path to the registry file. If not provided, the registry file from package_data will be used. + temp_folder : Path, optional + Path to a temporary folder to use as the local cache. If not provided, the default location will be used. + branch : str, optional + Branch of hydrologie/xhydro-testdata to use when fetching testing datasets. + _local_cache : Path, optional + Path to the local cache. Defaults to the default location. + + Returns + ------- + None + The testing data will be downloaded to the local cache. + """ # Get registry file from package_data or provided path registry = load_registry(registry) diff --git a/xhydro/testing/utils.py b/xhydro/testing/utils.py index dde7fd41..ff52d2f4 100644 --- a/xhydro/testing/utils.py +++ b/xhydro/testing/utils.py @@ -30,7 +30,8 @@ def publish_release_notes( Returns ------- - str, optional + str or None + Formatted release notes as a string, if `file` is not provided. Notes -----