get_readable_fileobj¶
-
astropy.utils.data.
get_readable_fileobj
(name_or_obj, encoding=None, cache=False, show_progress=True, remote_timeout=None, sources=None, http_headers=None)[source]¶ Yield a readable, seekable file-like object from a file or URL.
This supports passing filenames, URLs, and readable file-like objects, any of which can be compressed in gzip, bzip2 or lzma (xz) if the appropriate compression libraries are provided by the Python installation.
- Parameters
- name_or_objstr or file-like object
The filename of the file to access (if given as a string), or the file-like object to access.
If a file-like object, it must be opened in binary mode.
- encodingstr, optional
When
None
(default), returns a file-like object with aread
method that returnsstr
(unicode
) objects, usinglocale.getpreferredencoding
as an encoding. This matches the default behavior of the built-inopen
when nomode
argument is provided.When
'binary'
, returns a file-like object where itsread
method returnsbytes
objects.When another string, it is the name of an encoding, and the file-like object’s
read
method will returnstr
(unicode
) objects, decoded from binary using the given encoding.- cachebool or “update”, optional
Whether to cache the contents of remote URLs. If “update”, check the remote URL for a new version but store the result in the cache.
- show_progressbool, optional
Whether to display a progress bar if the file is downloaded from a remote server. Default is
True
.- remote_timeoutfloat
Timeout for remote requests in seconds (default is the configurable
astropy.utils.data.Conf.remote_timeout
, which is 3s by default)- 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.
- 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
.
- Returns
- filereadable file-like object
Notes
This function is a context manager, and should be used for example as:
with get_readable_fileobj('file.dat') as f: contents = f.read()
If a URL is provided and the cache is in use, the provided URL will be the name used in the cache. The contents may already be stored in the cache under this URL provided, they may be downloaded from this URL, or they may be downloaded from one of the locations listed in
sources
. Seedownload_file
for details.