Client¶

class imgproxykit.Client(base_url: str, /, *, key: str | None = None, salt: str | None = None, signature_size: int = 32, unsigned_signature: str = 'unsafe', arguments_separator: str = ':') → None[source]¶

Build imgproxy URLs from Python transforms or server presets.

Stores the imgproxy address and signing configuration for reuse across images. Each call to url() returns a URL string; imgproxy loads the source and processes the image when that URL is requested.

Pass processing options through Transform as option instances or scalar keyword arguments. Preset options reference names configured on the imgproxy server.

Subclass this client and override path_serializer_cls or url_signer_cls to customize path construction or signing. Each client creates its own instances of these components.

Configure the imgproxy address and create the client components.

Supply both key and salt for signed URLs. Omit both for URLs with the configured unsigned marker (unsafe by default). The server must accept unsigned requests or trust that marker.

Parameters:¶

base_url: str¶: Public imgproxy address, including any deployment path prefix. Trailing slashes are removed; the address is otherwise stored as supplied, without validation.
key: str | None = None¶: Nonempty hex-encoded signing key matching the server. Supply together with salt; None selects unsigned mode.
salt: str | None = None¶: Nonempty hex-encoded signing salt matching the server. Supply together with key; None selects unsigned mode.
signature_size: int = 32¶: Positive digest byte count to encode. Must match the server’s IMGPROXY_SIGNATURE_SIZE. Defaults to 32. Values of 32 or more use the full digest.
unsigned_signature: str = 'unsafe'¶: URL marker used when key and salt are omitted. Defaults to 'unsafe'. With server signing enabled, configure this marker in IMGPROXY_TRUSTED_SIGNATURES.
arguments_separator: str = ':'¶: Separator between processing option names and their arguments. Must match the server’s IMGPROXY_ARGUMENTS_SEPARATOR. Defaults to ':'.

Raises:¶

ValueError – With the default signer, if only one signing credential is supplied, either is empty or invalid hex, or signature_size is not positive, even in unsigned mode.

Examples

Create an unsigned client:

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

Create a signed client with example credentials:

>>> client = Client(
...     'https://imgproxy.example.com',
...     key='736563726574',
...     salt='73616c74',
... )

path_serializer_cls¶: alias of PathSerializer

url(source: str, *, transform: Transform | None = None) → str[source]¶

Build a URL using processing options and server preset references.

Pass option instances or scalar keyword arguments through Transform. Use Preset to reference server presets. Preset definitions remain on the server and are not expanded here. Set the output format with Transform(format='webp') or a Format option. Omitted processing parameters are left to the server.

Parameters:¶

source: str¶: Complete source URI understood by the imgproxy server. The default serializer encodes its UTF-8 representation as URL-safe Base64 without padding. The URI is neither validated nor resolved against base_url.
transform: Transform | None = None¶: Reusable processing options and optional output format. Omit or pass None to add no processing options.

Return type:¶

str

Returns:¶

The complete imgproxy URL, signed when credentials were supplied or containing the unsigned marker otherwise. No network request is made.

url_signer_cls¶: alias of UrlSigner

variants(source: str, *, variants: Mapping[Key, Transform]) → dict[Key, str][source]¶

Build named URLs for one source using complete transformations.

Parameters:¶

source: str¶: Complete source URI understood by the imgproxy server.
variants: Mapping[Key, Transform]¶: Names mapped to the transformation for each variant. Each transformation is passed unchanged to url().

Return type:¶

dict[TypeVar(Key, bound= str), str]

Returns:¶

A new dictionary preserving the input keys and iteration order. The key type is preserved, including literal string unions. An empty mapping produces an empty dictionary. No network request is made.