miranda.testing package

Helpers for testing miranda.

Submodules

miranda.testing.utils module

Testing utilities module.

miranda.testing.utils.TESTDATA_BRANCH = 'v2025.5.16'

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

or setting the variable at runtime:

$ env MIRANDA_TESTDATA_BRANCH="my_testing_branch" pytest
miranda.testing.utils.TESTDATA_CACHE_DIR = None

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 MIRANDA_TESTDATA_CACHE_DIR="/path/to/my/data"

or setting the variable at runtime:

$ env MIRANDA_TESTDATA_CACHE_DIR="/path/to/my/data" pytest
miranda.testing.utils.TESTDATA_REPO_URL = 'https://raw.githubusercontent.com/Ouranosinc/miranda-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 MIRANDA_TESTDATA_REPO_URL="https://github.com/my_username/miranda-testdata"

or setting the variable at runtime:

$ env MIRANDA_TESTDATA_REPO_URL="https://github.com/my_username/miranda-testdata" pytest
miranda.testing.utils.audit_url(url: str, context: str | None = None) → str[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.

Returns:

str – The URL if it is well-formed.

Raises:

URLError – If the URL is not well-formed.

miranda.testing.utils.cassini(repo: str = 'https://raw.githubusercontent.com/Ouranosinc/miranda-testdata/', branch: str = 'v2025.5.16', cache_dir: str | Path = None, allow_updates: bool = True)[source]

Pooch registry instance for miranda 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 miranda testing data.

Notes

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

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

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

  • MIRANDA_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 miranda.testing import cassini

example_file = cassini().fetch("example.nc")
data = xr.open_dataset(example_file)
miranda.testing.utils.default_testdata_cache = None

Default location for the testing data cache.

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

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

miranda.testing.utils.default_testdata_version = 'v2025.5.16'

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

miranda.testing.utils.gather_testing_data(worker_cache_dir: str | PathLike[str] | Path, worker_id: str, _cache_dir: str | PathLike[str] | None = None) → None[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.

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

Convenience function to open a dataset from the miranda testing data using the cassini class.

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

Parameters:

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

  • cassini_kwargs (dict) – Keyword arguments passed to the cassini function.

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

Returns:

xarray.Dataset – The dataset.

See also

xarray.open_dataset

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

cassini

Pooch wrapper for accessing the miranda testing data.

miranda.testing.utils.populate_testing_data(temp_folder: Path | None = None, repo: str = 'https://raw.githubusercontent.com/Ouranosinc/miranda-testdata/', branch: str = 'v2025.5.16', local_cache: Path = None) → None[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 miranda-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.

miranda.testing.utils.publish_release_notes(style: str = 'md', file: PathLike[str] | StringIO | TextIO | None = None, changes: str | PathLike[str] | None = None) → str | 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.

Returns:

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

Notes

This function is used solely for development and packaging purposes.

miranda.testing.utils.show_versions(file: PathLike | StringIO | TextIO | None = None, deps: list | None = None) → str | None[source]

Print the versions of miranda 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, prints miranda dependencies.

Returns:

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

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

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