Skip to main content
`Ctrl`+`K`

# imageio.core.Request

class imageio.core.Request(uri, mode, *, extension=None, format_hint: str = None, **kwargs)

  ImageResource handling utility.

  Represents a request for reading or saving an image resource. This object wraps information to that request and acts as an interface for the plugins to several resources; it allows the user to read from filenames, files, http, zipfiles, raw bytes, etc., but offer a simple interface to the plugins via `get_file()` and `get_local_filename()`.

  For each read/write operation a single Request instance is used and passed to the can_read/can_write method of a format, and subsequently to the Reader/Writer class. This allows rudimentary passing of information between different formats and between a format and associated reader/writer.

  Parameters:
    uri{str, bytes, file}

      The resource to load the image from.

    mode str

      The first character is “r” or “w”, indicating a read or write request. The second character is used to indicate the kind of data: “i” for an image, “I” for multiple images, “v” for a volume, “V” for multiple volumes, “?” for don’t care.

  Attributes:
    `extension`

      The (lowercase) extension of the requested filename.

    `filename`

      Name of the ImageResource.

    `firstbytes`

      The first 256 bytes of the file.

    format_hint
    `kwargs`

      The dict of keyword arguments supplied by the user.

    `mode`

      The mode of the request.

  Methods

  `finish`() | Wrap up this request.
  `get_file`() | Get a file object for the resource associated with this request.
  `get_local_filename`() | If the filename is an existing file on this filesystem, return that.
  `get_result`() | For internal use.

  Attribute and Method Details

  extension

    The (lowercase) extension of the requested filename. Suffixes in url’s are stripped. Can be None if the request is not based on a filename.

  filename

    Name of the ImageResource.

    The uri for which reading/saving was requested. This can be a filename, an http address, or other resource identifier. Do not rely on the filename to obtain the data, but use `get_file()` or `get_local_filename()` instead.

  firstbytes

    The first 256 bytes of the file. These can be used to parse the header to determine the file-format.

  format_hint
  kwargs

    The dict of keyword arguments supplied by the user.

  mode

    The mode of the request. The first character is “r” or “w”, indicating a read or write request. The second character is used to indicate the kind of data: “i” for an image, “I” for multiple images, “v” for a volume, “V” for multiple volumes, “?” for don’t care.

  finish() → None

    Wrap up this request.

    Finishes any pending reads or writes, closes any open files and frees any resources allocated by this request.

  get_file()

    Get a file object for the resource associated with this request. If this is a reading request, the file is in read mode, otherwise in write mode. This method is not thread safe. Plugins should not close the file when done.

    This is the preferred way to read/write the data. But if a format cannot handle file-like objects, they should use `get_local_filename()`.

  get_local_filename()

    If the filename is an existing file on this filesystem, return that. Otherwise a temporary file is created on the local file system which can be used by the format to read from or write to.

  get_result()

    For internal use. In some situations a write action can have a result (bytes data). That is obtained with this function.