# `ImageFile` Module

The `ImageFile` module provides support functions for the image open and save functions.

In addition, it provides a `Parser` class which can be used to decode an image piece by piece (e.g. while receiving it over a network connection). This class implements the same consumer interface as the standard sgmllib and xmllib modules.

## Example: Parse an image

    from PIL import ImageFile

    fp = open("hopper.pgm", "rb")

    p = ImageFile.Parser()

    while 1:
        s = fp.read(1024)
        if not s:
            break
        p.feed(s)

    im = p.close()

    im.save("copy.jpg")

## Classes

class PIL.ImageFile.Parser

  Incremental image parser. This class implements the standard feed/close consumer interface.

  close()

    (Consumer) Close the stream.

    Returns:

      An image object.

    Raises:

      OSError – If the parser failed to parse the image file either because it cannot be identified or cannot be decoded.

  feed(data)

    (Consumer) Feed data to the parser.

    Parameters:

      data – A string buffer.

    Raises:

      OSError – If the parser failed to parse the image file.

  reset()

    (Consumer) Reset the parser. Note that you can only call this method immediately after you’ve created a parser; parser instances cannot be reused.

class PIL.ImageFile.PyCodec
  cleanup()

    Override to perform codec specific cleanup

    Returns:

      None

  init(args)

    Override to perform codec specific initialization

    Parameters:

      args – Array of args items from the tile entry

    Returns:

      None

  setfd(fd)

    Called from ImageFile to set the Python file-like object

    Parameters:

      fd – A Python file-like object

    Returns:

      None

  setimage(im, extents=None)

    Called from ImageFile to set the core output image for the codec

    Parameters:

      - im – A core image object

      - extents – a 4 tuple of (x0, y0, x1, y1) defining the rectangle for this tile

    Returns:

      None

class PIL.ImageFile.PyDecoder

  Bases: `PyCodec`

  Python implementation of a format decoder. Override this class and add the decoding logic in the `decode()` method.

  See Writing Your Own File Codec in Python

  decode(buffer)

    Override to perform the decoding process.

    Parameters:

      buffer – A bytes object with the data to be decoded.

    Returns:

      A tuple of `(bytes consumed, errcode)`. If finished with decoding return -1 for the bytes consumed. Err codes are from `ImageFile.ERRORS`.

  set_as_raw(data, rawmode=None)

    Convenience method to set the internal image from a stream of raw data

    Parameters:

      - data – Bytes to be set

      - rawmode – The rawmode to be used for the decoder. If not specified, it will default to the mode of the image

    Returns:

      None

class PIL.ImageFile.PyEncoder

  Bases: `PyCodec`

  Python implementation of a format encoder. Override this class and add the decoding logic in the `encode()` method.

  See Writing Your Own File Codec in Python

  encode(bufsize)

    Override to perform the encoding process.

    Parameters:

      bufsize – Buffer size.

    Returns:

      A tuple of `(bytes encoded, errcode, bytes)`. If finished with encoding return 1 for the error code. Err codes are from `ImageFile.ERRORS`.

  encode_to_file(fh, bufsize)
    Parameters:

      - fh – File handle.

      - bufsize – Buffer size.

    Returns:

      If finished successfully, return 0. Otherwise, return an error code. Err codes are from `ImageFile.ERRORS`.

  encode_to_pyfd()

    If `pushes_fd` is `True`, then this method will be used, and `encode()` will only be called once.

    Returns:

      A tuple of `(bytes consumed, errcode)`. Err codes are from `ImageFile.ERRORS`.

class PIL.ImageFile.ImageFile

  Bases: `Image`

  Base class for image file format handlers.

  tile

    A list of tile descriptors, or `None`

  get_format_mimetype()
  verify()

    Check file integrity

  load()

    Load image data based on tile list

  load_prepare()
  load_end()

class PIL.ImageFile.StubImageFile

  Bases: `ImageFile`

  Base class for stub image loaders.

  A stub loader is an image loader that can identify files of a certain format, but relies on external code to load the file.

  load()

    Load image data based on tile list

## Constants

PIL.ImageFile.LOAD_TRUNCATED_IMAGES = False

  Whether or not to load truncated image files. User code may change this.

PIL.ImageFile.ERRORS

  Dict of known error codes returned from `PyDecoder.decode()`, `PyEncoder.encode()` `PyEncoder.encode_to_pyfd()` and `PyEncoder.encode_to_file()`.