xhydro.testing package¶

Testing utilities and helper functions.

Submodules¶

xhydro.testing.helpers module¶

Helper functions for testing data management.

xhydro.testing.helpers.DATA_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_DATA_DIR="/path/to/my/data"

or setting the variable at runtime:

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

xhydro.testing.helpers.DEVEREAUX = <pooch.core.Pooch object>¶

Pooch registry instance for xhydro test data.

Notes¶

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

XHYDRO_DATA_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_DATA_UPDATES: If this environment variable is set, then the data files will be downloaded even if the upstream hashes do not match. This is useful if you want to always use the latest version of the data files.

Examples¶

Using the registry to download a file:

from xhydro.testing.utils import DEVEREAUX
import xarray as xr

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

xhydro.testing.helpers.generate_registry(filenames: list[str] | None = None, base_url: str = 'https://github.com/hydrologie/xhydro-testdata/raw/main') → None[source]¶

Generate a registry file for the test data.

Parameters¶

filenameslist of str, optional: List of filenames to generate the registry file for. If not provided, all files under xhydro/testing/data will be used.
base_urlstr, optional: Base URL to the test data repository.

xhydro.testing.helpers.load_registry(file: str | Path | None = None) → dict[str, str][source]¶

Load the registry file for the test data.

Parameters¶

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

xhydro.testing.helpers.populate_testing_data(registry: str | Path | None = None, temp_folder: Path | None = None, branch: str = 'main', _local_cache: Path = PosixPath('/home/docs/.cache/xhydro-testdata')) → None[source]¶

Populate the local cache with the testing data.

Parameters¶

registrystr or Path, optional: Path to the registry file. If not provided, the registry file from package_data will be used.
temp_folderPath, optional: Path to a temporary folder to use as the local cache. If not provided, the default location will be used.
branchstr, optional: Branch of hydrologie/xhydro-testdata to use when fetching testing datasets.
_local_cachePath, optional: Path to the local cache. Defaults to the default location.

Returns¶

None: The testing data will be downloaded to the 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 projet.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.

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.