Options¶

Options define individual processing settings, such as image dimensions, quality, and crop position. Import option classes from imgproxykit.options and combine their instances in a Transform. Simple settings can also be passed as keyword arguments.

Tip

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

Scalar options¶

Scalar options accept a single value. Pass an option instance to Transform, or use the equivalent keyword argument:

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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

optimized = Transform(
    Quality(85),  # (1)!
    Format('webp'),
)
keyword_optimized = Transform(quality=85, format='webp')  # (2)!

image_url = client.url(source=source_url, transform=optimized)
keyword_url = client.url(source=source_url, transform=keyword_optimized)

print('Option instance:', image_url)
print('Keyword:', keyword_url)

Pass scalar options as instances of Quality and Format.
Use keyword arguments to create the same options.

Show Output

Option instance: http://localhost:8080/unsafe/quality:85/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Keyword: http://localhost:8080/unsafe/quality:85/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Both transformations generate the same URL. Option instances and keyword arguments can also be combined in one transformation.

Structured options¶

Structured options group related settings in named arguments. For example, Resize combines dimensions and resizing mode, while Gravity selects the crop position:

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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

thumbnail = Transform(
    Resize.fill(width=300, height=300),  # (1)!
    Gravity.center(),  # (2)!
    dpr=2,  # (3)!
)

thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

Request a square crop using the fill strategy.
Keep the center when cropping.
Request twice the pixel density using a scalar keyword.

Show Output

http://localhost:8080/unsafe/resize:fill:300:300/gravity:ce/dpr:2/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Pass structured options as positional arguments; scalar keywords can follow them.

Omitted arguments¶

Omit an argument to leave it to imgproxy. Explicit False and zero values are preserved:

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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

default = Transform(Resize.fit(width=300))  # (1)!
no_enlarge = Transform(Resize.fit(width=300, enlarge=False))  # (2)!

default_url = client.url(source=source_url, transform=default)
no_enlarge_url = client.url(source=source_url, transform=no_enlarge)

print('Omitted:', default_url)
print('Explicit False:', no_enlarge_url)

Leave the upscaling setting to the server.
Explicitly disable upscaling. The path preserves the empty height position and serializes False as 0.

Show Output

Omitted: http://localhost:8080/unsafe/resize:fit:300/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Explicit False: http://localhost:8080/unsafe/resize:fit:300::0/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Server presets¶

Preset references processing settings defined on the imgproxy server. Pass preset names as positional arguments and combine them with other options:

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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

thumbnail = Transform(
    Preset('thumbnail', 'small'),  # (1)!
    quality=85,  # (2)!
    format='webp',
)

thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

Reference presets defined on the guide’s Docker server: thumbnail is a 300×300 crop and small is a 96×96 crop.
Combine preset references with explicit quality and output format.

Show Output

http://localhost:8080/unsafe/preset:thumbnail:small/quality:85/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

The library sends preset names in the supplied order. Imgproxy resolves their definitions on the server.

Available options¶

Built-in options cover resizing and cropping, formats and quality, effects, metadata, source limits, and URL behavior. For example, Blur adds blur, Background sets a background color, and Filename sets the download filename. See the Options API reference for the full list and constructor arguments.

Some options require server configuration. For example, source limit options require IMGPROXY_ALLOW_SECURITY_OPTIONS=true. Supported formats and processing features depend on your imgproxy installation; type annotations do not check server capabilities. See the imgproxy configuration documentation for server settings.

Next steps¶

Continue with Variants to generate named sets of image URLs. See the Options API reference for all processing options and their arguments.