imgproxykit 0.1.0__py3-none-any.whl

imgproxykit/__init__.py

@@ -0,0 +1,2 @@
+from imgproxykit.client import Client as Client
+from imgproxykit.transform import Transform as Transform

imgproxykit/builders.py

@@ -0,0 +1,132 @@
+from imgproxykit.internal.constants import PRESET
+from imgproxykit.internal.paths import build_path
+from imgproxykit.internal.serialization import (
+    serialize_option,
+    serialize_segment,
+)
+from imgproxykit.transform import Transform
+from imgproxykit.types import EMPTY, FormatType
+
+
+class PathBuilder:
+    """
+    Resolve processing options and build an unsigned imgproxy path.
+
+    Used by :class:`~imgproxykit.Client` before signing the resulting path.
+    Sources are Base64-encoded without padding; processing options and an
+    optional output extension are included in the same path.
+
+    Python transforms and server presets are mutually exclusive.
+    Preset definitions remain on the imgproxy server.
+
+    Subclass this builder and override :meth:`__call__` to customize path
+    construction. Set the subclass on
+    :attr:`imgproxykit.Client.path_builder_cls` to use it in a client.
+
+    """
+
+    __slots__ = ()
+
+    def __call__(
+        self,
+        source: str,
+        *,
+        transform: Transform | EMPTY = EMPTY,
+        presets: tuple[str, ...] | EMPTY = EMPTY,
+        output_format: FormatType | EMPTY = EMPTY,
+    ) -> str:
+        """
+        Build a path from a Python transform or server preset names.
+
+        Args:
+            source: Complete source URI understood by imgproxy. Its contents
+                are encoded as supplied, without resolving relative paths.
+            transform: Processing options and output format defined in Python.
+                Omit together with ``presets`` to add no processing options.
+            presets: Server preset names in the order they should be supplied.
+                Cannot be combined with ``transform``.
+            output_format: Output extension when using ``presets``.
+                For a Python transform, set its ``format`` instead.
+
+        Returns:
+            Unsigned path beginning with ``/``, ready for signing.
+            Contains neither the imgproxy address nor a signature segment.
+
+        Raises:
+            ValueError: If ``transform`` and ``presets`` are both supplied,
+                or ``output_format`` is supplied without ``presets``.
+
+        Usage:
+
+        >>> from imgproxykit import Transform
+        >>> from imgproxykit.builders import PathBuilder
+        >>> from imgproxykit.options import Resize
+        >>> builder = PathBuilder()
+        >>> source = 'https://example.com/photo.jpg'
+        >>> thumbnail = Transform(
+        ...     options=(Resize(width=96, height=96, mode='fill'),),
+        ...     format='webp',
+        ... )
+        >>> local_path = builder(source, transform=thumbnail)
+        >>> preset_path = builder(
+        ...     source,
+        ...     presets=('thumbnail',),
+        ...     output_format='webp',
+        ... )
+
+        """
+        options, selected_format = self._resolve_options(
+            transform,
+            presets,
+            output_format,
+        )
+        return build_path(
+            source,
+            options=options,
+            output_format=selected_format,
+        )
+
+    def _resolve_options(
+        self,
+        transform: Transform | EMPTY,
+        presets: tuple[str, ...] | EMPTY,
+        output_format: FormatType | EMPTY,
+    ) -> tuple[tuple[str, ...], FormatType | EMPTY]:
+        """
+        Resolve mutually exclusive inputs into path segments and a format.
+
+        Python options are serialized in their supplied order. Server preset
+        names form a single ``pr`` segment. Omitted processing parameters
+        produce no segments and leave the output format unspecified.
+
+        """
+        self._validate_options(transform, presets, output_format)
+        if presets is not EMPTY:
+            return (serialize_segment(PRESET, presets),), output_format
+
+        if transform is EMPTY:
+            return (), EMPTY
+
+        return (
+            tuple(serialize_option(option) for option in transform.options),
+            transform.format,
+        )
+
+    def _validate_options(
+        self,
+        transform: Transform | EMPTY,
+        presets: tuple[str, ...] | EMPTY,
+        output_format: FormatType | EMPTY,
+    ) -> None:
+        """
+        Validate processing options before path serialization.
+
+        Python transforms cannot be combined with server presets.
+        A separate output format is only accepted with server presets.
+
+        """
+        if transform is not EMPTY and presets is not EMPTY:
+            raise ValueError('Choose transform or presets.')
+
+        if presets is EMPTY and output_format is not EMPTY:
+            raise ValueError('Set format on the Python transform.')

