# 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 (`Union`[`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 (`Optional`[`SessionConfig`], 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, overwrite]) | 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, **kwargs)

    Add a file to the download queue.

    Parameters:

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

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

      - filename (`Union`[`str`, `Callable`[[`str`, `Optional`[`ClientResponse`]], `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 (`Union`[`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 `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.

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