Image URL Factory

The image URL factory is the single source of truth for constructing, recognizing, extracting from, and rewriting Cloudflare Images delivery URLs. Every place the toolkit produces a delivery URL routes through it, so a single DELIVERY_URL setting (see Configuration) controls the delivery domain for the whole application.

Why it exists

Cloudflare returns image variant URLs on its shared imagedelivery.net domain, and historically the toolkit hardcoded that host in several places. The factory centralizes that logic so admins can serve images from an alternate domain — a native custom domain or a Cloudflare Worker reverse-proxy — without changing application code.

The singleton

A ready-to-use instance is exported from the package root:

from django_cloudflareimages_toolkit import image_url_factory

It reads settings live on every call, so configuration changes (including test overrides) take effect immediately.

Supported URL shapes

The factory produces three shapes, selected purely by configuration (see Configuration for the settings table):

# Default (no DELIVERY_URL)
https://imagedelivery.net/<account_hash>/<image_id>/<variant>

# Native custom domain
https://<domain>/cdn-cgi/imagedelivery/<account_hash>/<image_id>/<variant>

# Worker reverse-proxy
https://<domain>/<image_id>/<variant>

Building URLs

from django_cloudflareimages_toolkit import image_url_factory

# Honors the configured DELIVERY_URL shape.
image_url_factory.build_url("abc123")                 # default variant: "public"
image_url_factory.build_url("abc123", "thumbnail")
image_url_factory.build_url("abc123", "public", account_hash="override-hash")

Rewriting Cloudflare URLs

Cloudflare always returns variant URLs on imagedelivery.net. rewrite_url converts such a URL into the configured shape, preserving any query string (for example signed-URL parameters). It is a no-op when no DELIVERY_URL is configured or when the URL is not a shared-domain delivery URL.

stored = "https://imagedelivery.net/HASH/abc123/public"
image_url_factory.rewrite_url(stored)
# With DELIVERY_URL='images.example.com':
#   https://images.example.com/cdn-cgi/imagedelivery/HASH/abc123/public

This is exactly what CloudflareImage.get_variant_url (and therefore public_url / thumbnail_url) uses internally, so model URL helpers honor the configured domain automatically.

Inspecting URLs

image_url_factory.is_delivery_url(url)     # True for imagedelivery.net OR the configured host
image_url_factory.extract_image_id(url)    # the image id, or None
image_url_factory.split_variant(url)       # (base_without_last_segment, last_segment)

The same helpers back the public CloudflareImageUtils.is_cloudflare_image_url, CloudflareImageUtils.extract_image_id, and CloudflareImageUtils.validate_image_url functions, so they recognize custom delivery domains too.

Recognition only matches the exact delivery host. For a custom domain configured with a path prefix (the default cdn-cgi/imagedelivery), a URL must use that prefix to be treated as a delivery URL — unrelated assets on the same host (for example https://images.example.com/static/logo.png) are left for the regular Image Resizing path instead of being rewritten as flexible variants.

Note

extract_image_id assumes the final path segment is the variant. A custom-path image id (one containing /) used without a variant — e.g. build_url("folder/sub/abc", variant="") — cannot be distinguished from “id + variant” and will not round-trip. Pair custom-path image ids with a variant for reliable extraction and validation.

API reference

class django_cloudflareimages_toolkit.url_factory.CloudflareImageURLFactory(settings: CloudflareImagesSettings | None = None)[source]

Bases: object

Single source of truth for Cloudflare Images delivery URLs.

The factory builds delivery URLs from their components, recognizes whether an arbitrary URL is a delivery URL, extracts the image id from one, and rewrites Cloudflare’s imagedelivery.net URLs into the configured shape.

All behavior is driven by the DELIVERY_URL, DELIVERY_PATH_PREFIX, and DELIVERY_INCLUDE_ACCOUNT_HASH settings. When DELIVERY_URL is not configured, every method preserves the historical imagedelivery.net behavior.

DEFAULT_HOST = 'imagedelivery.net'

DEFAULT_SCHEME = 'https'

__init__(settings: CloudflareImagesSettings | None = None) → None[source]

Initialize the factory.

Parameters:: settings – A settings object exposing delivery_url, delivery_path_prefix, delivery_include_account_hash, and account_hash. Defaults to the global cloudflare_settings singleton.

property uses_custom_domain: bool: Whether an alternate DELIVERY_URL is configured.

property path_prefix: str: Normalized path prefix for custom-domain URLs ("" when default).

property include_account_hash: bool: Whether the account hash appears in the path of built URLs.

base_url(account_hash: str | None = None) → str[source]

Return the delivery URL prefix up to (but excluding) the image id.

Parameters:: account_hash – Override for the account hash. Defaults to cloudflare_settings.account_hash when the configured shape includes the hash.

build_url(image_id: str, variant: str = 'public', account_hash: str | None = None) → str[source]

Build a full delivery URL honoring the configured shape.

Parameters:

image_id – The Cloudflare image id (may contain / for custom paths).
variant – The variant name or flexible-variant options. Pass an empty value to omit the trailing segment entirely. Note that a multi-segment image_id combined with an empty variant does not round-trip through extract_image_id(), which treats the last segment as the variant; pair custom-path ids with a variant.
account_hash – Optional account-hash override.

Returns:

The fully-qualified delivery URL.

is_delivery_url(url: str) → bool[source]

Return True if url is a Cloudflare Images delivery URL.

Recognizes the shared imagedelivery.net host and the configured custom domain (when DELIVERY_URL is set). The host must match exactly — a URL that merely contains imagedelivery.net elsewhere in the path does not qualify — and for a custom domain with a path prefix the URL must use that prefix.

extract_image_id(url: str) → str | None[source]

Extract the image id from a delivery URL, or None.

Handles the shared host, the native custom-domain prefix, and the Worker shape, accounting for whether the account hash is present. Multi-segment (custom-path) image ids are preserved.

Note

The final path segment is assumed to be the variant. A custom-path image id used without a variant (e.g. a URL built via build_url("folder/sub/abc", variant="")) cannot be distinguished from “id + variant” and will lose its last segment here. Pair custom-path ids with a variant for reliable round-tripping.

split_variant(url: str) → tuple[str, str | None][source]

Split a delivery URL into (base_without_last_segment, last_segment).

Useful for swapping a named variant for flexible-variant options. The query string and fragment are dropped from the returned base.

with_options(url: str, options: str) → str[source]

Return a flexible-variant URL applying options to url.

When the delivery URL carries a variant segment, that segment is replaced by options. When it has no variant (e.g. a no-variant custom URL), the options are appended so the image id is preserved rather than overwritten. Query string and fragment are preserved.

rewrite_url(url: str) → str[source]

Rewrite a Cloudflare imagedelivery.net URL into the configured shape.

Cloudflare always returns variant URLs on the shared imagedelivery.net host; this rewrites them to the configured custom domain. The query string and fragment (e.g. signed-URL parameters) are preserved.

Returns the URL unchanged when no DELIVERY_URL is configured or when url is not a shared-host delivery URL.