Skip to content
Back to top
View this page

# PIL package (autodoc of remaining modules)

Reference for modules whose documentation has not yet been ported or written can be found here.

## `PIL` module

exception PIL.UnidentifiedImageError

  Bases: `OSError`

  Raised in `PIL.Image.open()` if an image cannot be opened and identified.

  If a PNG image raises this error, setting `ImageFile.LOAD_TRUNCATED_IMAGES` to true may allow the image to be opened after all. The setting will ignore missing data and checksum failures.

## `BdfFontFile` module

Parse X Bitmap Distribution Format (BDF)

class PIL.BdfFontFile.BdfFontFile(fp: BinaryIO)

  Bases: `FontFile`

  Font file plugin for the X11 BDF format.

PIL.BdfFontFile.bdf_char(f: BinaryIO) → tuple[str, int, tuple[tuple[int, int], tuple[int, int, int, int], tuple[int, int, int, int]], Image] | None

## `ContainerIO` module

class PIL.ContainerIO.ContainerIO(file: IO, offset: int, length: int)

  Bases: `IO`

  A file object that provides read access to a part of an existing file (for example a TAR file).

  close() → None
  fileno() → int
  flush() → None
  isatty() → bool
  read(n: int = -1) → AnyStr

    Read data.

    Parameters:

      n – Number of bytes to read. If omitted, zero or negative, read until end of region.

    Returns:

      An 8-bit string.

  readable() → bool
  readline(n: int = -1) → AnyStr

    Read a line of text.

    Parameters:

      n – Number of bytes to read. If omitted, zero or negative, read until end of line.

    Returns:

      An 8-bit string.

  readlines(n: int | None = -1) → list[AnyStr]

    Read multiple lines of text.

    Parameters:

      n – Number of lines to read. If omitted, zero, negative or None, read until end of region.

    Returns:

      A list of 8-bit strings.

  seek(offset: int, mode: int = 0) → int

    Move file pointer.

    Parameters:

      - offset – Offset in bytes.

      - mode – Starting position. Use 0 for beginning of region, 1 for current offset, and 2 for end of region. You cannot move the pointer outside the defined region.

    Returns:

      Offset from start of region, in bytes.

  seekable() → bool
  tell() → int

    Get current file pointer.

    Returns:

      Offset from start of region, in bytes.

  truncate(size: int | None = None) → int
  writable() → bool
  write(b: AnyStr) → NoReturn
  writelines(lines: Iterable) → NoReturn

## `FontFile` module

class PIL.FontFile.FontFile

  Bases: `object`

  Base class for raster font file handlers.

  bitmap: Image | None = None
  compile() → None

    Create metrics and bitmap

  save(filename: str) → None

    Save font

  to_imagefont() → ImageFont

    Convert to ImageFont

PIL.FontFile.puti16(fp: BinaryIO, values: tuple[int, int, int, int, int, int, int, int, int, int]) → None

  Write network order (big-endian) 16-bit sequence

## `GdImageFile` module

Note

This format cannot be automatically recognized, so the class is not registered for use with `PIL.Image.open()`. To open a gd file, use the `PIL.GdImageFile.open()` function instead.

Warning

THE GD FORMAT IS NOT DESIGNED FOR DATA INTERCHANGE. This implementation is provided for convenience and demonstrational purposes only.

class PIL.GdImageFile.GdImageFile(fp: StrOrBytesPath | IO[bytes], filename: str | bytes | None = None)

  Bases: `ImageFile`

  Image plugin for the GD uncompressed format. Note that this format is not supported by the standard `PIL.Image.open()` function. To use this plugin, you have to import the `PIL.GdImageFile` module and use the `PIL.GdImageFile.open()` function.

  format: str | None = 'GD'
  format_description: str | None = 'GD uncompressed images'

PIL.GdImageFile.open(fp: str | bytes | PathLike[str] | PathLike[bytes] | IO[bytes], mode: str = 'r') → GdImageFile

  Load texture from a GD image file.

  Parameters:

    - fp – GD file name, or an opened file handle.

    - mode – Optional mode. In this version, if the mode argument is given, it must be “r”.

  Returns:

    An image instance.

  Raises:

    OSError – If the image could not be read.

## `GimpGradientFile` module

