xclim.testing package

Helpers for testing xclim.

Submodules

xclim.testing.conftest module

Specialized setup for running xclim doctests.

xclim.testing.conftest.doctest_setup(xdoctest_namespace, nimbus, worker_id, open_dataset)[source]

Gather testing data on doctest run.

Return type:

None

xclim.testing.conftest.is_matplotlib_installed(xdoctest_namespace)[source]

Skip tests that require matplotlib if it is not installed.

Return type:

None

xclim.testing.conftest.nimbus(threadsafe_data_dir, worker_id)[source]

Return a nimbus object for the test data.

Returns:

nimbus – An preconfigured pooch object.

xclim.testing.conftest.open_dataset(threadsafe_data_dir, worker_id)[source]

Return a function that opens a dataset from the test data.

Returns:

function – A function that opens a dataset from the test data.

xclim.testing.conftest.threadsafe_data_dir(tmp_path_factory)[source]

Return a threadsafe temporary directory for storing testing data.

Yields:

Path – The path to the temporary directory.

xclim.testing.helpers module

Module for loading testing data.

xclim.testing.helpers.add_doctest_filepaths()[source]

Overload some libraries directly into the xdoctest namespace.

Return type:

dict[str, Any]

Returns:

dict[str, Any] – A dictionary of xdoctest namespace objects.

xclim.testing.helpers.add_ensemble_dataset_objects()[source]

Create a dictionary of xclim ensemble-related datasets to be patched into the xdoctest namespace.

Return type:

dict[str, list[str]]

Returns:

dict[str, list[str]] – A dictionary of xclim ensemble-related datasets.

xclim.testing.helpers.add_example_file_paths()[source]

Create a dictionary of doctest-relevant datasets to be patched into the xdoctest namespace.

Return type:

dict[str, str | list[DataArray]]

Returns:

dict of str or dict of list of xr.DataArray – A dictionary of doctest-relevant datasets.

xclim.testing.helpers.assert_lazy = <dask.callbacks.Callback object>

Context manager that raises an AssertionError if any dask computation is triggered.

xclim.testing.helpers.generate_atmos(nimbus)[source]

Create the atmosds synthetic testing dataset.

Parameters:

nimbus (pooch.Pooch) – The Pooch object to use for downloading the data.

Return type:

dict[str, DataArray]

Returns:

dict[str, xr.DataArray] – A dictionary of xarray DataArrays.

xclim.testing.helpers.test_timeseries(values, variable, start='2000-07-01', units=None, freq='D', as_dataset=False, cftime=None, calendar=None)[source]

Create a generic timeseries object based on pre-defined dictionaries of existing variables.

Parameters:

  • values (np.ndarray) – The values of the DataArray.

  • variable (str) – The name of the DataArray.

  • start (str) – The start date of the time dimension. Default is “2000-07-01”.

  • units (str or None) – The units of the DataArray. Default is None.

  • freq (str) – The frequency of the time dimension. Default is daily/”D”.

  • as_dataset (bool) – Whether to return a Dataset or a DataArray. Default is False.

  • cftime (bool) – Whether to use cftime or not. Default is None, which uses cftime only for non-standard calendars.

  • calendar (str or None) – Whether to use a calendar. If a calendar is provided, cftime is used.

Return type:

DataArray | Dataset

Returns:

xr.DataArray or xr.Dataset – A DataArray or Dataset with time, lon and lat dimensions.

xclim.testing.utils module

Testing and Tutorial Utilities’ Module

xclim.testing.utils.TESTDATA_BRANCH = 'v2025.4.29'

Sets the branch of the testing data repository to use when fetching datasets.

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XCLIM_TESTDATA_BRANCH="my_testing_branch"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_BRANCH="my_testing_branch" pytest
xclim.testing.utils.TESTDATA_CACHE_DIR = PosixPath('/home/docs/.cache/xclim-testdata')

Sets the directory to store the testing datasets.

If not set, the default location will be used (based on platformdirs, see pooch.os_cache()).

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XCLIM_TESTDATA_CACHE_DIR="/path/to/my/data"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_CACHE_DIR="/path/to/my/data" pytest
xclim.testing.utils.TESTDATA_REPO_URL = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/'

Sets the URL of the testing data repository to use when fetching datasets.

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XCLIM_TESTDATA_REPO_URL="https://github.com/my_username/xclim-testdata"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_REPO_URL="https://github.com/my_username/xclim-testdata" pytest
xclim.testing.utils.audit_url(url, context=None)[source]

Check if the URL is well-formed.

Parameters:

  • url (str) – The URL to check.

  • context (str, optional) – Additional context to include in the error message. Default is None.

Return type:

str

Returns:

str – The URL if it is well-formed.

Raises:

URLError – If the URL is not well-formed.

xclim.testing.utils.default_testdata_cache = PosixPath('/home/docs/.cache/xclim-testdata')

Default location for the testing data cache.

xclim.testing.utils.default_testdata_repo_url = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/'

Default URL of the testing data repository to use when fetching datasets.

xclim.testing.utils.default_testdata_version = 'v2025.4.29'

Default version of the testing data to use when fetching datasets.

xclim.testing.utils.gather_testing_data(worker_cache_dir, worker_id, _cache_dir=PosixPath('/home/docs/.cache/xclim-testdata'))[source]

Gather testing data across workers.