imgproxykit/client.py

@@ -0,0 +1,167 @@
+from typing import ClassVar, overload
+
+from imgproxykit.builders import PathBuilder
+from imgproxykit.signing import URLSigner
+from imgproxykit.transform import Transform
+from imgproxykit.types import EMPTY, FormatType
+
+
+class Client:
+    """
+    Build imgproxy URLs from Python transforms or server presets.
+
+    Stores the imgproxy address and signing configuration for reuse across
+    images. Each call to :meth:`url` returns a URL string; imgproxy loads
+    the source and processes the image when that URL is requested.
+
+    Processing parameters can come from a :class:`~imgproxykit.Transform`
+    defined in Python or from preset names configured on the imgproxy server.
+
+    Subclass this client and override :attr:`path_builder_cls` or
+    :attr:`signer_cls` to customize path construction or signing.
+    Each client creates its own instances of these components.
+
+    """
+
+    __slots__ = (
+        '_base_url',
+        '_path_builder',
+        '_signer',
+    )
+
+    #: Component that resolves processing parameters and builds unsigned paths.
+    path_builder_cls: ClassVar[type[PathBuilder]] = PathBuilder
+    #: Component that signs paths or returns the unsigned URL marker.
+    signer_cls: ClassVar[type[URLSigner]] = URLSigner
+
+    @overload
+    def __init__(self, base_url: str, /) -> None: ...
+
+    @overload
+    def __init__(self, base_url: str, /, *, key: str, salt: str) -> None: ...
+
+    def __init__(
+        self,
+        base_url: str,
+        /,
+        *,
+        key: str | EMPTY = EMPTY,
+        salt: str | EMPTY = EMPTY,
+    ) -> None:
+        """
+        Configure the imgproxy address and create the client components.
+
+        Supply both ``key`` and ``salt`` for signed URLs. Omit both for
+        URLs with an ``unsafe`` signature marker, which can be used with
+        an imgproxy server that has signature checking disabled.
+
+        Args:
+            base_url: Public imgproxy address, including any deployment path
+                prefix. Required positional argument. Trailing slashes
+                are removed.
+            key: Hex-encoded signing key matching the server configuration.
+            salt: Hex-encoded signing salt matching the server configuration.
+
+        Raises:
+            ValueError: With the default signer, if only one signing
+                credential is supplied, or either is empty or invalid hex.
+
+        Usage:
+
+        >>> from imgproxykit import Client
+        >>> unsigned = Client('https://images.example.com')
+        >>> signed = Client(
+        ...     'https://images.example.com',
+        ...     key='736563726574',
+        ...     salt='73616c74',
+        ... )
+
+        The signing credentials above are examples for local development.
+
+        """
+        # TODO: Define runtime validation for base URLs and empty sources.
+        self._base_url = base_url.rstrip('/')
+        self._path_builder = self.path_builder_cls()
+        self._signer = self.signer_cls(key=key, salt=salt)
+
+    @overload
+    def url(
+        self,
+        source: str,
+        *,
+        transform: Transform | EMPTY = ...,
+    ) -> str: ...
+
+    @overload
+    def url(
+        self,
+        source: str,
+        *,
+        presets: tuple[str, ...],
+        format: FormatType | EMPTY = EMPTY,
+    ) -> str: ...
+
+    def url(
+        self,
+        source: str,
+        *,
+        transform: Transform | EMPTY = EMPTY,
+        presets: tuple[str, ...] | EMPTY = EMPTY,
+        format: FormatType | EMPTY = EMPTY,  # noqa: A002
+    ) -> str:
+        """
+        Build a URL for one source using a transform or server presets.
+
+        Pass ``transform`` for processing parameters defined in Python.
+        Pass ``presets`` to reference named server presets instead.
+        Preset definitions remain on the server and are not expanded here.
+
+        With a Python transform, set the output format on that transform.
+        With server presets, use the ``format`` argument. Omitted processing
+        parameters and formats are left to the server.
+
+        Args:
+            source: Complete source URI understood by the imgproxy server.
+                The default builder Base64-encodes it without changing its
+                contents or resolving storage-relative paths.
+            transform: Reusable processing options and optional output format.
+                Omitting both ``transform`` and ``presets`` adds no options.
+            presets: Names of server presets, in the supplied order.
+                Mutually exclusive with ``transform``.
+            format: Output format when using ``presets``. Must be omitted
+                when using a Python transform.
+
+        Returns:
+            The complete imgproxy URL, signed when credentials were supplied.
+
+        Raises:
+            ValueError: With the default builder, if ``transform`` and
+                ``presets`` are supplied together, or ``format`` is supplied
+                without ``presets``.
+
+        Usage:
+
+        >>> from imgproxykit import Client, Transform
+        >>> from imgproxykit.options import Resize
+        >>> client = Client('https://images.example.com')
+        >>> thumbnail = Transform(
+        ...     options=(Resize(width=300, height=300, mode='fill'),),
+        ...     format='webp',
+        ... )
+        >>> source = 'https://example.com/photo.jpg'
+        >>> local_options_url = client.url(source, transform=thumbnail)
+        >>> server_presets_url = client.url(
+        ...     source,
+        ...     presets=('thumbnail', 'watermarked'),
+        ...     format='webp',
+        ... )
+
+        """
+        path = self._path_builder(
+            source,
+            transform=transform,
+            presets=presets,
+            output_format=format,
+        )
+        signature = self._signer(path)
+        return f'{self._base_url}/{signature}{path}'

