download

download(url: str, path: str | Path, *, force: bool = True, clean_on_failure: bool = True, backend: Literal['urllib', 'requests'] | None = None, hexdigests: Mapping[str, str] | None = None, hexdigests_remote: Mapping[str, str] | None = None, hexdigests_strict: bool = False, progress_bar: bool = True, tqdm_kwargs: Mapping[str, Any] | None = None, _version: str | None = None, **kwargs: Unpack[RequestKwargs]) → None[source]

Download a file from a given URL.

Parameters:

  • url – URL to download

  • path – Path to download the file to

  • force – If false and the file already exists, will not re-download.

  • clean_on_failure – If true, will delete the file on any exception raised during download

  • backend – The downloader to use. Choose ‘urllib’ or ‘requests’

  • hexdigests – The expected hexdigests as (algorithm_name, expected_hex_digest) pairs.

  • hexdigests_remote – The expected hexdigests as (algorithm_name, url to file with expected hexdigest) pairs.

  • hexdigests_strict – Set this to False to stop automatically checking for the algorithm(filename)=hash format

  • progress_bar – Set to true to show a progress bar while downloading

  • tqdm_kwargs – Override the default arguments passed to tadm.tqdm when progress_bar is True.

  • kwargs – If using urllib.request.urlretrieve(), there are no keyword arguments available. If using requests as a backend, passes these to requests.get(). If using requests as a backend, stream is set to True by default.

Raises:

  • Exception – Thrown if an error besides a keyboard interrupt is thrown during download

  • KeyboardInterrupt – If a keyboard interrupt is thrown during download

  • UnexpectedDirectory – If a directory is given for the path argument

  • ValueError – If an invalid backend is chosen

  • DownloadError – If an error occurs during download