Processing options¶

Import built-in options from imgproxykit.options and pass their instances to the Transform constructor. Constructors describe accepted arguments; imgproxy applies processing behavior and server defaults.

Scalar options accept their value either positionally or by keyword, for example Blur(2) or Blur(value=2). Options with multiple arguments and options accepting structured values use keyword-only arguments, except Preset, which accepts preset names as positional arguments.

Base option¶

class imgproxykit.options.Option[source]¶

Base class for typed imgproxy processing options.

Concrete options provide a fixed name and positional arguments. Pass their instances to Transform. This abstract class cannot be instantiated directly.

Arguments retain None values until serialization: internal gaps keep their positions, while trailing None values are omitted. Other false values (such as empty strings, zeroes, and False) keep their positions.

See imgproxy processing options.

abstract property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

name : ClassVar[str]¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = None¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

validate() → None[source]¶

Validate option arguments.

Override this method to enforce server-independent constraints. The default implementation does nothing.

Raises:¶

ValueError – If option arguments are invalid.

Return type:¶

None

Built-in options¶

AutoRotate¶

class imgproxykit.options.AutoRotate(value: ValueT)[source]¶

Apply the source EXIF orientation before processing.

Overrides automatic EXIF orientation handling for this request. The orientation tag is removed regardless of this setting.

value¶

Whether to apply the source EXIF orientation.

Type:¶

bool

Usage:

>>> option = AutoRotate(False)
>>> option.arguments
(False,)

See imgproxy auto rotate.

name : ClassVar[str] = 'auto_rotate'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'ar'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Background¶

class imgproxykit.options.Background(*, color: str | tuple[int, int, int] | None = None)[source]¶

Fill the background with a hex or RGB color, or explicitly disable filling.

Useful when converting transparent images to JPEG. Use hex() or rgb() to select a color, and disabled() to override background filling set earlier in the request, including by a preset.

color¶

Hex color without a leading hash, or an RGB tuple with channel values from 0 to 255. Omission disables filling.

Type:¶

str | tuple[int, int, int] | None

Usage:

>>> option = Background.hex('ffffff')
>>> option.arguments
('ffffff',)
>>> option = Background.rgb(red=255, green=255, blue=255)
>>> option.arguments
(255, 255, 255)
>>> option = Background.disabled()
>>> option.arguments
(None,)

See imgproxy background.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

classmethod disabled() → Self[source]¶

Explicitly disable background filling, including a preset’s color.

Emits the background option without arguments. Unlike omitting the option, this overrides background filling configured earlier in the request. Equivalent to Background().

Return type:¶

Self

classmethod hex(color: str) → Self[source]¶

Fill the background using a hex color without a leading hash.

Return type:¶

Self

name : ClassVar[str] = 'background'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

classmethod rgb(*, red: int, green: int, blue: int) → Self[source]¶

Fill the background using three required RGB channels.

Return type:¶

Self

short_name : ClassVar[str | None] = 'bg'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Blur¶

class imgproxykit.options.Blur(value: ValueT)[source]¶

Apply Gaussian blur with the given sigma.

The sigma controls the size of the Gaussian blur mask.

value¶

Gaussian blur sigma.

Type:¶

float

Usage:

>>> option = Blur(2.0)
>>> option.arguments
(2.0,)

See imgproxy blur.

name : ClassVar[str] = 'blur'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'bl'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

CacheBuster¶

class imgproxykit.options.CacheBuster(value: ValueT)[source]¶

Add an escaped version string to the signed URL to bypass caches.

Changing the value produces a new URL for browser and CDN caches without changing image processing. Special characters are escaped.

value¶

Cache version string included in the signed path.

Type:¶

str

Usage:

>>> option = CacheBuster('v2')
>>> option.arguments
('v2',)

See imgproxy cache buster.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

ScalarOption.arguments

name : ClassVar[str] = 'cachebuster'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'cb'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Crop¶

class imgproxykit.options.Crop(*, width: float | None = None, height: float | None = None, gravity: Position | None = None, offset_x: float | None = None, offset_y: float | None = None)[source]¶

Crop before resizing; dimensions below one are relative.

Defines the source area to process before resizing. Omitted gravity uses the request gravity; omitted arguments remain None.