Parameters:

  • worker_cache_dir (str or Path) – The directory to store the testing data.

  • worker_id (str) – The worker ID.

  • _cache_dir (str or Path, optional) – The directory to store the testing data. Default is None.

Raises:

  • ValueError – If the cache directory is not set.

  • FileNotFoundError – If the testing data is not found.

Return type:

None

xclim.testing.utils.list_input_variables(submodules=None, realms=None)[source]

List all possible variables names used in xclim’s indicators.

Made for development purposes. Parses all indicator parameters with the xclim.core.utils.InputKind.VARIABLE or OPTIONAL_VARIABLE kinds.

Parameters:

  • submodules (str, optional) – Restrict the output to indicators of a list of submodules only. Default None, which parses all indicators.

  • realms (Sequence of str, optional) – Restrict the output to indicators of a list of realms only. Default None, which parses all indicators.

Return type:

dict

Returns:

dict – A mapping from variable name to indicator class.

xclim.testing.utils.nimbus(repo='https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/', branch='v2025.4.29', cache_dir=PosixPath('/home/docs/.cache/xclim-testdata'), allow_updates=True)[source]

Pooch registry instance for xclim test data.

Parameters:

  • repo (str) – URL of the repository to use when fetching testing datasets.

  • branch (str) – Branch of repository to use when fetching testing datasets.

  • cache_dir (str or Path) – The path to the directory where the data files are stored.

  • allow_updates (bool) – If True, allow updates to the data files. Default is True.

Returns:

pooch.Pooch – The Pooch instance for accessing the xclim testing data.

Notes

There are three environment variables that can be used to control the behaviour of this registry:

  • XCLIM_TESTDATA_CACHE_DIR: If this environment variable is set, it will be used as the base directory to store the data files. The directory should be an absolute path (i.e., it should start with /). Otherwise, the default location will be used (based on platformdirs, see pooch.os_cache()).

  • XCLIM_TESTDATA_REPO_URL: If this environment variable is set, it will be used as the URL of the repository to use when fetching datasets. Otherwise, the default repository will be used.

  • XCLIM_TESTDATA_BRANCH: If this environment variable is set, it will be used as the branch of the repository to use when fetching datasets. Otherwise, the default branch will be used.

Examples

Using the registry to download a file:

import xarray as xr
from xclim.testing.helpers import nimbus

example_file = nimbus().fetch("example.nc")
data = xr.open_dataset(example_file)
xclim.testing.utils.open_dataset(name, nimbus_kwargs=None, **xr_kwargs)[source]

Convenience function to open a dataset from the xclim testing data using the nimbus class.

This is a thin wrapper around the nimbus class to make it easier to open xclim testing datasets.

Parameters:

  • name (str) – Name of the file containing the dataset.

  • nimbus_kwargs (dict) – Keyword arguments passed to the nimbus function.

  • **xr_kwargs (Any) – Keyword arguments passed to xarray.open_dataset.

Return type:

Dataset

Returns:

xarray.Dataset – The dataset.

See also

xarray.open_dataset

Open and read a dataset from a file or file-like object.

nimbus

Pooch wrapper for accessing the xclim testing data.

Notes

As of xclim v0.57.0, this function no longer supports the dap_url parameter. For OPeNDAP datasets, use xarray.open_dataset directly using the OPeNDAP URL with an appropriate backend installed (netCDF4, pydap, etc.).

xclim.testing.utils.populate_testing_data(temp_folder=None, repo='https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/', branch='v2025.4.29', local_cache=PosixPath('/home/docs/.cache/xclim-testdata'))[source]

Populate the local cache with the testing data.

Parameters:

  • temp_folder (Path, optional) – Path to a temporary folder to use as the local cache. If not provided, the default location will be used.

  • repo (str, optional) – URL of the repository to use when fetching testing datasets.

  • branch (str, optional) – Branch of xclim-testdata to use when fetching testing datasets.

  • local_cache (Path) – The path to the local cache. Defaults to the location set by the platformdirs library. The testing data will be downloaded to this local cache.

Return type:

None

xclim.testing.utils.publish_release_notes(style='md', file=None, changes=None)[source]

Format release notes in Markdown or ReStructuredText.

Parameters:

  • style ({“rst”, “md”}) – Use ReStructuredText formatting or Markdown. Default: Markdown.

  • file ({os.PathLike, StringIO, TextIO}, optional) – If provided, prints to the given file-like object. Otherwise, returns a string.

  • changes (str or os.PathLike[str], optional) – If provided, manually points to the file where the changelog can be found. Assumes a relative path otherwise.

Return type:

str | None

Returns:

str, optional – If file not provided, the formatted release notes.

Notes

This function is used solely for development and packaging purposes.

xclim.testing.utils.run_doctests()[source]

Run the doctests for the module.

xclim.testing.utils.show_versions(file=None, deps=None)[source]

Print the versions of xclim and its dependencies.

Parameters:

  • file ({os.PathLike, StringIO, TextIO}, optional) – If provided, prints to the given file-like object. Otherwise, returns a string.

  • deps (list of str, optional) – A list of dependencies to gather and print version information from. Otherwise, prints xclim dependencies.

Return type:

str | None

Returns:

str or None – If file not provided, the versions of xclim and its dependencies.

xclim.testing.utils.testing_setup_warnings()[source]

Warn users about potential incompatibilities between xclim and xclim-testdata versions.