Stuff to translate curve segments to palette values (derived from the corresponding code in GIMP, written by Federico Mena Quintero. See the GIMP distribution for more information.)

PIL.GimpGradientFile.EPSILON = 1e-10

class PIL.GimpGradientFile.GimpGradientFile(fp: IO[bytes])

  Bases: `GradientFile`

  File handler for GIMP’s gradient format.

class PIL.GimpGradientFile.GradientFile

  Bases: `object`

  getpalette(entries: int = 256) → tuple[bytes, str]
  gradient: list[tuple[float, float, float, list[float], list[float], Callable[[float, float], float]]] | None = None

PIL.GimpGradientFile.SEGMENTS = [<function linear>, <function curved>, <function sine>, <function sphere_increasing>, <function sphere_decreasing>]

PIL.GimpGradientFile.curved(middle: float, pos: float) → float

PIL.GimpGradientFile.linear(middle: float, pos: float) → float

PIL.GimpGradientFile.sine(middle: float, pos: float) → float

PIL.GimpGradientFile.sphere_decreasing(middle: float, pos: float) → float

PIL.GimpGradientFile.sphere_increasing(middle: float, pos: float) → float

## `GimpPaletteFile` module

class PIL.GimpPaletteFile.GimpPaletteFile(fp: IO[bytes])

  Bases: `object`

  File handler for GIMP’s palette format.

  classmethod frombytes(data: bytes) → GimpPaletteFile
  getpalette() → tuple[bytes, str]
  rawmode = 'RGB'

## `ImageDraw2` module

(Experimental) WCK-style drawing interface operations

See also

`PIL.ImageDraw`

class PIL.ImageDraw2.Pen(color: str, width: int = 1, opacity: int = 255)

  Bases: `object`

  Stores an outline color and width.

class PIL.ImageDraw2.Brush(color: str, opacity: int = 255)

  Bases: `object`

  Stores a fill color

class PIL.ImageDraw2.Font(color: str, file: str | bytes | PathLike[str] | PathLike[bytes] | BinaryIO, size: float = 12)

  Bases: `object`

  Stores a TrueType font and color

class PIL.ImageDraw2.Draw(image: Image | str, size: tuple[int, int] | list[int] | None = None, color: float | tuple[float, ...] | str | None = None)

  Bases: `object`

  (Experimental) WCK-style drawing interface

  flush() → Image
  render(op: str, xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, brush: Brush | Pen | None = None, **kwargs: Any) → None
  settransform(offset: tuple[float, float]) → None

    Sets a transformation offset.

  arc(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, start: float, end: float, *options: Any) → None

    Draws an arc (a portion of a circle outline) between the start and end angles, inside the given bounding box.

    See also

    `PIL.ImageDraw.ImageDraw.arc()`

  chord(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, start: float, end: float, *options: Any) → None

    Same as `arc()`, but connects the end points with a straight line.

    See also

    `PIL.ImageDraw.ImageDraw.chord()`

  ellipse(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, *options: Any) → None

    Draws an ellipse inside the given bounding box.

    See also

    `PIL.ImageDraw.ImageDraw.ellipse()`

  line(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, *options: Any) → None

    Draws a line between the coordinates in the `xy` list.

    See also

    `PIL.ImageDraw.ImageDraw.line()`

  pieslice(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, start: float, end: float, *options: Any) → None

    Same as arc, but also draws straight lines between the end points and the center of the bounding box.

    See also

    `PIL.ImageDraw.ImageDraw.pieslice()`

  polygon(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, *options: Any) → None

    Draws a polygon.

    The polygon outline consists of straight lines between the given coordinates, plus a straight line between the last and the first coordinate.

    See also

    `PIL.ImageDraw.ImageDraw.polygon()`

  rectangle(xy: Sequence[float] | Sequence[Sequence[float]], pen: Pen | Brush | None, *options: Any) → None

    Draws a rectangle.

    See also

    `PIL.ImageDraw.ImageDraw.rectangle()`

  text(xy: tuple[float, float], text: AnyStr, font: Font) → None

    Draws the string at the given position.

    See also

    `PIL.ImageDraw.ImageDraw.text()`

  textbbox(xy: tuple[float, float], text: AnyStr, font: Font) → tuple[float, float, float, float]

    Returns bounding box (in pixels) of given text.

    Returns:

      `(left, top, right, bottom)` bounding box

    See also

    `PIL.ImageDraw.ImageDraw.textbbox()`

  textlength(text: AnyStr, font: Font) → float

    Returns length (in pixels) of given text. This is the amount by which following text should be offset.

    See also

    `PIL.ImageDraw.ImageDraw.textlength()`

