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'),
)

Both forms create the same transformation. 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.

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

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