get_pkg_data_filename

astropy.utils.data.get_pkg_data_filename(data_name, package=None, show_progress=True, remote_timeout=None)

Retrieves a data file from the standard locations for the package and provides a local filename for the data.

This function is similar to get_pkg_data_fileobj but returns the file name instead of a readable file-like object. This means that this function must always cache remote files locally, unlike get_pkg_data_fileobj.

Parameters:

data_namestr

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.

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

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 the requests in seconds (default is the configurable astropy.utils.data.Conf.remote_timeout).

Returns:

filenamestr

A file path on the local file system corresponding to the data requested in data_name.

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_fileobj

returns a file-like object with the data

Examples

This will retrieve the contents of the data file for the astropy.wcs tests:

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

This retrieves a data file by hash either locally or from the astropy data server:

>>> from astropy.utils.data import get_pkg_data_filename
>>> fn = get_pkg_data_filename('hash/34c33b3eb0d56eb9462003af249eff28')  
>>> with open(fn) as f:
...     fcontents = f.read()
...