download_file¶
-
astropy.utils.data.
download_file
(remote_url, cache=False, show_progress=True, timeout=None, sources=None, pkgname='astropy', http_headers=None, ftp_tls=False)[source]¶ Downloads a URL and optionally caches the result.
It returns the filename of a file containing the URL’s contents. If
cache=True
and the file is present in the cache, just returns the filename; if the file had to be downloaded, add it to the cache.The cache is effectively a dictionary mapping URLs to files; by default the file contains the contents of the URL that is its key, but in practice these can be obtained from a mirror (using
sources
) or imported from the local filesystem (usingimport_file_to_cache
orimport_download_cache
). Regardless, each file is regarded as representing the contents of a particular URL, and this URL should be used to look them up or otherwise manipulate them.The files in the cache directory are named according to a cryptographic hash of their contents (currently MD5, so hackers can cause collisions). Thus files with the same content share storage. The modification times on these files normally indicate when they were last downloaded from the Internet.
- Parameters
- remote_urlstr
The URL of the file to download
- cachebool or “update”, optional
Whether to cache the contents of remote URLs. If “update”, always download the remote URL in case there is a new version and store the result in the cache.
- show_progressbool, optional
Whether to display a progress bar during the download (default is
True
). Regardless of this setting, the progress bar is only displayed when outputting to a terminal.- timeoutfloat, optional
The timeout, in seconds. Otherwise, use
astropy.utils.data.Conf.remote_timeout
.- sourceslist of str, optional
If provided, a list of URLs to try to obtain the file from. The result will be stored under the original URL. The original URL will not be tried unless it is in this list; this is to prevent long waits for a primary server that is known to be inaccessible at the moment. If an empty list is passed, then
download_file
will not attempt to connect to the Internet.- pkgname
str
, optional The package name to use to locate the download cache. i.e. for
pkgname='astropy'
the default cache location is~/.astropy/cache
.- http_headersdict or None
HTTP request headers to pass into
urlopen
if needed. (These headers are ignored if the protocol for thename_or_obj
/sources
entry is not a remote HTTP URL.) In the default case (None), the headers areUser-Agent: some_value
andAccept: */*
, wheresome_value
is set byastropy.utils.data.conf.default_http_user_agent
.- ftp_tlsbool
If True, use TLS with ftp URLs instead of the standard unsecured FTP.
- Returns
- local_pathstr
Returns the local path that the file was download to.
- Raises
- urllib.error.URLError
Whenever there’s a problem getting the remote file.
Notes
Because this returns a filename, another process could run clear_download_cache before you actually open the file, leaving you with a filename that no longer points to a usable file.