width¶

Crop width: pixels at or above one, relative below one. Zero uses the full source width.

Type:¶

float | None

height¶

Crop height: pixels at or above one, relative below one. Zero uses the full source height.

Type:¶

float | None

gravity¶

Crop anchor, such as ce or fp.

Type:¶

Position | None

offset_x¶

Horizontal gravity offset or focus X coordinate.

Type:¶

float | None

offset_y¶

Vertical gravity offset or focus Y coordinate.

Type:¶

float | None

Usage:

>>> option = Crop(width=300, height=200, gravity='ce')
>>> option.arguments
(300, 200, 'ce', None, None)
>>> option = Crop(
...     width=0.5, height=0.5, gravity='fp', offset_x=0.5, offset_y=0.5
... )
>>> option.arguments
(0.5, 0.5, 'fp', 0.5, 0.5)

See imgproxy crop.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'crop'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'c'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

DPR¶

class imgproxykit.options.DPR(value: ValueT)[source]¶

Scale an image for high pixel density displays.

The factor also scales gravity offsets, watermark offsets, and padding.

value¶

Positive pixel density multiplier.

Type:¶

float

Usage:

>>> option = DPR(2)
>>> option.arguments
(2,)

See imgproxy DPR.

name : ClassVar[str] = 'dpr'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

EnforceThumbnail¶

class imgproxykit.options.EnforceThumbnail(value: ValueT)[source]¶

Use an embedded HEIC or AVIF thumbnail when available.

Uses the embedded thumbnail instead of the main source image when available. Supported for HEIC and AVIF sources.

value¶

Whether to prefer an embedded thumbnail.

Type:¶

bool

Usage:

>>> option = EnforceThumbnail(True)
>>> option.arguments
(True,)

See imgproxy enforce thumbnail.

name : ClassVar[str] = 'enforce_thumbnail'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'eth'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Enlarge¶

class imgproxykit.options.Enlarge(value: ValueT)[source]¶

Allow upscaling smaller source images.

Allows imgproxy to upscale sources smaller than the target dimensions.

value¶

Whether smaller source images may be enlarged.

Type:¶

bool

Usage:

>>> option = Enlarge(True)
>>> option.arguments
(True,)

See imgproxy enlarge.

name : ClassVar[str] = 'enlarge'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'el'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Expires¶

class imgproxykit.options.Expires(value: ValueT)[source]¶

Reject the URL after the given Unix timestamp.

imgproxy returns HTTP 404 after the supplied timestamp has expired.

value¶

Expiration time as a Unix timestamp in seconds.

Type:¶

int

See imgproxy expires.

name : ClassVar[str] = 'expires'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'exp'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Extend¶

class imgproxykit.options.Extend(*, value: bool, gravity: Position | None = None, offset_x: float | None = None, offset_y: float | None = None)[source]¶

Extend the canvas to the target dimensions.

Omitted settings remain None. The default anchor is center without offsets; smart gravity is unsupported.

value¶

Whether canvas extension is enabled.

Type:¶

bool

gravity¶

Canvas anchor, such as ce, so, or fp.

Type:¶

Position | None

offset_x¶

Horizontal gravity offset or focus X coordinate.

Type:¶

float | None

offset_y¶

Vertical gravity offset or focus Y coordinate.

Type:¶

float | None

Usage:

>>> option = Extend(value=True, gravity='so')
>>> option.arguments
(True, 'so', None, None)

See imgproxy extend.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'extend'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'ex'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

ExtendAspectRatio¶

class imgproxykit.options.ExtendAspectRatio(*, value: bool, gravity: Position | None = None, offset_x: float | None = None, offset_y: float | None = None)[source]¶

Extend the canvas to the requested aspect ratio.

Omitted settings remain None. The default anchor is center without offsets; smart gravity is unsupported.

value¶

Whether canvas extension is enabled.

Type:¶

bool

gravity¶

Canvas anchor, such as ce, so, or fp.

Type:¶

Position | None

offset_x¶

Horizontal gravity offset or focus X coordinate.

Type:¶

float | None

offset_y¶

Vertical gravity offset or focus Y coordinate.

Type:¶

float | None

Usage:

