Variants

Variants define a named group of image versions, each with its own transformation. Pass a mapping of names to Transform objects to variants() to generate their URLs together.

Tip

Use the local Docker server on port 8080 for the examples in this chapter.

Generate variants

Define a complete transformation for each name, then generate URLs for a source image:

from imgproxykit import Client, Transform

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Define a complete transformation for each variant name.
products = {
    'small': Transform(width=320),
    'medium': Transform(width=640),
    'large': Transform(width=1280),
}

# Build one URL per variant for the same source image.
product_urls = client.variants(source=source_url, variants=products)
small_url = product_urls['small']  # Access a URL by its variant name.

print(small_url)

product_urls contains a URL for each of the three widths. Access a URL by its name, or pass the dictionary to a template or API response. The names belong to your application; each URL uses its transformation and the client’s signing settings.

Reuse a variant set

Define a set once and reuse it across source images. Shared settings can be composed into each transformation, as described in Transform:

from imgproxykit import Client, Transform

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
dog_source = 'https://picsum.photos/id/237/1600/1200'
pug_source = 'https://picsum.photos/id/1025/1600/1200'

# Share quality and output format across all variants.
base = Transform(quality=85, format='webp')
sizes = {
    'small': Transform(*base.options, width=320),
    'medium': Transform(*base.options, width=640),
    'large': Transform(*base.options, width=1280),
}

# Reuse the same set for different source images.
dog_urls = client.variants(source=dog_source, variants=sizes)
pug_urls = client.variants(source=pug_source, variants=sizes)

print(dog_urls['small'])
print(pug_urls['small'])

Both dictionaries contain the same names and processing settings, with URLs pointing to their respective sources. The shared sizes mapping can be kept at module level and reused across requests.

Type variant names

Annotate the input mapping with a Literal union to check variant names when accessing the generated URLs:

from typing import Literal, assert_type

from imgproxykit import Client, Transform

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Limit the allowed variant names with a literal union.
type ProductKeys = Literal['small', 'medium', 'large']

products: dict[ProductKeys, Transform] = {
    'small': Transform(width=320),
    'medium': Transform(width=640),
    'large': Transform(width=1280),
}

# The returned dictionary preserves the annotated key type.
product_urls = client.variants(source=source_url, variants=products)
assert_type(product_urls, dict[ProductKeys, str])

print(product_urls['small'])

product_urls has type dict[ProductKeys, str]. A type checker accepts product_urls['small'] and reports product_urls['profile'] as an invalid key. Without an explicit key annotation, a regular string-keyed mapping typically produces dict[str, str].

Next steps

See the Client API reference for the complete variants() signature and return type.