Extension points¶

Customize URL generation by subclassing these components and assigning them to imgproxykit.Client.path_serializer_cls or imgproxykit.Client.url_signer_cls.

The client passes arguments_separator to the path serializer constructor and key, salt, signature_size, and unsigned_signature to the signer constructor. Custom constructors must accept these keyword arguments.

Path serializer¶

class imgproxykit.serialization.PathSerializer(*, arguments_separator: str) → None[source]¶

Serialize processing options into an unsigned imgproxy path.

Used by Client before signing the resulting path. Sources are encoded as URL-safe Base64 without padding. Processing options are included before the source in the supplied order.

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

Subclass this serializer and override __call__() to customize path construction. Set the subclass on imgproxykit.Client.path_serializer_cls to use it in a client.

Configure processing option serialization.

Parameters:¶

arguments_separator: str¶: Separator between processing option names and their arguments. Must match the server’s IMGPROXY_ARGUMENTS_SEPARATOR.

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

Build an unsigned path using processing options and preset references.

Serialize each option using the configured arguments separator before the encoded source. Output formats are included as processing segments. Omitted processing parameters are left to the server.

Parameters:¶

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

Return type:¶

str

Returns:¶

Unsigned path beginning with /, ready for signing. Contains neither the imgproxy address nor a signature segment.

Examples

Build a square WebP thumbnail path:

>>> from imgproxykit import Transform
>>> from imgproxykit.serialization import PathSerializer
>>> from imgproxykit.options import Resize
>>> serializer = PathSerializer(arguments_separator=':')
>>> thumbnail = Transform(
...     Resize(width=96, height=96, mode='fill'),
...     format='webp',
... )
>>> serializer('s3://images/photo.jpg', transform=thumbnail)
'/resize:fill:96:96/format:webp/czM6Ly9pbWFnZXMvcGhvdG8uanBn'

URL signer¶

class imgproxykit.signing.UrlSigner(*, key: str | None, salt: str | None, signature_size: int, unsigned_signature: str) → None[source]¶

Sign imgproxy paths using a reusable key and salt pair.

Used by Client after path construction. Credentials are decoded once during initialization and reused for subsequent signatures. Passing None for both credentials enables unsigned mode.

Subclass this signer and override __call__() to customize signing. Set the subclass on imgproxykit.Client.url_signer_cls to use it in a client.

Configure signing credentials or enable unsigned mode.

Supply both key and salt to generate signatures. Pass None for both to return the configured unsigned marker. The server must accept unsigned requests or trust that marker.

Parameters:¶

key: str | None¶: Nonempty hex-encoded signing key matching the server. Supply together with salt; None selects unsigned mode.
salt: str | None¶: Nonempty hex-encoded signing salt matching the server. Supply together with key; None selects unsigned mode.
signature_size: int¶: Positive digest byte count to encode. Must match the server’s IMGPROXY_SIGNATURE_SIZE. Values of 32 or more use the full digest.
unsigned_signature: str¶: URL marker used when key and salt are both None. With server signing enabled, configure this marker in IMGPROXY_TRUSTED_SIGNATURES.

Raises:¶

ValueError – If only one signing credential is supplied, either is empty or invalid hex, or signature_size is not positive, even in unsigned mode.

__call__(path: str) → str[source]¶

Sign the exact supplied path or return the unsigned marker.

The signature is an HMAC-SHA256 digest of the salt followed by the UTF-8 encoded path. The path is neither normalized nor modified.

Parameters:¶

path: str¶: Finalized path beginning with /, including processing options, the encoded source, and any output extension. Excludes the server address and signature segment.

Return type:¶

str

Returns:¶

URL-safe Base64 signature without padding, or the unsigned marker when both signing credentials are None.