astro py:docs

- Index
- Modules

### Navigation

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

# get_pkg_data_fileobj

`astropy.utils.data.``get_pkg_data_fileobj`(data_name, package=None, encoding=None, cache=True)

  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_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.

  encoding : str, optional

  > When `None` (default), returns a file-like object with a `read` method that on Python 2.x returns `bytes` objects and on Python 3.x 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.

  cache : bool

  > 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 `urllib2.urlopen` on Python 2 or `urllib.request.urlopen` on Python 3 is returned).

  Returns:

  fileobj : file-like

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

  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_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]