imgproxykit

A typed Python toolkit for building imgproxy URLs.

Build imgproxy URLs with typed Python options and reusable transformations. Define image settings once, compose them for different use cases, and generate named variants from a single source.

Features

• Fully typed and checked with mypy, pyright, ty and pyrefly in strict modes
• Signed URLs using your imgproxy server's key and salt
• Immutable, reusable transforms combining typed options and scalar arguments
• Variants: generate multiple image URLs from a reusable set of transforms
• Support for named presets configured on your imgproxy server
• Django, Django Modern REST, Django REST Framework, FastAPI, Litestar integration

---

Installation

Requires Python 3.12+. A running imgproxy server is needed to serve images from the generated URLs.

pip install imgproxykit

There are several included extras:

• 'imgproxykit[django]' provides Django and Django-Modern-REST integrations with shortcuts, template tags, and client configuration through Django settings
• 'imgproxykit[drf]' provides Django REST Framework integration with serializer fields for image URLs and named variants
• 'imgproxykit[fastapi]' provides FastAPI integration with a dependency for injecting the client into route handlers
• 'imgproxykit[litestar]' provides Litestar integration with a plugin that injects the client into route handlers

Examples

Generate a thumbnail URL

Build a URL for a cropped webp thumbnail:

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

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

>>> thumbnail = Transform(
...     Resize.fill(width=300, height=300),  # Pass typed option objects.
...     quality=80,  # Or scalar keywords, equivalent to Quality(80).
...     format='webp',
... )

>>> source_url = 'https://originals.example.com/products/backpack.jpg'
>>> thumbnail_url = client.url(source=source_url, transform=thumbnail)

The generated URL has this structure, with the source URL encoded as URL-safe base64:

https://imgproxy.example.com/unsafe/resize:fill:300:300/quality:80/format:webp/<encoded-source>

thumbnail_url points to a cropped webp thumbnail.

Generate image variants

Build variants by extending a shared transform with a width for each size:

>>> from imgproxykit import Client, Transform

>>> client = Client('https://imgproxy.example.com')

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

>>> source_url = 'https://originals.example.com/products/backpack.jpg'
>>> # Build one URL per variant for the same source image.
>>> product_urls = client.variants(source=source_url, variants=products)

product_urls maps each variant name to its generated URL:

{
    'small': 'https://imgproxy.example.com/unsafe/quality:85/format:webp/width:320/<encoded-source>',
    'medium': 'https://imgproxy.example.com/unsafe/quality:85/format:webp/width:640/<encoded-source>',
    'large': 'https://imgproxy.example.com/unsafe/quality:85/format:webp/width:1280/<encoded-source>',
}

Next steps

• Read the documentation for client configuration, transformations, variants, and processing options.
• Check the changelog for new features, fixes, and breaking changes.
• 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).