## `ImageMode` module

class PIL.ImageMode.ModeDescriptor(mode: str, bands: tuple[str, ...], basemode: str, basetype: str, typestr: str)

  Bases: `NamedTuple`

  Wrapper for mode strings.

  bands: tuple[str, ...]

    Alias for field number 1

  basemode: str

    Alias for field number 2

  basetype: str

    Alias for field number 3

  mode: str

    Alias for field number 0

  typestr: str

    Alias for field number 4

PIL.ImageMode.getmode(mode: str) → ModeDescriptor

  Gets a mode descriptor for the given mode.

## `PaletteFile` module

class PIL.PaletteFile.PaletteFile(fp: IO[bytes])

  Bases: `object`

  File handler for Teragon-style palette files.

  getpalette() → tuple[bytes, str]
  rawmode = 'RGB'

## `PcfFontFile` module

class PIL.PcfFontFile.PcfFontFile(fp: BinaryIO, charset_encoding: str = 'iso8859-1')

  Bases: `FontFile`

  Font file plugin for the X11 PCF format.

  name = 'name'

PIL.PcfFontFile.sz(s: bytes, o: int) → bytes

## `PngImagePlugin.iTXt` class

class PIL.PngImagePlugin.iTXt(text: str, lang: str | None = None, tkey: str | None = None)

  Bases: `str`

  Subclass of string to allow iTXt chunks to look like strings while keeping their extra information

  __new__(cls, text, lang, tkey)
    Parameters:

      - value – value for this key

      - lang – language code

      - tkey – UTF-8 version of the key name

  lang: str | bytes | None
  tkey: str | bytes | None

## `PngImagePlugin.PngInfo` class

class PIL.PngImagePlugin.PngInfo

  Bases: `object`

  PNG chunk container (for use with save(pnginfo=))

  add(cid: bytes, data: bytes, after_idat: bool = False) → None

    Appends an arbitrary chunk. Use with caution.

    Parameters:

      - cid – a byte string, 4 bytes long.

      - data – a byte string of the encoded data

      - after_idat – for use with private chunks. Whether the chunk should be written after IDAT

  add_itxt(key: str | bytes, value: str | bytes, lang: str | bytes = '', tkey: str | bytes = '', zip: bool = False) → None

    Appends an iTXt chunk.

    Parameters:

      - key – latin-1 encodable text key name

      - value – value for this key

      - lang – language code

      - tkey – UTF-8 version of the key name

      - zip – compression flag

  add_text(key: str | bytes, value: str | bytes | iTXt, zip: bool = False) → None

    Appends a text chunk.

    Parameters:

      - key – latin-1 encodable text key name

      - value – value for this key, text or an `PIL.PngImagePlugin.iTXt` instance

      - zip – compression flag

## `TarIO` module

class PIL.TarIO.TarIO(tarfile: str, file: str)

  Bases: `ContainerIO`[`bytes`]

  A file object that provides read access to a given member of a TAR file.

## `WalImageFile` module

This reader is based on the specification available from: https://www.flipcode.com/archives/Quake_2_BSP_File_Format.shtml and has been tested with a few sample files found using google.

Note

This format cannot be automatically recognized, so the reader is not registered for use with `PIL.Image.open()`. To open a WAL file, use the `PIL.WalImageFile.open()` function instead.

class PIL.WalImageFile.WalImageFile(fp: StrOrBytesPath | IO[bytes], filename: str | bytes | None = None)

  Bases: `ImageFile`

  format: str | None = 'WAL'
  format_description: str | None = 'Quake2 Texture'
  load() → Image.core.PixelAccess | None

    Load image data based on tile list

PIL.WalImageFile.open(filename: str | bytes | PathLike[str] | PathLike[bytes] | IO[bytes]) → WalImageFile

  Load texture from a Quake2 WAL texture file.

  By default, a Quake2 standard palette is attached to the texture. To override the palette, use the `PIL.Image.Image.putpalette()` method.

  Parameters:

    filename – WAL file name, or an opened file handle.

  Returns:

    An image instance.