imgproxykit/internal/constants.py

@@ -0,0 +1,8 @@
+from typing import Final
+
+# imgproxy verifies URL signatures using HMAC-SHA256.
+SIGNATURE_DIGEST: Final = 'sha256'
+# A URL still needs a signature segment when server signature checking is off.
+UNSAFE: Final = 'unsafe'
+# imgproxy's short option name for referencing server-side presets.
+PRESET: Final = 'pr'

imgproxykit/internal/empty.py

@@ -0,0 +1,8 @@
+from typing_extensions import Sentinel
+
+# NOTE: this module must not import anything from `imgproxykit`,
+# so it can be used anywhere without creating import cycles.
+
+#: Default singleton for empty values.
+#: Re-exported as ``imgproxykit.types.EMPTY``.
+EMPTY = Sentinel('EMPTY')

imgproxykit/internal/encoding.py

@@ -0,0 +1,13 @@
+import base64
+
+
+def encode_base64(value: str | bytes) -> str:
+    """
+    Encode text or bytes as URL-safe Base64 without padding.
+
+    Text is first encoded as UTF-8. Byte values, such as signature digests,
+    are encoded directly. Trailing ``=`` padding is removed for URL paths.
+
+    """
+    raw = value.encode() if isinstance(value, str) else value
+    return base64.urlsafe_b64encode(raw).rstrip(b'=').decode()

imgproxykit/internal/paths.py

@@ -0,0 +1,21 @@
+from imgproxykit.internal.encoding import encode_base64
+from imgproxykit.types import EMPTY, FormatType
+
+
+def build_path(
+    source: str,
+    *,
+    options: tuple[str, ...],
+    output_format: FormatType | EMPTY = EMPTY,
+) -> str:
+    """
+    Assemble serialized options, an encoded source, and an output extension.
+
+    The leading ``/`` is part of the path supplied to the signer.
+    The source is encoded as URL-safe Base64 without padding. An omitted
+    output format adds no extension, leaving format selection to imgproxy.
+
+    """
+    segments = '/'.join((*options, encode_base64(source)))
+    path = f'/{segments}'
+    return path if output_format is EMPTY else f'{path}.{output_format}'

imgproxykit/internal/serialization.py

