Django¶

Requires the django extra. See Django for installation, configuration, and usage.

Client and shortcuts¶

imgproxykit.integrations.django.get_client() → Client[source]¶

Return the cached client configured by IMGPROXYKIT[‘client’].

Create the client on first use. Django’s override_settings clears the cache when entering and leaving an override of IMGPROXYKIT.

Return type:¶

Client

imgproxykit.integrations.django.imgproxy_url(source: str | FieldFile, transform: Transform | str | None = None) → str[source]¶

Build an imgproxy URL using Django’s configured client.

Parameters:¶

source: str | FieldFile¶

Source URI or model file field, passed to the source resolver.

transform: Transform | str | None = None¶

Transformation or name from IMGPROXYKIT['transforms']. Omit to add no processing options.

Return type:¶

str

Returns:¶

Image URL.

Raises:¶

• KeyError – If a named transformation is not configured.

• ValueError – If the default source resolver receives an empty file field.

imgproxykit.integrations.django.imgproxy_variants[Key: str](source: str | FieldFile, variants: Mapping[Key, Transform]) → dict[Key, str][source]¶

imgproxykit.integrations.django.imgproxy_variants[Key: str](source: str | FieldFile, variants: str) → dict[str, str]

Build named image URLs using Django’s configured client.

Parameters:¶

source: str | FieldFile¶

Source URI or model file field, resolved once for all variants.

variants: Mapping[Key, Transform]¶

variants: str

Transformation mapping or set name from IMGPROXYKIT['variants'].

Returns:¶

URLs in variant order. Direct mappings preserve their key type.

Raises:¶

• KeyError – If a named variant set is not configured.

• ValueError – If the default source resolver receives an empty file field.

Source resolution¶

imgproxykit.integrations.django.sources.resolve_source(source: str | FieldFile) → str[source]¶

Resolve an image source using Django’s configured resolver.

Call source_resolver with the original string or file field. The setting accepts a callable or a dotted import path to one. It must return a URI understood by the imgproxy server. This allows projects to resolve relative media URLs or construct storage URIs such as s3://bucket/key without accessing the field’s URL first.

Without a resolver, return strings unchanged and use FieldFile.url for file fields. Relative URLs are not expanded automatically.

Parameters:¶

source: str | FieldFile¶

Source string or model file field, including empty fields.

Return type:¶

str

Returns:¶

Source URI to pass to the configured client.

imgproxykit.integrations.django.sources.default_source_resolver(source: str | FieldFile) → str[source]¶

Return a source string unchanged or use a file field’s storage URL.

Relative URLs are not expanded.

Raises:¶

ValueError – If the file field has no associated file, as with direct access to FieldFile.url.

Return type:¶

str

Settings¶

class imgproxykit.integrations.django.SettingsDict[source]¶

Describe the IMGPROXYKIT dictionary for static type checking.

Extra items:¶

Never

client : Required[ClientSettingsDict]¶

Client constructor options; defaults remain in the core Client.

source_resolver : Callable[[str | FieldFile], str] | str¶

Convert the original source to a URI, including empty file fields.

transforms : Mapping[str, Transform]¶

Named Python transformations, distinct from imgproxy server presets.

variants : Mapping[str, Mapping[str, Transform]]¶

Named sets of transformations; objects can be shared with transforms.

class imgproxykit.integrations.django.ClientSettingsDict[source]¶

Describe client constructor options for static type checking.

Extra items:¶

Never

argument_separator : str¶

Processing argument separator; must match the server.

base_url : Required[str]¶

Public imgproxy address, including any deployment path prefix.

key : str | None¶

Hex-encoded signing key matching the imgproxy server.

salt : str | None¶

Hex-encoded signing salt matching the imgproxy server.

signature_size : int¶

Positive signature digest byte count; must match the server.

source_encoding : SourceEncoding¶

Source URL representation using Base64 or percent-encoded plain mode.

unsigned_marker : str¶

Signature marker used when signing credentials are omitted.

use_short_options : bool¶

Use short processing option aliases when available.

final class imgproxykit.integrations.django.Settings(*values)[source]¶

Name options in Django’s IMGPROXYKIT dictionary.

final class imgproxykit.integrations.django.ClientSettings(*values)[source]¶

Name options in IMGPROXYKIT’s client dictionary.