# Downloader

class parfive.Downloader(max_conn=5, max_splits=5, progress=True, overwrite=False, config=None)

  Bases: `object`

  Download files in parallel.

  Parameters:

    - max_conn (`int`, default: `5`) – The number of parallel download slots.

    - max_splits (`int`, default: `5`) – The maximum number of splits to use to download a file (server dependent).

    - progress (`bool`, default: `True`) – If `True` show a main progress bar showing how many of the total files have been downloaded. If `False`, no progress bars will be shown at all.

    - overwrite (`bool` | `Literal`[`'unique'`], default: `False`) – Determine how to handle downloading if a file already exists with the same name. If `False` the file download will be skipped and the path returned to the existing file, if `True` the file will be downloaded and the existing file will be overwritten, if `'unique'` the filename will be modified to be unique.

    - config (`SessionConfig` | `None`, default: `None`) – A config object containing more complex settings for this `Downloader` instance.

  Attributes Summary

  `queued_downloads` | The total number of files already queued for download.

  Methods Summary

  `download`() | Download all files in the queue.
  `enqueue_file`(url[, path, filename, ...]) | Add a file to the download queue.
  `retry`(results) | Retry any failed downloads in a results object.
  `run_download`() | Download all files in the queue.
  `simple_download`(urls, *[, path, overwrite]) | Download a series of URLs to a single destination.

  Attributes Documentation

  queued_downloads

    The total number of files already queued for download.

  Methods Documentation

  download()

    Download all files in the queue.

    Returns:

      `parfive.Results` – A list of files downloaded.

    Notes

    This is a synchronous version of `run_download`, an `asyncio` event loop will be created to run the download (in it’s own thread if a loop is already running).

  enqueue_file(url, path=None, filename=None, overwrite=None, checksum=None, **kwargs)

    Add a file to the download queue.

    Parameters:

      - url (`str`) – The URL to retrieve.

      - path (`str` | `PathLike` | `None`, default: `None`) – The directory to retrieve the file into, if `None` defaults to the current directory.

      - filename (`str` | `Callable`[[`str`, `ClientResponse` | `None`], `PathLike`] | `None`, default: `None`) – The filename to save the file as. Can also be a callable which takes two arguments the url and the response object from opening that URL, and returns the filename. (Note, for FTP downloads the response will be `None`.) If `None` the HTTP headers will be read for the filename, or the last segment of the URL will be used.

      - overwrite (`bool` | `Literal`[`'unique'`] | `None`, default: `None`) – Determine how to handle downloading if a file already exists with the same name. If `False` the file download will be skipped and the path returned to the existing file (if any checksum also matches, see below), if `True` the file will be downloaded and the existing file will be overwritten, if `'unique'` the filename will be modified to be unique. If `None` the value set when constructing the `Downloader` object will be used.

      - checksum (`str` | `bool` | `None`, default: `None`) – Provide a checksum, or request one from the server, to compare to any existing file and verify the downloaded file. This option can either be a string or `True`, if `True` the checksum provided by the server (if any) will be used, and if it is a string the it should be of the form `<algorithm>=<checksum>`. Valid algorithms are any provided by `hashlib` but the HTTP spec allows `sha-512`, `sha-256`, `md5` or `sha`. If `True` then where provided by the server (in the `Repr-Digest` or `Content-Digest` headers) the checksum will be validated against the checksum returned by the server. When `overwrite=False` and `checksum=` is set the checksum will also be used to determine if any local file should be overwritten. If the checksum is `True` then the server provided checksum will be used to compare to the local file and download skipped if it matches. If the checksum is explicitly passed, the download will fail early if the server provides a checksum for the file which doesn’t match the one provided by the user.

      - kwargs (`dict`) – Extra keyword arguments are passed to `aiohttp.ClientSession.request` or `aioftp.Client.context` depending on the protocol.

  retry(results)

    Retry any failed downloads in a results object.

    Note

    This will start a new event loop.

    Parameters:

      results (`parfive.Results`) – A previous results object, the `.errors` property will be read and the downloads retried.

    Returns:

      `parfive.Results` – A modified version of the input `results` with all the errors from this download attempt and any new files appended to the list of file paths.

  async run_download()

    Download all files in the queue.

    Returns:

      `parfive.Results` – A list of files downloaded.

  classmethod simple_download(urls, *, path='./', overwrite=None)

    Download a series of URLs to a single destination.

    Parameters:

      - urls (iterable) – A sequence of URLs to download.

      - path (`pathlib.Path`, optional) – The destination directory for the downloaded files. Defaults to the current directory.

      - overwrite (`bool`, optional) – Overwrite the files at the destination directory. If `False` the URL will not be downloaded if a file with the corresponding filename already exists.

    Returns:

      `parfive.Results` – A list of files downloaded.