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 empty arguments are omitted.

See imgproxy processing options.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType]¶

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.

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) → None[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.

Parameters:¶

value : ValueT¶

value¶

Whether to apply the source EXIF orientation.

Usage:

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

See imgproxy auto rotate.

name : ClassVar[OptionType] = '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.

Background¶

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

Fill the background with a hex color or RGB tuple; omit to disable.

Useful when converting transparent images to JPEG. Omit the color to disable background manipulation.

Parameters:¶

color : str | tuple[int, int, int] | None¶

color¶

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

Usage:

>>> option = Background(color='ffffff')
>>> option.arguments
('ffffff',)
>>> option = Background(color=(255, 255, 255))
>>> option.arguments
(255, 255, 255)
>>> option = Background()
>>> option.arguments
(None,)

See imgproxy background.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

Blur¶

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

Apply Gaussian blur with the given sigma.

The sigma controls the size of the Gaussian blur mask.

Parameters:¶

value : ValueT¶

value¶

Gaussian blur sigma.

Usage:

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

See imgproxy blur.

name : ClassVar[OptionType] = '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.

CacheBuster¶

class imgproxykit.options.CacheBuster(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Cache version string included in the signed path.

Usage:

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

See imgproxy cache buster.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

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) → 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.

Parameters:¶

width : float | None¶

height : float | None¶

gravity : Position | None¶

offset_x : float | None¶

offset_y : float | None¶

width¶

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

height¶

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

gravity¶

Crop anchor, such as ce or fp.

offset_x¶

Horizontal gravity offset or focus X coordinate.

offset_y¶

Vertical gravity offset or focus Y coordinate.

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.

name : ClassVar[OptionType] = '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.

DPR¶

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

Scale an image for high pixel density displays.

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

Parameters:¶

value : ValueT¶

value¶

Positive pixel density multiplier.

Usage:

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

See imgproxy DPR.

name : ClassVar[OptionType] = '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) → None[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.

Parameters:¶

value : ValueT¶

value¶

Whether to prefer an embedded thumbnail.

Usage:

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

See imgproxy enforce thumbnail.

name : ClassVar[OptionType] = '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.

Enlarge¶

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

Allow upscaling smaller source images.

Allows imgproxy to upscale sources smaller than the target dimensions.

Parameters:¶

value : ValueT¶

value¶

Whether smaller source images may be enlarged.

Usage:

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

See imgproxy enlarge.

name : ClassVar[OptionType] = '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.

Expires¶

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

Reject the URL after the given Unix timestamp.

imgproxy returns HTTP 404 after the supplied timestamp has expired.

Parameters:¶

value : ValueT¶

value¶

Expiration time as a Unix timestamp in seconds.

See imgproxy expires.

name : ClassVar[OptionType] = '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.

Extend¶

class imgproxykit.options.Extend(*, value: bool, gravity: Position | None = None, offset_x: float | None = None, offset_y: float | None = 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.

Parameters:¶

value : bool¶

gravity : Position | None¶

offset_x : float | None¶

offset_y : float | None¶

value¶

Whether canvas extension is enabled.

gravity¶

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

offset_x¶

Horizontal gravity offset or focus X coordinate.

offset_y¶

Vertical gravity offset or focus Y coordinate.

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.

name : ClassVar[OptionType] = '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.

ExtendAspectRatio¶

class imgproxykit.options.ExtendAspectRatio(*, value: bool, gravity: Position | None = None, offset_x: float | None = None, offset_y: float | None = 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.

Parameters:¶

value : bool¶

gravity : Position | None¶

offset_x : float | None¶

offset_y : float | None¶

value¶

Whether canvas extension is enabled.

gravity¶

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

offset_x¶

Horizontal gravity offset or focus X coordinate.

offset_y¶

Vertical gravity offset or focus Y coordinate.

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.

name : ClassVar[OptionType] = '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.

Filename¶

class imgproxykit.options.Filename(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Response filename, supplied as unencoded text.

Usage:

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

See imgproxy filename.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

Flip¶

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

Flip the image horizontally and/or vertically.

Omitted axes remain None and use imgproxy defaults.

Parameters:¶

horizontal : bool | None¶

vertical : bool | None¶

horizontal¶

Whether to mirror the image horizontally.

vertical¶

Whether to mirror the image vertically.

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.

name : ClassVar[OptionType] = '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.

Format¶

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

Set the output image format.

Parameters:¶

value : ValueT¶

value¶

Output format, such as webp or avif.

Usage:

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

See imgproxy format.

name : ClassVar[OptionType] = '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.

FormatQuality¶

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

Set quality for each supplied output format.

Adds or overrides server quality settings for the listed formats.

Parameters:¶

qualities : tuple[tuple[FormatType, int], ...]¶

qualities¶

Ordered pairs of output format and quality percentage.

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.

name : ClassVar[OptionType] = '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.

Gravity¶

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

Choose the image area retained when cropping.

Omitted offsets remain None.

Parameters:¶

position : Position¶

offset_x : float | None¶

offset_y : float | None¶

position¶

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

offset_x¶

Horizontal offset; with fp, the focus X coordinate.

offset_y¶

Vertical offset; with fp, the focus Y coordinate.

Usage:

>>> option = Gravity(position='ce')
>>> option.arguments
('ce', None, None)
>>> option = Gravity(position='fp', offset_x=0.25, offset_y=0.5)
>>> option.arguments
('fp', 0.25, 0.5)

See imgproxy gravity.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

Height¶

class imgproxykit.options.Height(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Target height in pixels.

Usage:

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

See imgproxy height.

name : ClassVar[OptionType] = '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.

KeepCopyright¶

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

Preserve copyright information when stripping metadata.

Applies when metadata is being stripped from the output image.

Parameters:¶

value : ValueT¶

value¶

Whether to retain copyright metadata.

Usage:

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

See imgproxy keep copyright.

name : ClassVar[OptionType] = '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.

MaxAnimationFrameResolution¶

class imgproxykit.options.MaxAnimationFrameResolution(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Animation frame resolution limit in megapixels.

Usage:

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

See imgproxy max animation frame resolution.

name : ClassVar[OptionType] = '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.

MaxAnimationFrames¶

class imgproxykit.options.MaxAnimationFrames(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Maximum number of animation frames.

Usage:

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

See imgproxy max animation frames.

name : ClassVar[OptionType] = '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.

MaxBytes¶

class imgproxykit.options.MaxBytes(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Maximum requested output size in bytes; zero disables it.

Usage:

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

See imgproxy max bytes.

name : ClassVar[OptionType] = '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.

MaxResultDimension¶

class imgproxykit.options.MaxResultDimension(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Maximum resulting width or height in pixels.

Usage:

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

See imgproxy max result dimension.

name : ClassVar[OptionType] = '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.

MaxSrcFileSize¶

class imgproxykit.options.MaxSrcFileSize(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Source file size limit in bytes.

Usage:

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

See imgproxy max src file size.

name : ClassVar[OptionType] = '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.

MaxSrcResolution¶

class imgproxykit.options.MaxSrcResolution(value: ValueT) → None[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.

Parameters:¶

value : ValueT¶

value¶

Source resolution limit in megapixels.

Usage:

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

See imgproxy max src resolution.

name : ClassVar[OptionType] = '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.

MinHeight¶

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

Set the minimum resulting height in pixels.

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

Parameters:¶

value : ValueT¶

value¶

Minimum resulting height in pixels.

Usage:

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

See imgproxy min height.

name : ClassVar[OptionType] = '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.

MinWidth¶

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

Set the minimum resulting width in pixels.

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

Parameters:¶

value : ValueT¶

value¶

Minimum resulting width in pixels.

Usage:

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

See imgproxy min width.

name : ClassVar[OptionType] = '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.

Padding¶

class imgproxykit.options.Padding(*, top: int | None = None, right: int | None = None, bottom: int | None = None, left: int | None = 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.

Parameters:¶

top : int | None¶

right : int | None¶

bottom : int | None¶

left : int | None¶

top¶

Top padding in pixels; fallback for omitted sides.

right¶

Right padding; also used for an omitted left side.

bottom¶

Bottom padding in pixels.

left¶

Left padding in pixels.

Usage:

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

See imgproxy padding.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

Pixelate¶

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

Set the pixelation block size.

Larger blocks produce a coarser pixelation effect.

Parameters:¶

value : ValueT¶

value¶

Individual pixel block size in pixels.

Usage:

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

See imgproxy pixelate.

name : ClassVar[OptionType] = '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.

Preset¶

class imgproxykit.options.Preset(*names: str) → None[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.

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.

name : ClassVar[OptionType] = '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.

PreserveHDR¶

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

Preserve high bit depth instead of converting to 8 bit.

Overrides the server high bit depth setting for this request.

Parameters:¶

value : ValueT¶

value¶

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

Usage:

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

See imgproxy preserve hdr.

name : ClassVar[OptionType] = '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.

Quality¶

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

Set output image quality.

Parameters:¶

value : ValueT¶

value¶

Quality percentage. Zero delegates to server quality settings.

Usage:

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

See imgproxy quality.

name : ClassVar[OptionType] = '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.

Raw¶

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

Stream the unchecked source file without processing.

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

Parameters:¶

value : ValueT¶

value¶

Whether to stream the raw source file.

Usage:

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

See imgproxy raw.

name : ClassVar[OptionType] = '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) → None[source]¶

Configure image dimensions and resizing behavior.

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

Parameters:¶

width : int | None¶

height : int | None¶

mode : ResizeType | None¶

enlarge : bool | None¶

extend : bool | None¶

width¶

Target width in pixels.

height¶

Target height in pixels.

mode¶

Resizing strategy, such as fit or fill.

enlarge¶

Allow upscaling smaller source images.

extend¶

Pad images that are smaller than the target dimensions.

Usage:

>>> option = Resize(width=96, height=96, mode='fill')
>>> option.arguments
('fill', 96, 96, None, None)

See imgproxy resize.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

ResizingType¶

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

Choose the resizing strategy.

Controls how target dimensions and the source aspect ratio interact.

Parameters:¶

value : ValueT¶

value¶

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

Usage:

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

See imgproxy resizing type.

name : ClassVar[OptionType] = '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.

ReturnAttachment¶

class imgproxykit.options.ReturnAttachment(value: ValueT) → None[source]¶

Request attachment disposition for downloading.

Sets attachment disposition so browsers can offer to save the image. Combine with Filename to choose the downloaded filename.

Parameters:¶

value : ValueT¶

value¶

Whether to return an attachment disposition.

Usage:

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

See imgproxy return attachment.

name : ClassVar[OptionType] = 'return_attachment'¶

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.

Rotate¶

class imgproxykit.options.Rotate(value: ValueT) → None[source]¶

Rotate clockwise by a multiple of 90 degrees.

Rotation follows EXIF orientation unless automatic rotation is disabled.

Parameters:¶

value : ValueT¶

value¶

Clockwise angle in degrees; must be a multiple of 90.

Usage:

>>> option = Rotate(90)
>>> option.arguments
(90,)

See imgproxy rotate.

name : ClassVar[OptionType] = '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.

Sharpen¶

class imgproxykit.options.Sharpen(value: ValueT) → None[source]¶

Apply sharpening with the given sigma.

The sigma controls the size of the sharpening mask.

Parameters:¶

value : ValueT¶

value¶

Sharpening filter sigma.

Usage:

>>> option = Sharpen(1.0)
>>> option.arguments
(1.0,)

See imgproxy sharpen.

name : ClassVar[OptionType] = 'sharpen'¶

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.

Size¶

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

Set target dimensions, upscaling, and canvas extension.

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

Parameters:¶

width : int | None¶

height : int | None¶

enlarge : bool | None¶

extend : bool | None¶

width¶

Target width in pixels.

height¶

Target height in pixels.

enlarge¶

Allow upscaling smaller source images.

extend¶

Pad images smaller than the target dimensions.

Usage:

>>> option = Size(width=300, height=200, enlarge=True)
>>> option.arguments
(300, 200, True, None)

See imgproxy size.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = '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.

SkipProcessing¶

class imgproxykit.options.SkipProcessing(*, formats: tuple[FormatType, ...]) → None[source]¶

Skip processing listed formats when source and output formats match.

Processing is skipped only when the requested output format matches the source format. Video thumbnail processing cannot be skipped.

Parameters:¶

formats : tuple[FormatType, ...]¶

formats¶

Source formats eligible for skipping processing.

Usage:

>>> option = SkipProcessing(formats=('svg', 'gif'))
>>> option.arguments
('svg', 'gif')

See imgproxy skip processing.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = 'skip_processing'¶

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.

StripColorProfile¶

class imgproxykit.options.StripColorProfile(value: ValueT) → None[source]¶

Convert the embedded profile to sRGB and remove it.

When enabled, imgproxy converts the embedded ICC profile to sRGB and removes it. Otherwise, imgproxy tries to preserve the profile.

Parameters:¶

value : ValueT¶

value¶

Whether to convert and remove the embedded color profile.

Usage:

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

See imgproxy strip color profile.

name : ClassVar[OptionType] = 'strip_color_profile'¶

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.

StripMetadata¶

class imgproxykit.options.StripMetadata(value: ValueT) → None[source]¶

Remove image metadata.

Overrides the server metadata stripping setting for this request.

Parameters:¶

value : ValueT¶

value¶

Whether to remove EXIF, IPTC, and other image metadata.

Usage:

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

See imgproxy strip metadata.

name : ClassVar[OptionType] = 'strip_metadata'¶

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.

Trim¶

class imgproxykit.options.Trim(*, threshold: float, color: str | None = None, equal_hor: bool | None = None, equal_ver: bool | None = None) → None[source]¶

Trim the surrounding background with optional color and symmetry.

Removes the surrounding background before resizing. Trimming loads the full image into memory and is unsupported for animated images. Omitted settings remain None.

Parameters:¶

threshold : float¶

color : str | None¶

equal_hor : bool | None¶

equal_ver : bool | None¶

threshold¶

Color similarity tolerance.

color¶

Optional hex background color; FF00FF selects transparent backgrounds. Omission enables automatic detection.

equal_hor¶

Trim equal amounts from the left and right sides.

equal_ver¶

Trim equal amounts from the top and bottom sides.

Usage:

>>> option = Trim(threshold=10, color='ffffff', equal_hor=True)
>>> option.arguments
(10, 'ffffff', True, None)

See imgproxy trim.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = 'trim'¶

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.

Watermark¶

class imgproxykit.options.Watermark(*, opacity: float, position: WatermarkPosition | None = None, offset_x: float | None = None, offset_y: float | None = None, scale: float | None = None) → None[source]¶

Apply the watermark image configured on the imgproxy server.

Omitted settings remain None and are resolved by the server.

Parameters:¶

opacity : float¶

position : WatermarkPosition | None¶

offset_x : float | None¶

offset_y : float | None¶

scale : float | None¶

opacity¶

Multiplier applied to the configured base opacity.

position¶

Watermark anchor, or re to repeat it across the image.

offset_x¶

Horizontal offset, or horizontal spacing when repeating.

offset_y¶

Vertical offset, or vertical spacing when repeating.

scale¶

Size relative to the resulting image. Zero or omission preserves the watermark size.

Usage:

>>> option = Watermark(
...     opacity=0.5, position='soea', offset_x=10, offset_y=10
... )
>>> option.arguments
(0.5, 'soea', 10, 10, None)

See imgproxy watermark and watermark image configuration.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = 'watermark'¶

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.

Width¶

class imgproxykit.options.Width(value: ValueT) → None[source]¶

Set the target width in pixels.

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

Parameters:¶

value : ValueT¶

value¶

Target width in pixels.

Usage:

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

See imgproxy width.

name : ClassVar[OptionType] = '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.

Zoom¶

class imgproxykit.options.Zoom(*, factor_x: float, factor_y: float | None = None) → None[source]¶

Multiply dimensions by one factor or separate X and Y factors.

Unlike DPR, zoom does not scale gravity offsets, watermark offsets, or padding. Factors must be greater than zero.

Parameters:¶

factor_x : float¶

factor_y : float | None¶

factor_x¶

Horizontal multiplier, also used vertically when factor_y is omitted.

factor_y¶

Optional vertical multiplier.

Usage:

>>> option = Zoom(factor_x=2)
>>> option.arguments
(2, None)
>>> option = Zoom(factor_x=2, factor_y=1.5)
>>> option.arguments
(2, 1.5)

See imgproxy zoom.

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

Positional arguments in imgproxy protocol order.

name : ClassVar[OptionType] = 'zoom'¶

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.