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
, seepooch.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 onplatformdirs
, seepooch.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/.
- xhydro.testing.utils.publish_release_notes(style: str = 'md', file: PathLike | StringIO | TextIO | None = None, changes: str | PathLike = None) str | None [source]¶
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.