Skip to main content
`Ctrl`+`K`

# 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, *, use_fsspec=None, fsspec_kwargs=None, fsspec_filesystem=None, close_files=True)

  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, lzma (xz) or lzw (Z) if the appropriate compression libraries are provided by the Python installation.

  Parameters:
    name_or_obj `python:str` or python: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.

    encoding `python:str`, optional

      When `None` (default), returns a file-like object with a `read` method that 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 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_progress bool, optional

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

    remote_timeout `python:float`

      Timeout for remote requests in seconds (default is the configurable `astropy.utils.data.Conf.remote_timeout`).

    sources `python:list` of `python: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_headers `python:dict` or `python:None`

      HTTP request headers to pass into `urlopen` if needed. (These headers are ignored if the protocol for the `name_or_obj`/`sources` entry is not a remote HTTP URL.) In the default case (None), the headers are `User-Agent: some_value` and `Accept: */*`, where `some_value` is set by `astropy.utils.data.conf.default_http_user_agent`.

    use_fsspec bool, optional

      Use `fsspec.open` to open the file? Defaults to `False` unless `name_or_obj` starts with the Amazon S3 storage prefix `s3://` or the Google Cloud Storage prefix `gs://`. Can also be used for paths with other prefixes (e.g. `http://`) but in this case you must explicitly pass `use_fsspec=True`. Use of this feature requires the optional `fsspec` package. A `ModuleNotFoundError` will be raised if the dependency is missing.

      Added in version 5.2.

    fsspec_kwargs `python:dict`, optional

      Keyword arguments passed on to `fsspec.open`. This can be used to configure cloud storage credentials and caching behavior. For example, pass `fsspec_kwargs={"anon": True}` to enable anonymous access to Amazon S3 open data buckets. See `fsspec`’s documentation for available parameters. Finer control over `fsspec` filesystem configuration is available through the `fsspec_filesystem` keyword argument.

      Added in version 5.2.

    fsspec_filesystem `fsspec.spec.AbstractFileSystem`, optional

      A `filesystem` instance initialized by the user, for example, via `fsspec.spec.AbstractFileSystem`. Files will be opened by calling `fsspec.spec.AbstractFileSystem.open` on `fsspec_filesystem`, giving the user a way to set, for example, the filesystem’s `protocol`, `block_size`, and `cache_type`. See `fsspec`’s documentation for available parameters.

      Added in version 8.0.

    close_files bool, optional

      Close the file object when exiting the context manager. Default is `True`.

      Added in version 5.2.

  Returns:
    file file-like (readable)

  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`. See `download_file` for details.