ravenpy.testing package

RavenPy Testing Utilities

Submodules

ravenpy.testing.helpers module

ravenpy.testing.helpers.count_pixels(stats: dict, numeric_categories=False) → int

ravenpy.testing.helpers.make_bnds(params, delta)

Return low and high parameter bounds by subtracting and adding delta*params to params.

Parameters:

• params (sequence) – Parameters.

• delta (float [0,1]) – Relative delta to subtract and add to parameters.

Returns:

Low and high bounds for parameters.

Return type:

(tuple, tuple)

ravenpy.testing.helpers.synthetic_gr4j_inputs(path)

ravenpy.testing.utils module

Tools for searching for and acquiring test data.

ravenpy.testing.utils.TESTDATA_BRANCH = 'v2025.6.12'

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 RAVEN_TESTDATA_BRANCH="my_testing_branch"

or setting the variable at runtime:

$ env RAVEN_TESTDATA_BRANCH="my_testing_branch" pytest

ravenpy.testing.utils.TESTDATA_CACHE_DIR = PosixPath('/home/docs/.cache/raven-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 RAVEN_TESTDATA_CACHE_DIR="/path/to/my/data"

or setting the variable at runtime:

$ env RAVEN_TESTDATA_CACHE_DIR="/path/to/my/data" pytest

ravenpy.testing.utils.TESTDATA_REPO_URL = 'https://raw.githubusercontent.com/Ouranosinc/raven-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 RAVEN_TESTDATA_REPO_URL="https://github.com/my_username/raven-testdata"

or setting the variable at runtime:

$ env RAVEN_TESTDATA_REPO_URL="https://github.com/my_username/raven-testdata" pytest

ravenpy.testing.utils.audit_url(url: str, context: str | None = None) → str

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.

Returns:

The URL if it is well-formed.

Return type:

str

Raises:

URLError – If the URL is not well-formed.

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

Default location for the testing data cache.

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

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

ravenpy.testing.utils.default_testdata_version = 'v2025.6.12'

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

ravenpy.testing.utils.gather_testing_data(worker_cache_dir: str | PathLike[str] | Path, worker_id: str, _cache_dir: str | PathLike[str] | None = PosixPath('/home/docs/.cache/raven-testdata')) → None

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.

ravenpy.testing.utils.get_file(name: str, _yangtze_kwargs: dict[str, Path | str | bool] | None = None)

Convenience function to get a file from the RavenPy testing data using the yangtze class.

This is a thin wrapper around the yangtze class to make it easier to access RavenPy testing datasets.

Parameters:

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

• _yangtze_kwargs (dict) – Keyword arguments passed to the yangtze function.

Returns:

The path to the file.

Return type:

str

ravenpy.testing.utils.open_dataset(name: str, _yangtze_kwargs: dict[str, Path | str | bool] | None = None, **xr_kwargs: Any) → Dataset

Convenience function to open a dataset from the RavenPy testing data using the yangtze class.

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

Parameters:

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

• _yangtze_kwargs (dict) – Keyword arguments passed to the yangtze function.

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

Returns:

The dataset.

Return type:

xarray.Dataset

See also

xarray.open_dataset

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

yangtze

Pooch wrapper for accessing the RavenPy testing data.

ravenpy.testing.utils.populate_testing_data(temp_folder: Path | None = None, repo: str = 'https://raw.githubusercontent.com/Ouranosinc/raven-testdata/', branch: str = 'v2025.6.12', retry: int = 3, local_cache: Path = PosixPath('/home/docs/.cache/raven-testdata')) → None

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 raven-testdata to use when fetching testing datasets.

• retry (int) – Number of times to retry downloading the files in case of failure. Default: 3.

• 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.

ravenpy.testing.utils.show_versions(file: PathLike | StringIO | TextIO | None = None, deps: list | None = None) → str | None

Print the versions of RavenPy 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, optional) – A list of dependencies to gather and print version information from. Otherwise, print RavenPy dependencies.

Returns:

The formatted version information if file is not provided, otherwise None.

Return type:

str or None

ravenpy.testing.utils.testing_setup_warnings()

Warn users about potential incompatibilities between RavenPy and raven-testdata versions.

ravenpy.testing.utils.yangtze(repo: str = 'https://raw.githubusercontent.com/Ouranosinc/raven-testdata/', branch: str = 'v2025.6.12', cache_dir: str | Path | None = PosixPath('/home/docs/.cache/raven-testdata'), allow_updates: bool = True, force_download: bool = False)

Pooch registry instance for RavenPy 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 or None) – The path to the directory where the data files are stored. A valid cache_dir path is required.

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

• force_download (bool) – If True, force the download of the registry file even if it already exists.

Returns:

The Pooch instance for accessing the RavenPy testing data.

Return type:

pooch.Pooch

Notes

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

• RAVEN_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()).

• RAVEN_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.

• RAVEN_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 ravenpy.testing import yangtze

example_file = yangtze().fetch("example.nc")
data = xr.open_dataset(example_file)