Transformations

A Transform collects the processing options used to build an imgproxy URL. Pass it to url() through the transform argument.

Create a transformation

Pass option instances as positional arguments. Scalar options, such as quality and output format, can also be supplied as keyword arguments:

from imgproxykit import Transform
from imgproxykit.options import Format, Quality, Resize

thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),
    quality=85,
    format='webp',
)
explicit = Transform(
    Resize(width=300, height=300, mode='fill'),
    Quality(85),
    Format('webp'),
)

thumbnail and explicit contain the same resize, quality, and format options. Use option instances for structured settings such as Resize; choose either form for scalar options such as Quality and Format.

See Transform for the supported scalar keyword arguments and Processing options for option constructors.

Reuse and immutability

Create a transformation once and reuse it for multiple source images:

from imgproxykit import Client, Transform
from imgproxykit.options import Resize

client = Client('https://imgproxy.example.com')
# Reuse the same transformation for multiple source images.
thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),
    format='webp',
)

source_urls = [
    'https://originals.example.com/sneakers.jpg',
    'https://originals.example.com/backpack.jpg',
]
thumbnail_urls = [
    client.url(source=source_url, transform=thumbnail)
    for source_url in source_urls
]

Transform is immutable: its options attribute is a tuple and cannot be reassigned. Built-in option instances are immutable too. Building a URL does not change the transformation.

Both URLs use the same 300 by 300 crop and WebP output for different source images.

To use different settings, create another Transform. There is currently no API for replacing or removing options from an existing transformation.

Compose transformations

Group shared settings in a transformation, then unpack its options into new transformations. For example, product thumbnails and avatars can share quality and output format while using different dimensions:

from imgproxykit import Transform
from imgproxykit.options import Resize

base = Transform(quality=85, format='webp')

product_thumbnail = Transform(*base.options, width=320)
avatar = Transform(
    *base.options,
    Resize(width=96, height=96, mode='fill'),
)

Each new transformation contains the shared options followed by its own options. base remains unchanged. You can unpack more than one transformation when combining reusable groups of options.

Unpacking appends options; it does not merge or replace them. For example, Transform(*product_thumbnail.options, width=640) retains both width options. When sharing settings across sizes, keep the shared transformation focused on settings such as quality and format, and specify dimensions in each complete transformation.

Use Variants to group complete transformations under names and build their URLs together.

Option order

Positional options retain their supplied order. Scalar keyword options are appended after them, in keyword order. Repeated options are preserved:

from imgproxykit import Client, Transform
from imgproxykit.options import Quality

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

transform = Transform(Quality(80), Quality(90), quality=85)
imgproxy_url = client.url(source=source_url, transform=transform)

This produces the processing segments quality:80/quality:90/quality:85. The library does not merge them or resolve conflicts locally.

Note

Option order controls serialization into the URL, including its signature. It does not define a sequence of image processing operations. Imgproxy determines the processing pipeline and interprets repeated or overlapping settings, such as Resize together with Width.

Server presets

Use Preset to reference presets configured on your imgproxy server. A single option can reference several names:

from imgproxykit import Client, Transform
from imgproxykit.options import Preset

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

thumbnail = Transform(
    Preset('thumbnail', 'watermarked'),
    quality=85,
    format='webp',
)
thumbnail_url = client.url(source=source_url, transform=thumbnail)

This produces preset:thumbnail:watermarked/quality:85/format:webp before the encoded source.

Important

Configure both named presets on your server before using this example.

Preset names retain their order. A Preset can appear among other option instances, and multiple Preset instances remain separate URL segments. The library does not load preset definitions or expand them into options; the server resolves their settings together with the other processing options.

No explicit processing options

Omit transform, pass None, or supply an empty Transform to generate a URL without processing option segments:

from imgproxykit import Client, Transform

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

default_url = client.url(source=source_url)
none_url = client.url(source=source_url, transform=None)
empty_url = client.url(source=source_url, transform=Transform())

These calls produce the same URL.

Note

Imgproxy determines the resulting image using its server defaults; an empty transformation does not request an unchanged copy of the source.

Next steps