get_pkg_data_fileobj

astropy.utils.data.get_pkg_data_fileobj(data_name, package=None, encoding=None, cache=True)[source]

Retrieves a data file from the standard locations for the package and provides the file as a file-like object that reads bytes.

Parameters:
data_namepython:str

Name/location of the desired data file. One of the following:

  • The name of a data file included in the source distribution. The path is relative to the module calling this function. For example, if calling from astropy.pkname, use 'data/file.dat' to get the file in astropy/pkgname/data/file.dat. Double-dots can be used to go up a level. In the same example, use '../data/file.dat' to get astropy/data/file.dat.

  • If a matching local file does not exist, the Astropy data server will be queried for the file.

  • A hash like that produced by compute_hash can be requested, prefixed by ‘hash/’ e.g. ‘hash/34c33b3eb0d56eb9462003af249eff28’. The hash will first be searched for locally, and if not found, the Astropy data server will be queried.

packagepython:str, optional

If specified, look for a file relative to the given package, rather than the default of looking relative to the calling module’s package.

encodingpython:str, optional

When None (default), returns a file-like object with a read method returns str (unicode) objects, using locale.getpreferredencoding as an encoding. This matches the default behavior of the built-in open when no mode argument is provided.

When 'binary', returns a file-like object where its read method returns bytes objects.

When another string, it is the name of an encoding, and the file-like object’s read method will return str (unicode) objects, decoded from binary using the given encoding.

cachebool

If True, the file will be downloaded and saved locally or the already-cached local copy will be accessed. If False, the file-like object will directly access the resource (e.g. if a remote URL is accessed, an object like that from urllib.request.urlopen is returned).

Returns:
fileobjpython:file-like object

An object with the contents of the data file available via read function. Can be used as part of a with statement, automatically closing itself after the with block.

Raises:
urllib.error.URLError

If a remote file cannot be found.

OSError

If problems occur writing or reading a local file.

See also

get_pkg_data_contents

returns the contents of a file or url as a bytes object

get_pkg_data_filename

returns a local name for a file containing the data

Examples

This will retrieve a data file and its contents for the astropy.wcs tests:

>>> from astropy.utils.data import get_pkg_data_fileobj
>>> with get_pkg_data_fileobj('data/3d_cd.hdr',
...                           package='astropy.wcs.tests') as fobj:
...     fcontents = fobj.read()
...

This next example would download a data file from the astropy data server because the allsky/allsky_rosat.fits file is not present in the source distribution. It will also save the file locally so the next time it is accessed it won’t need to be downloaded.:

>>> from astropy.utils.data import get_pkg_data_fileobj
>>> with get_pkg_data_fileobj('allsky/allsky_rosat.fits',
...                           encoding='binary') as fobj:  
...     fcontents = fobj.read()
...
Downloading http://data.astropy.org/allsky/allsky_rosat.fits [Done]

This does the same thing but does not cache it locally:

>>> with get_pkg_data_fileobj('allsky/allsky_rosat.fits',
...                           encoding='binary', cache=False) as fobj:  
...     fcontents = fobj.read()
...
Downloading http://data.astropy.org/allsky/allsky_rosat.fits [Done]