imgproxykit

A typed Python toolkit for building imgproxy URLs.

Features · Installation · Example · Issues · Contributing

Define image transformations in Python and turn them into reusable, signed URLs. Your imgproxy server fetches and processes the image when the URL is requested.

Features

• Typed API with annotations
• Immutable, reusable transforms built from Python dataclasses
• Free imgproxy processing options, including geometry, filters, metadata, quality, pixel density, gravity, and watermarks
• Output format selection, including WebP and AVIF
• Support for named presets configured on your imgproxy server

Installation

Requires Python 3.12+ and a running imgproxy server.

pip install imgproxykit

Example

Create a client, define a transform, and generate a URL:

>>> from imgproxykit import Client, Transform
>>> from imgproxykit.options import Quality, Resize
>>> client = Client('https://images.example.com')
>>> thumbnail = Transform(
...     options=(
...         Resize(width=300, height=300, mode='fill'),
...         Quality(85),
...     ),
...     format='webp',
... )
>>> url = client.url(
...     'https://example.com/photo.jpg',
...     transform=thumbnail,
... )
>>> url.startswith('https://images.example.com/unsafe/rs:fill:300:300/q:85/')
True
>>> url.endswith('.webp')
True

Reuse client and thumbnail for other source images. Options you omit are left to imgproxy's defaults.

Without signing credentials, URLs use the unsafe marker and require a server with signature checking disabled.

Signed URLs

Supply the hex-encoded key and salt from your imgproxy server configuration:

import os

from imgproxykit import Client

client = Client(
    'https://images.example.com',
    key=os.environ['IMGPROXY_KEY'],
    salt=os.environ['IMGPROXY_SALT'],
)

url = client.url(
    'https://example.com/photo.jpg',
    transform=thumbnail,
)

Both credentials are required together. The client signs each generated path automatically.

Server presets

Already have presets on your imgproxy server? Reference them by name:

url = client.url(
    'https://example.com/photo.jpg',
    presets=('thumbnail', 'watermarked'),
    format='webp',
)

Use either a Python transform or server presets in each call. For Python transforms, set format on Transform; for presets, pass it to client.url().

Contributing

See the contributing guide for development setup and checks. Bug reports and feature requests are welcome on the issue tracker.

License

MIT

Credits

Generated with wemake-python-package (template version).