`DownloadManager`#

class ansys.tools.common.example_download.DownloadManager#

Manages downloads of example files.

Manages the download of example from the example-data repository, which is at ansys/example-data.

Overview#

Methods

`clear_download_cache`	Remove downloaded example files from the local path.
`download_file`	Download an example file from the `example-data` repository.
`download_directory`	Download an example directory from the `example-data` repository.

Import detail#

from ansys.tools.common.example_download import DownloadManager

Method detail#

DownloadManager.clear_download_cache()#: Remove downloaded example files from the local path.

DownloadManager.download_file(filename: str, directory: str, destination: str | pathlib.Path | None = None, force: bool = False, timeout: float = 60.0, max_retries: int = 3) → str#

Download an example file from the example-data repository.

This method first tries to use Git sparse checkout for efficient downloading, retrying up to max_retries times. If Git is not available or all Git attempts fail, it falls back to HTTP download, which is retried up to max_retries times as well. Between attempts, an exponential backoff delay (1, 2, 4, … seconds) is applied.

Parameters#

filenamestr: Name of the example file to download.
directorystr: Path under the example-data repository.
destinationstr | Path | None, default: None: Path to download the example file to. The default is None, in which case the default path for app data is used.
forcebool, default: False: Whether to always download the example file. The default is False, in which case if the example file is cached, it is reused.
timeoutfloat, default: 60.0: Timeout in seconds for each git or HTTP operation attempt (not a bound on the total call duration). The default is 60 seconds.
max_retriesint, default: 3: Maximum number of retry attempts for failed downloads, applied separately to the Git-based and HTTP-based strategies. Between attempts, an exponential backoff delay (1, 2, 4, … seconds) is applied. Because this method can fully exhaust retries for the Git-based strategy before falling back to the HTTP-based one, the worst-case total duration is roughly 2 * max_retries * timeout plus the backoff delays for both strategies.

Returns#

str: Local path of the downloaded example file.

Raises#

FileNotFoundError: If the destination path exists but is not a directory, or if it does not exist and could not be created.
ValueError: If the HTTP fallback constructs a download URL that does not use the http or https scheme.
DownloadError: If the file could not be downloaded after exhausting all retry attempts.

DownloadManager.download_directory(directory: str, destination: str | pathlib.Path | None = None, force: bool = False, github_token: str | None = None, timeout: float = 60.0, max_retries: int = 3) → str#

Download an example directory from the example-data repository.

This method first tries to use Git sparse checkout for efficient downloading, retrying up to max_retries times. If Git is not available or all Git attempts fail, it falls back to HTTP download, which is retried up to max_retries times as well. Between attempts, an exponential backoff delay (1, 2, 4, … seconds) is applied.

Warning

Do not execute this function with untrusted directory argument. Download directory tries to use Git sparse checkout, which involves executing Git commands with the directory as argument.

Parameters#

directorystr: Path under the example-data repository.
destinationstr | Path | None, default: None: Path to download the example file to. The default is None, in which case the default path for app data is used.
forcebool, default: False: Whether to always download the example file. The default is False, in which case if the example file is cached, it is reused.
github_tokenstr | None, default: None: GitHub personal access token for API authentication (used by HTTP fallback). When None, falls back to GITHUB_TOKEN or GH_TOKEN environment variables. Using a token increases the rate limit from 60 req/h to 5000 req/h.
timeoutfloat, default: 60.0: Timeout in seconds for each git or HTTP operation attempt (not a bound on the total call duration). The default is 60 seconds.
max_retriesint, default: 3: Maximum number of retry attempts for failed downloads, applied separately to the Git-based and HTTP-based strategies. Between attempts, an exponential backoff delay (1, 2, 4, … seconds) is applied. Because this method can fully exhaust retries for the Git-based strategy before falling back to the HTTP-based one, the worst-case total duration is roughly 2 * max_retries * timeout plus the backoff delays for both strategies.

Returns#

str: Local path of the downloaded example file.

Raises#

requests.HTTPError: If listing the directory contents from the GitHub API fails (for example, due to an invalid directory or a rate limit).
ValueError: If the HTTP fallback constructs a download URL that does not use the http or https scheme.
DownloadError: If the directory could not be downloaded after exhausting all retry attempts.