imagine.errors

import imagine

Everything here is re-exported by imagine, so import imagine is enough and the names are called as imagine.*. Importing imagine.errors on its own works too and reaches the same definitions.

Every error the module raises, under ImageError as their root.

The subclasses separate the cases a caller treats differently: input that is not an image it can read, output it cannot write, a format it does not know, a coordinate outside the surface, and a font that will not load.

Classes

ImageError

class imagine.ImageError < Error

Base class for every error the imagine module raises.

Catching ImageError catches everything this module throws on its own. The subclasses below exist so a caller can tell an unreadable upload apart from a coordinate mistake in their own code without matching on message text.

• printable — has a @to_string(), so echo and print() show something useful

ImageError.to_string()

imagine.ImageError.to_string()

DecodeError

class imagine.DecodeError < ImageError

Raised when image data cannot be read: the bytes are not an image at all, the format is one this build cannot decode, or the file is truncated or corrupt.

Anything arriving from outside the program (an upload, a download, a file a user picked) can raise this, so it is the one error a server handling images must always be ready for.

• printable — has a @to_string(), so echo and print() show something useful

DecodeError.to_string()

imagine.DecodeError.to_string()

EncodeError

class imagine.EncodeError < ImageError

Raised when an image cannot be written in the requested format, either because this build has no encoder for it or because the encoder rejected the image or the options given.

• printable — has a @to_string(), so echo and print() show something useful

EncodeError.to_string()

imagine.EncodeError.to_string()

FormatError

class imagine.FormatError < ImageError

Raised when a format name is not one imagine knows, or when a file extension cannot be mapped to a format.

• printable — has a @to_string(), so echo and print() show something useful

FormatError.to_string()

imagine.FormatError.to_string()

BoundsError

class imagine.BoundsError < ImageError

Raised when a rectangle, crop or resize falls outside the image, or when a dimension is zero or negative.

Drawing operations do not raise this. A line running off the edge of the canvas is clipped, which is what every drawing API does and what callers expect; it is only the operations that must return an image of an exact size that have no sensible way to continue.

• printable — has a @to_string(), so echo and print() show something useful

BoundsError.to_string()

imagine.BoundsError.to_string()

FontError

class imagine.FontError < ImageError

Raised when a font cannot be parsed, cannot be found on the system, or does not carry the horizontal metrics text layout needs.

• printable — has a @to_string(), so echo and print() show something useful

FontError.to_string()

imagine.FontError.to_string()

2026, Richard Ore and Zuri contributors