@@ -0,0 +1,34 @@
+from imgproxykit.options import Option
+from imgproxykit.types import EMPTY, Argument
+
+
+def serialize_option(option: Option) -> str:
+    """Serialize a typed processing option into an imgproxy path segment."""
+    return serialize_segment(option.name, option.arguments)
+
+
+def serialize_segment(name: str, arguments: tuple[Argument, ...]) -> str:
+    """
+    Serialize an option name and positional arguments into a path segment.
+
+    Internal :data:`~imgproxykit.types.EMPTY` values become empty positions;
+    trailing empty values are omitted. Explicit zeroes and empty strings
+    retain their positions. Booleans are serialized as ``1`` and ``0``.
+
+    """
+    # TODO: Verify reserved characters in string arguments and preset names
+    # against imgproxy before choosing encoding or rejection. Cover colons,
+    # slashes, percent signs, Unicode, and empty strings.
+    end = len(arguments)
+    while end and arguments[end - 1] is EMPTY:
+        end -= 1
+    return ':'.join((name, *map(_serialize_argument, arguments[:end])))
+
+
+def _serialize_argument(value: Argument) -> str:
+    """Serialize one argument without treating false values as omitted."""
+    if value is EMPTY:
+        return ''
+    if isinstance(value, bool):
+        return str(int(value))
+    return str(value)

imgproxykit/options/__init__.py

@@ -0,0 +1,62 @@
+from imgproxykit.options.auto_rotate import AutoRotate as AutoRotate
+from imgproxykit.options.background import Background as Background
+from imgproxykit.options.base import Option as Option
+from imgproxykit.options.blur import Blur as Blur
+from imgproxykit.options.cache_buster import CacheBuster as CacheBuster
+from imgproxykit.options.crop import Crop as Crop
+from imgproxykit.options.dpr import DPR as DPR
+from imgproxykit.options.enforce_thumbnail import (
+    EnforceThumbnail as EnforceThumbnail,
+)
+from imgproxykit.options.enlarge import Enlarge as Enlarge
+from imgproxykit.options.expires import Expires as Expires
+from imgproxykit.options.extend import Extend as Extend
+from imgproxykit.options.extend_aspect_ratio import (
+    ExtendAspectRatio as ExtendAspectRatio,
+)
+from imgproxykit.options.filename import Filename as Filename
+from imgproxykit.options.flip import Flip as Flip
+from imgproxykit.options.format_quality import FormatQuality as FormatQuality
+from imgproxykit.options.gravity import Gravity as Gravity
+from imgproxykit.options.height import Height as Height
+from imgproxykit.options.keep_copyright import KeepCopyright as KeepCopyright
+from imgproxykit.options.max_animation_frame_resolution import (
+    MaxAnimationFrameResolution as MaxAnimationFrameResolution,
+)
+from imgproxykit.options.max_animation_frames import (
+    MaxAnimationFrames as MaxAnimationFrames,
+)
+from imgproxykit.options.max_bytes import MaxBytes as MaxBytes
+from imgproxykit.options.max_result_dimension import (
+    MaxResultDimension as MaxResultDimension,
+)
+from imgproxykit.options.max_src_file_size import (
+    MaxSrcFileSize as MaxSrcFileSize,
+)
+from imgproxykit.options.max_src_resolution import (
+    MaxSrcResolution as MaxSrcResolution,
+)
+from imgproxykit.options.min_height import MinHeight as MinHeight
+from imgproxykit.options.min_width import MinWidth as MinWidth
+from imgproxykit.options.padding import Padding as Padding
+from imgproxykit.options.pixelate import Pixelate as Pixelate
+from imgproxykit.options.preserve_hdr import PreserveHDR as PreserveHDR
+from imgproxykit.options.quality import Quality as Quality
+from imgproxykit.options.raw import Raw as Raw
+from imgproxykit.options.resize import Resize as Resize
+from imgproxykit.options.resizing_type import ResizingType as ResizingType
+from imgproxykit.options.return_attachment import (
+    ReturnAttachment as ReturnAttachment,
+)
+from imgproxykit.options.rotate import Rotate as Rotate
+from imgproxykit.options.sharpen import Sharpen as Sharpen
+from imgproxykit.options.size import Size as Size
+from imgproxykit.options.skip_processing import SkipProcessing as SkipProcessing
+from imgproxykit.options.strip_color_profile import (
+    StripColorProfile as StripColorProfile,
+)
+from imgproxykit.options.strip_metadata import StripMetadata as StripMetadata
+from imgproxykit.options.trim import Trim as Trim
+from imgproxykit.options.watermark import Watermark as Watermark
+from imgproxykit.options.width import Width as Width
+from imgproxykit.options.zoom import Zoom as Zoom