>>> option = ExtendAspectRatio(value=True, gravity='so')
>>> option.arguments
(True, 'so', None, None)

See imgproxy extend aspect ratio.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'extend_aspect_ratio'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'exar'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Filename¶

class imgproxykit.options.Filename(value: ValueT)[source]¶

Set the response filename using URL-safe Base64 encoding.

Sets the filename in the Content-Disposition response header. The name is encoded as URL-safe Base64 automatically. Combine with ReturnAttachment to request downloading in the browser.

value¶

Response filename, supplied as unencoded text.

Type:¶

str

Usage:

>>> option = Filename('product photo.jpg')
>>> option.arguments
('cHJvZHVjdCBwaG90by5qcGc', True)

See imgproxy filename.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

ScalarOption.arguments

name : ClassVar[str] = 'filename'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'fn'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Flip¶

class imgproxykit.options.Flip(*, horizontal: bool | None = None, vertical: bool | None = None)[source]¶

Flip the image horizontally and/or vertically.

Omitted axes remain None and use imgproxy defaults.

horizontal¶

Whether to mirror the image horizontally.

Type:¶

bool | None

vertical¶

Whether to mirror the image vertically.

Type:¶

bool | None

Usage:

>>> option = Flip(horizontal=True)
>>> option.arguments
(True, None)
>>> option = Flip(horizontal=True, vertical=True)
>>> option.arguments
(True, True)

See imgproxy flip.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'flip'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'fl'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Format¶

class imgproxykit.options.Format(value: ValueT)[source]¶

Set the output image format.

value¶

Output format, such as webp or avif.

Type:¶

FormatType

Usage:

>>> option = Format('webp')
>>> option.arguments
('webp',)

See imgproxy format.

name : ClassVar[str] = 'format'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'f'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

FormatQuality¶

class imgproxykit.options.FormatQuality(*, qualities: tuple[tuple[FormatType, int], ...])[source]¶

Set quality for each supplied output format.

Adds or overrides server quality settings for the listed formats.

qualities¶

Ordered pairs of output format and quality percentage.

Type:¶

tuple[tuple[FormatType, int], ...]

Usage:

>>> option = FormatQuality(qualities=(('jpg', 85), ('webp', 80)))
>>> option.arguments
('jpg', 85, 'webp', 80)

See imgproxy format quality.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'format_quality'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'fq'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Gravity¶

class imgproxykit.options.Gravity(*, position: Position, offset_x: float | None = None, offset_y: float | None = None)[source]¶

Choose the image area retained when cropping.

Use readable anchor factories, smart(), or focus(). The constructor also accepts imgproxy position codes directly. Omitted offsets remain None.

position¶

Anchor such as ce (center), sm (smart), or fp (focus point).

Type:¶

Position

offset_x¶

Horizontal offset; with fp, the focus X coordinate.

Type:¶

float | None

offset_y¶

Vertical offset; with fp, the focus Y coordinate.

Type:¶

float | None

Usage:

>>> option = Gravity.center()
>>> option.arguments
('ce', None, None)
>>> option = Gravity.focus(x=0.25, y=0.5)
>>> option.arguments
('fp', 0.25, 0.5)

See imgproxy gravity.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

