download_file_from_url

pyhelpers.ops.download_file_from_url(url, path_to_file, if_exists='replace', max_retries=5, requests_session_args=None, verbose=False, print_wrap_limit=None, chunk_multiplier=1, desc=None, bar_format=None, colour=None, validate=True, **kwargs)[source]

Downloads a file from a valid URL.

See also [OPS-DFFU-1] and [OPS-DFFU-2].

Parameters:

  • url (str) – Valid URL pointing to a web resource.

  • path_to_file (str | os.PathLike[str]) – Path where the downloaded file will be saved; it can be either a full path with filename or just a filename, in which case it will be saved in the current working directory.

  • if_exists (str) – Action to take if the specified file already exists; options include 'replace' (default - download and replace the existing file) and 'pass' (cancel the download).

  • max_retries (int) – Maximum number of retries in case of download failures; defaults to 5.

  • verbose (bool | int) – Whether to print progress and relevant information to the console; defaults to False.

  • requests_session_args (dict | None) – [Optional] Additional parameters for initialising the requests session; defaults to None.

  • print_wrap_limit (int | None) – Maximum length of the string before splitting into two lines; defaults to None, which disables splitting. If the string exceeds this value, e.g. 100, it will be split at (before) state_prep to improve readability when printed.

  • chunk_multiplier (int | float) – A factor by which the default chunk size (1MB) is multiplied; this can be adjusted to optimise download performance based on file size; defaults to 1.

  • desc (str | None) – Custom description for the progress bar; when desc=None, it defaults to the filename.

  • bar_format (str | None) – Custom format for the progress bar.

  • colour (str | None) – Custom colour of the progress bar (e.g. ‘green’, ‘yellow’); defaults to None.

  • validate (bool) – Whether to validate if the downloaded file size matches the expected content length; defaults to True.

  • kwargs – [Optional] Additional parameters passed to the method tqdm.tqdm().

Examples:

>>> from pyhelpers.ops import download_file_from_url
>>> from pyhelpers.dirs import cd
>>> from PIL import Image
>>> import os
>>> url = 'https://www.python.org/static/community_logos/python-logo-master-v3-TM.png'
>>> path_to_img = cd("tests", "images", "ops-download_file_from_url-demo.png")
>>> # Check if "python-logo.png" exists at the specified path
>>> os.path.exists(path_to_img)
False
>>> # Download the .png file
>>> download_file_from_url(url, path_to_img, verbose=True, colour='green')
Downloading "ops-download_file_from_url-demo.png" 100%|██████████| 83.6k/83.6k | ...
    Saving "ops-download_file_from_url-demo.png" to "./tests/images/" ... Done.
>>> # If download is successful, check again:
>>> os.path.exists(path_to_img)
True
>>> img = Image.open(path_to_img)
>>> img.show()  # as illustrated below
../_images/ops-download_file_from_url-demo.svg

Figure 11 The Python Logo.


Note

  • When verbose=True, the function requires tqdm.