xhydro.testing package¶

Testing utilities and helper functions.

Submodules¶

xhydro.testing.helpers module¶

Helper functions for testing data management.

xhydro.testing.helpers.TESTDATA_BRANCH = 'v2025.1.14'¶

Sets the branch of hydrologie/xhydro-testdata to use when fetching testing datasets.

Notes¶

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

$ export XHYDRO_TESTDATA_BRANCH="my_testing_branch"

or setting the variable at runtime:

$ env XHYDRO_TESTDATA_BRANCH="my_testing_branch" pytest

xhydro.testing.helpers.TESTDATA_CACHE_DIR = PosixPath('/home/docs/.cache/xhydro-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 XHYDRO_TESTDATA_CACHE_DIR="/path/to/my/data"

or setting the variable at runtime:

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

xhydro.testing.helpers.TESTDATA_REPO_URL = 'https://raw.githubusercontent.com/hydrologie/xhydro-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 XHYDRO_TESTDATA_REPO_URL="https://github.com/my_username/xhydro-testdata/"

or setting the variable at runtime:

$ env XHYDRO_TESTDATA_REPO_URL="https://github.com/my_username/xhydro-testdata/" pytest

xhydro.testing.helpers.audit_url(url: str, context: str | None = None) → str[source]¶

Check if the URL is well-formed.

Parameters¶

urlstr: The URL to check.
contextstr, optional: Additional context to include in the error message.

Returns¶

str: The URL if it is well-formed.

Raises¶

URLError: If the URL is not well-formed.

xhydro.testing.helpers.default_testdata_cache = PosixPath('/home/docs/.cache/xhydro-testdata')¶: Default location for the testing data cache.

xhydro.testing.helpers.default_testdata_repo_url = 'https://raw.githubusercontent.com/hydrologie/xhydro-testdata/'¶: Default URL of the testing data repository to use when fetching datasets.

xhydro.testing.helpers.default_testdata_version = 'v2025.1.14'¶: Default version of the testing data to use when fetching datasets.

xhydro.testing.helpers.deveraux(repo: str = 'https://raw.githubusercontent.com/hydrologie/xhydro-testdata/', branch: str = 'v2025.1.14', cache_dir: str | Path = PosixPath('/home/docs/.cache/xhydro-testdata'), data_updates: bool = True)[source]¶

Pooch registry instance for xhydro test data.

Parameters¶

repostr: URL of the repository to use when fetching testing datasets.
branchstr: Branch of repository to use when fetching testing datasets.
cache_dirstr or Path: The path to the directory where the data files are stored.
data_updatesbool: If True, allow updates to the data files. Default is True.

Returns¶

pooch.Pooch: The Pooch instance for accessing the xhydro testing data.

Notes¶

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

XHYDRO_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()).
XHYDRO_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.
XHYDRO_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 xhydro.testing.helpers import devereaux

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

xhydro.testing.helpers.load_registry(branch: str = 'v2025.1.14', repo: str = 'https://raw.githubusercontent.com/hydrologie/xhydro-testdata/') → dict[str, str][source]¶

Load the registry file for the test data.

Parameters¶

branchstr: Branch of the repository to use when fetching testing datasets.
repostr: URL of the repository to use when fetching testing datasets.

Returns¶

dict: Dictionary of filenames and hashes.

xhydro.testing.helpers.populate_testing_data(temp_folder: Path | None = None, repo: str = 'https://raw.githubusercontent.com/hydrologie/xhydro-testdata/', branch: str = 'v2025.1.14', local_cache: Path = PosixPath('/home/docs/.cache/xhydro-testdata')) → None[source]¶

Populate the local cache with the testing data.

Parameters¶

temp_folderPath, optional: Path to a temporary folder to use as the local cache. If not provided, the default location will be used.
repostr, optional: URL of the repository to use when fetching testing datasets.
branchstr, optional: Branch of xhydro-testdata to use when fetching testing datasets.
local_cachePath: 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.

xhydro.testing.utils module¶

Utilities for testing and releasing xhydro.

xhydro.testing.utils.fake_hydrotel_project(project_dir: str | PathLike, *, meteo: bool | Dataset = False, debit_aval: bool | Dataset = False)[source]¶

Create a fake Hydrotel project in the given directory.

Parameters¶

project_dirstr or os.PathLike: Directory where the project will be created.
meteobool or xr.Dataset: Fake meteo timeseries. If True, a 2-year timeseries is created. Alternatively, provide a Dataset. Leave as False to create a fake file.
debit_avalbool or xr.Dataset: Fake debit_aval timeseries. If True, a 2-year timeseries is created. Alternatively, provide a Dataset. Leave as False to create a fake file.

Notes¶

Uses the directory structure specified in xhydro/testing/data/hydrotel_structure.yml. Most files are fake, except for the project.csv, simulation.csv and output.csv files, which are filled with default options taken from xhydro/modelling/data/hydrotel_defaults/.

Format release history in Markdown or ReStructuredText.

Parameters¶

style{« rst », « md »}: Use ReStructuredText (rst) or Markdown (md) formatting. Default: Markdown.
file{os.PathLike, StringIO, TextIO}, optional: If provided, prints to the given file-like object. Otherwise, returns a string.
changes{str, os.PathLike}, optional: If provided, manually points to the file where the changelog can be found. Assumes a relative path otherwise.
latestbool: Whether to return the release notes of the latest version or all the content of the changelog.

Returns¶

str or None: Formatted release notes as a string, if file is not provided.

Notes¶

This function exists solely for development purposes. Adapted from xclim.testing.utils.publish_release_notes.