classmethod bottom(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the bottom edge with optional offsets.

Return type:¶

Self

classmethod bottom_left(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the bottom-left corner with optional offsets.

Return type:¶

Self

classmethod bottom_right(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the bottom-right corner with optional offsets.

Return type:¶

Self

classmethod center(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the center with optional offsets.

Return type:¶

Self

classmethod focus(*, x: float, y: float) → Self[source]¶

Center cropping on focus coordinates in the range [0, 1].

Return type:¶

Self

classmethod left(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the left edge with optional offsets.

Return type:¶

Self

name : ClassVar[str] = 'gravity'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

classmethod right(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the right edge with optional offsets.

Return type:¶

Self

short_name : ClassVar[str | None] = 'g'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

classmethod smart() → Self[source]¶

Let imgproxy select the most interesting image area.

Return type:¶

Self

classmethod top(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the top edge with optional offsets.

Return type:¶

Self

classmethod top_left(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the top-left corner with optional offsets.

Return type:¶

Self

classmethod top_right(*, offset_x: float | None = None, offset_y: float | None = None) → Self[source]¶

Anchor cropping to the top-right corner with optional offsets.

Return type:¶

Self

Height¶

class imgproxykit.options.Height(value: ValueT)[source]¶

Set the target height in pixels.

Zero lets imgproxy calculate height from width and aspect ratio. With force resizing, zero preserves the source height.

value¶

Target height in pixels.

Type:¶

int

Usage:

>>> option = Height(200)
>>> option.arguments
(200,)

See imgproxy height.

name : ClassVar[str] = 'height'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'h'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

KeepCopyright¶

class imgproxykit.options.KeepCopyright(value: ValueT)[source]¶

Preserve copyright information when stripping metadata.

Applies when metadata is being stripped from the output image.

value¶

Whether to retain copyright metadata.

Type:¶

bool

Usage:

>>> option = KeepCopyright(True)
>>> option.arguments
(True,)

See imgproxy keep copyright.

name : ClassVar[str] = 'keep_copyright'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'kcr'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MaxAnimationFrameResolution¶

class imgproxykit.options.MaxAnimationFrameResolution(value: ValueT)[source]¶

Override frame megapixel limit; requires ALLOW_SECURITY_OPTIONS.

Overrides the corresponding server limit for this request. Requires IMGPROXY_ALLOW_SECURITY_OPTIONS set to true on the imgproxy server.

value¶

Animation frame resolution limit in megapixels.

Type:¶

float

Usage:

>>> option = MaxAnimationFrameResolution(20)
>>> option.arguments
(20,)

See imgproxy max animation frame resolution.

name : ClassVar[str] = 'max_animation_frame_resolution'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'mafr'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MaxAnimationFrames¶

class imgproxykit.options.MaxAnimationFrames(value: ValueT)[source]¶

Override animation frame limit; requires ALLOW_SECURITY_OPTIONS.

Overrides the corresponding server limit for this request. Requires IMGPROXY_ALLOW_SECURITY_OPTIONS set to true on the imgproxy server.

value¶

Maximum number of animation frames.

Type:¶

int

Usage:

>>> option = MaxAnimationFrames(100)
>>> option.arguments
(100,)

See imgproxy max animation frames.

name : ClassVar[str] = 'max_animation_frames'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'maf'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MaxBytes¶

class imgproxykit.options.MaxBytes(value: ValueT)[source]¶

Reduce output quality to meet the requested byte limit.

imgproxy may encode the image repeatedly to reduce its quality. Applicable to JPEG, WebP, HEIC, and TIFF output.

value¶

Maximum requested output size in bytes; zero disables it.

Type:¶

int

Usage:

>>> option = MaxBytes(100_000)
>>> option.arguments
(100000,)

See imgproxy max bytes.

name : ClassVar[str] = 'max_bytes'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'mb'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MaxResultDimension¶

class imgproxykit.options.MaxResultDimension(value: ValueT)[source]¶

Override output dimension limit; requires ALLOW_SECURITY_OPTIONS.

Overrides the corresponding server limit for this request. Requires IMGPROXY_ALLOW_SECURITY_OPTIONS set to true on the imgproxy server.

value¶

Maximum resulting width or height in pixels.

Type:¶

int

Usage:

>>> option = MaxResultDimension(4096)
>>> option.arguments
(4096,)

See imgproxy max result dimension.

name : ClassVar[str] = 'max_result_dimension'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'mrd'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MaxSrcFileSize¶

class imgproxykit.options.MaxSrcFileSize(value: ValueT)[source]¶

Override source byte limit; requires ALLOW_SECURITY_OPTIONS.

Overrides the corresponding server limit for this request. Requires IMGPROXY_ALLOW_SECURITY_OPTIONS set to true on the imgproxy server.

value¶

Source file size limit in bytes.

Type:¶

int

Usage:

>>> option = MaxSrcFileSize(10_000_000)
>>> option.arguments
(10000000,)

See imgproxy max src file size.

name : ClassVar[str] = 'max_src_file_size'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'msfs'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MaxSrcResolution¶

class imgproxykit.options.MaxSrcResolution(value: ValueT)[source]¶

Override source megapixel limit; requires ALLOW_SECURITY_OPTIONS.

Overrides the corresponding server limit for this request. Requires IMGPROXY_ALLOW_SECURITY_OPTIONS set to true on the imgproxy server.

value¶

Source resolution limit in megapixels.

Type:¶

float

Usage:

>>> option = MaxSrcResolution(50)
>>> option.arguments
(50,)

See imgproxy max src resolution.

name : ClassVar[str] = 'max_src_resolution'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'msr'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MinHeight¶

class imgproxykit.options.MinHeight(value: ValueT)[source]¶

Set the minimum resulting height in pixels.

Combining this option with a target height can crop the result.

value¶

Minimum resulting height in pixels.

Type:¶

int

Usage:

>>> option = MinHeight(200)
>>> option.arguments
(200,)

See imgproxy min height.

name : ClassVar[str] = 'min-height'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'mh'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

MinWidth¶

class imgproxykit.options.MinWidth(value: ValueT)[source]¶

Set the minimum resulting width in pixels.

Combining this option with a target width can crop the result.

value¶

Minimum resulting width in pixels.

Type:¶

int

Usage:

>>> option = MinWidth(300)
>>> option.arguments
(300,)

See imgproxy min width.

name : ClassVar[str] = 'min-width'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'mw'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Padding¶

class imgproxykit.options.Padding(*, top: int | None = None, right: int | None = None, bottom: int | None = None, left: int | None = None)[source]¶

Add padding using CSS side order; specify at least one side.

Uses CSS side order and is applied after image transformations, except watermarking. Padding follows DPR and uses the background color. Supply at least one side; omitted arguments remain None.

Use all() for uniform padding, symmetric() for separate horizontal and vertical padding, or the constructor for individual sides.

top¶

Top padding in pixels; fallback for omitted sides.

Type:¶

int | None

right¶

Right padding; also used for an omitted left side.

Type:¶

int | None

bottom¶

Bottom padding in pixels.

Type:¶

int | None

left¶

Left padding in pixels.

Type:¶

int | None

Usage:

>>> option = Padding.all(10)
>>> option.arguments
(10, None, None, None)
>>> option = Padding.symmetric(horizontal=20, vertical=10)
>>> option.arguments
(10, 20, None, None)
>>> option = Padding(top=10, right=20, bottom=30, left=40)
>>> option.arguments
(10, 20, 30, 40)

See imgproxy padding.

classmethod all(value: int) → Self[source]¶

Apply the same padding to all sides using protocol fallback.

Return type:¶

Self

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'padding'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'pd'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

classmethod symmetric(*, horizontal: int, vertical: int) → Self[source]¶

Set padding for both axes, requiring both values explicitly.

Return type:¶

Self

Pixelate¶

class imgproxykit.options.Pixelate(value: ValueT)[source]¶

Set the pixelation block size.

Larger blocks produce a coarser pixelation effect.

value¶

Individual pixel block size in pixels.

Type:¶

int

Usage:

>>> option = Pixelate(10)
>>> option.arguments
(10,)

See imgproxy pixelate.

name : ClassVar[str] = 'pixelate'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'pix'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Preset¶

class imgproxykit.options.Preset(*names: str)[source]¶

Reference named presets configured on the imgproxy server.

Names retain their supplied order. Multiple Preset instances remain separate options, preserving their positions among other options. Preset definitions are resolved by the server, not expanded locally.

names¶

Ordered names of server presets to apply.

Type:¶

tuple[str, ...]

Usage:

>>> option = Preset('thumbnail', 'watermarked')
>>> option.arguments
('thumbnail', 'watermarked')

See imgproxy preset.

Store preset names in their supplied order.

Parameters:¶

*names: str¶

Server preset names in imgproxy protocol order.

Examples

Reference a single preset, then several in order:

>>> Preset('thumbnail').arguments
('thumbnail',)
>>> Preset('thumbnail', 'watermarked').arguments
('thumbnail', 'watermarked')

property arguments : tuple[Argument, ...]¶

Preset names in imgproxy protocol order.

Overrides:¶

Option.arguments

name : ClassVar[str] = 'preset'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'pr'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

PreserveHDR¶

class imgproxykit.options.PreserveHDR(value: ValueT)[source]¶

Preserve high bit depth instead of converting to 8 bit.

Overrides the server high bit depth setting for this request.

value¶

Whether to retain high bit depth instead of using 8 bit.

Type:¶

bool

Usage:

>>> option = PreserveHDR(True)
>>> option.arguments
(True,)

See imgproxy preserve hdr.

name : ClassVar[str] = 'preserve_hdr'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'ph'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Quality¶

class imgproxykit.options.Quality(value: ValueT)[source]¶

Set output image quality.

value¶

Quality percentage. Zero delegates to server quality settings.

Type:¶

int

Usage:

>>> option = Quality(85)
>>> option.arguments
(85,)

See imgproxy quality.

name : ClassVar[str] = 'quality'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'q'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

Raw¶

class imgproxykit.options.Raw(value: ValueT)[source]¶

Stream the unchecked source file without processing.

Streams the source without checking its type, resolution, or size. The output is not transformed.

value¶

Whether to stream the raw source file.

Type:¶

bool

Usage:

>>> option = Raw(True)
>>> option.arguments
(True,)

See imgproxy raw.

name : ClassVar[str] = 'raw'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

Resize¶

class imgproxykit.options.Resize(*, width: int | None = None, height: int | None = None, mode: ResizeType | None = None, enlarge: bool | None = None, extend: bool | None = None)[source]¶

Configure image dimensions and resizing behavior.

Values left as None are not supplied explicitly; imgproxy resolves their defaults.

Select a strategy with fit(), fill(), fill_down(), force(), or auto(). Use the constructor when the mode is supplied dynamically or should be left to the server.

width¶

Target width in pixels.

Type:¶

int | None

height¶

Target height in pixels.

Type:¶

int | None

mode¶

Resizing strategy, such as fit or fill.

Type:¶

ResizeType | None

enlarge¶

Allow upscaling smaller source images.

Type:¶

bool | None

extend¶

Pad images that are smaller than the target dimensions.

Type:¶

bool | None

Usage:

>>> option = Resize.fill(width=96, height=96)
>>> option.arguments
('fill', 96, 96, None, None)
>>> option = Resize.fit(width=300, enlarge=False)
>>> option.arguments
('fit', 300, None, False, None)

See imgproxy resize.

property arguments : tuple[Argument, ...]¶

Positional arguments in imgproxy protocol order.

Overrides:¶

Option.arguments

classmethod auto(*, width: int | None = None, height: int | None = None, enlarge: bool | None = None, extend: bool | None = None) → Self[source]¶

Resize using the auto strategy with optional dimensions.

Return type:¶

Self

classmethod fill(*, width: int | None = None, height: int | None = None, enlarge: bool | None = None, extend: bool | None = None) → Self[source]¶

Resize using the fill strategy with optional dimensions.

Return type:¶

Self

classmethod fill_down(*, width: int | None = None, height: int | None = None, enlarge: bool | None = None, extend: bool | None = None) → Self[source]¶

Resize using the fill-down strategy with optional dimensions.

Return type:¶

Self

classmethod fit(*, width: int | None = None, height: int | None = None, enlarge: bool | None = None, extend: bool | None = None) → Self[source]¶

Resize using the fit strategy with optional dimensions.

Return type:¶

Self

classmethod force(*, width: int | None = None, height: int | None = None, enlarge: bool | None = None, extend: bool | None = None) → Self[source]¶

Resize using the force strategy with optional dimensions.

Return type:¶

Self

name : ClassVar[str] = 'resize'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'rs'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.

ResizingType¶

class imgproxykit.options.ResizingType(value: ValueT)[source]¶

Choose the resizing strategy.

Controls how target dimensions and the source aspect ratio interact.

value¶

Resizing strategy: fit, fill, fill-down, force, or auto.

Type:¶

ResizeType

Usage:

>>> option = ResizingType('fill')
>>> option.arguments
('fill',)

See imgproxy resizing type.

name : ClassVar[str] = 'resizing_type'¶

All subtypes must provide a supported imgproxy processing option name.

The name is shared by all instances and is not a dataclass field or a constructor argument.

short_name : ClassVar[str | None] = 'rt'¶

Shortest documented imgproxy alias, or None if none is available.

Like name, this is shared by instances and is not a constructor argument. Use name when no short alias is defined.