imgproxykit/options/auto_rotate.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import Argument, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AutoRotate(Option):
+    """
+    Apply the source EXIF orientation before processing.
+
+    Overrides automatic EXIF orientation handling for this request.
+    The orientation tag is removed regardless of this setting.
+
+    Attributes:
+        value: Whether to apply the source EXIF orientation.
+
+    Usage:
+
+    >>> option = AutoRotate(value=False)
+    >>> option.arguments
+    (False,)
+
+    See `imgproxy auto rotate
+    <https://docs.imgproxy.net/usage/processing#auto-rotate>`_.
+
+    """
+
+    value: bool
+
+    _name: ClassVar[OptionType] = 'ar'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/background.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import EMPTY, Argument, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Background(Option):
+    """
+    Fill the background with a hex color or RGB tuple; omit to disable.
+
+    Useful when converting transparent images to JPEG. Omit the color
+    to disable background manipulation.
+
+    Attributes:
+        color: Hex color without a leading hash, or an RGB tuple with
+            channel values from 0 to 255. Omission disables filling.
+
+    Usage:
+
+    >>> option = Background(color='ffffff')
+    >>> option.arguments
+    ('ffffff',)
+    >>> option = Background(color=(255, 255, 255))
+    >>> option.arguments
+    (255, 255, 255)
+    >>> option = Background()
+    >>> option.arguments
+    (EMPTY,)
+
+    See `imgproxy background
+    <https://docs.imgproxy.net/usage/processing#background>`_.
+
+    """
+
+    color: str | tuple[int, int, int] | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 'bg'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return self.color if isinstance(self.color, tuple) else (self.color,)

imgproxykit/options/base.py

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from imgproxykit.types import Argument, OptionType
+
+
+class Option(ABC):
+    """
+    Base class for typed imgproxy processing options.
+
+    Concrete options provide a fixed name and positional arguments.
+    Pass their instances to :class:`~imgproxykit.Transform`.
+    This abstract class cannot be instantiated directly.
+
+    Arguments retain :data:`~imgproxykit.types.EMPTY` values until
+    serialization: internal gaps keep their positions, while trailing
+    empty arguments are omitted.
+
+    See `imgproxy processing options
+    <https://docs.imgproxy.net/usage/processing#processing-options>`_.
+
+    """
+
+    __slots__ = ()
+
+    # TODO: Define runtime validation boundaries for processing option values.
+    # TODO: Allow custom option names without type ignores; decide whether
+    # OptionType should remain limited to built-in processing options.
+
+    # Private API:
+    _name: ClassVar[OptionType]
+
+    @property
+    def name(self) -> OptionType:
+        """The fixed imgproxy processing option name."""
+        return self._name
+
+    @property
+    @abstractmethod
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""

imgproxykit/options/blur.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import Argument, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Blur(Option):
+    """
+    Apply Gaussian blur with the given sigma.
+
+    The sigma controls the size of the Gaussian blur mask.
+
+    Attributes:
+        value: Gaussian blur sigma.
+
+    Usage:
+
+    >>> option = Blur(value=2.0)
+    >>> option.arguments
+    (2.0,)
+
+    See `imgproxy blur
+    <https://docs.imgproxy.net/usage/processing#blur>`_.
+
+    """
+
+    value: float
+
+    _name: ClassVar[OptionType] = 'bl'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/cache_buster.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+from urllib.parse import quote
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import Argument, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CacheBuster(Option):
+    """
+    Add an escaped version string to the signed URL to bypass caches.
+
+    Changing the value produces a new URL for browser and CDN caches
+    without changing image processing. Special characters are escaped.
+
+    Attributes:
+        value: Cache version string included in the signed path.
+
+    Usage:
+
+    >>> option = CacheBuster(value='v2')
+    >>> option.arguments
+    ('v2',)
+
+    See `imgproxy cache buster
+    <https://docs.imgproxy.net/usage/processing#cache-buster>`_.
+
+    """
+
+    value: str
+
+    _name: ClassVar[OptionType] = 'cb'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (quote(self.value, safe=''),)