Extension points¶

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

Path serializer¶

class imgproxykit.serialization.PathSerializer(*, argument_separator: str, use_short_options: bool, source_encoding: SourceEncoding)[source]¶

Serialize processing options into an unsigned imgproxy path.

Used by Client before signing the resulting path. Sources use URL-safe Base64 without padding or full percent-encoding. Processing options precede 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 options and select the source URL serializer.

Parameters:¶

argument_separator: str¶

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

use_short_options: bool¶

Use short aliases when available, otherwise full names.

source_encoding: SourceEncoding¶

Source URL representation: 'base64' without padding or 'plain' with full UTF-8 percent-encoding. See imgproxy source URLs.

__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. Encoded according to source_encoding.

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(
...     argument_separator=':',
...     use_short_options=False,
...     source_encoding='base64',
... )
>>> thumbnail = Transform(
...     Resize.fill(width=96, height=96),
...     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_marker: str)[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_marker: 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.

Dataclass variants resolver¶

class imgproxykit.variants.DataclassVariantsResolver(*, model: type[DataclassInstance])[source]¶

Validate a dataclass variant declaration and resolve its transformations.

Each constructor field must be annotated with Annotated[str, Transform(...)] and contain exactly one Transform. Other annotation metadata is ignored. InitVar and fields declared with init=False are unsupported.

This component only resolves the declaration. URL generation and result construction are handled by imgproxykit.Client.variants().

__call__() → dict[str, Transform][source]¶

Resolve transformations in dataclass field order.

Return type:¶

dict[str, Transform]

Returns:¶

A new mapping from result field names to their transformations.

Raises:¶

• TypeError – If the declaration contains unsupported fields, invalid field annotations, or ambiguous transformations.

• NameError – If a forward reference in the annotations cannot be resolved in the model’s defining namespace.

model : type[_typeshed.DataclassInstance]¶

Dataclass class whose fields declare the named image variants.