imgproxykit

A typed Python toolkit for building imgproxy URLs.

Features

• Fully typed and checked with mypy, pyright, ty and pyrefly in strict modes
• Expressive transforms: combine option objects with concise scalar arguments
• Immutable, reusable transforms for consistent image settings across your app
• Support for named presets configured on your imgproxy server

Installation

Requires Python 3.12+ and a running imgproxy server.

pip install imgproxykit

Example

Define a WebP thumbnail once and reuse it across a product catalog:

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

# Public URL of your imgproxy server.
client = Client('https://imgproxy.example.com')

thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),  # Pass typed option objects.
    Gravity(position='sm'),  # Let imgproxy choose the crop's focus.
    quality=80,  # Or scalar keywords, equivalent to Quality(80).
    format='webp',
)
source_urls = [
    'https://originals.example.com/products/backpack.jpg',
    'https://originals.example.com/products/sneakers.jpg',
]
# Reuse one immutable transformation across your catalog.
thumbnail_urls = [
    client.url(source=source_url, transform=thumbnail)
    for source_url in source_urls
]

Use these URLs in your images' src attributes. Building a URL makes no network requests: when a browser requests it, imgproxy fetches the original image from originals.example.com and processes it.

Sign URLs and reuse presets configured on your imgproxy server:

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

client = Client(
    'https://imgproxy.example.com',
    # Replace with your imgproxy server's hex-encoded key and salt.
    key='736563726574',
    salt='73616c74',
)

thumbnail = Transform(
    Preset('product-card'),  # Reuse a preset from your imgproxy server.
    format='webp',  # Combine server presets with explicit processing options.
)
source_url = 'https://originals.example.com/products/backpack.jpg'
# The client signs the URL using your server's key and salt.
thumbnail_url = client.url(source=source_url, transform=thumbnail)

See the full documentation for client configuration, transformations, and processing options. Find published releases on PyPI.

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).