astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- Astropy Core Package Utilities (`astropy.utils`) »
- get_pkg_data_filename

# 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_name : 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.

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

  show_progress : bool, optional

  > Whether to display a progress bar if the file is downloaded from a remote server. Default is `True`.

  remote_timeout : float

  > Timeout for the requests in seconds (default is the configurable `astropy.utils.data.Conf.remote_timeout`, which is 3s by default)

  Returns:

  filename : str

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

  Raises:

  urllib2.URLError, urllib.error.URLError

  > If a remote file cannot be found.

  IOError

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