imgproxykit 0.1.0__py3-none-any.whl

imgproxykit/options/skip_processing.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, FormatType, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SkipProcessing(Option):
+    """
+    Skip processing listed formats when source and output formats match.
+
+    Processing is skipped only when the requested output format matches
+    the source format. Video thumbnail processing cannot be skipped.
+
+    Attributes:
+        formats: Source formats eligible for skipping processing.
+
+    Usage:
+
+    >>> option = SkipProcessing(formats=('svg', 'gif'))
+    >>> option.arguments
+    ('svg', 'gif')
+
+    See `imgproxy skip processing
+    <https://docs.imgproxy.net/usage/processing#skip-processing>`_.
+
+    """
+
+    formats: tuple[FormatType, ...]
+
+    _name: ClassVar[OptionType] = 'skp'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return self.formats

imgproxykit/options/strip_color_profile.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 StripColorProfile(Option):
+    """
+    Convert the embedded profile to sRGB and remove it.
+
+    When enabled, imgproxy converts the embedded ICC profile to sRGB
+    and removes it. Otherwise, imgproxy tries to preserve the profile.
+
+    Attributes:
+        value: Whether to convert and remove the embedded color profile.
+
+    Usage:
+
+    >>> option = StripColorProfile(value=True)
+    >>> option.arguments
+    (True,)
+
+    See `imgproxy strip color profile
+    <https://docs.imgproxy.net/usage/processing#strip-color-profile>`_.
+
+    """
+
+    value: bool
+
+    _name: ClassVar[OptionType] = 'scp'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/strip_metadata.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 StripMetadata(Option):
+    """
+    Remove image metadata.
+
+    Overrides the server metadata stripping setting for this request.
+
+    Attributes:
+        value: Whether to remove EXIF, IPTC, and other image metadata.
+
+    Usage:
+
+    >>> option = StripMetadata(value=True)
+    >>> option.arguments
+    (True,)
+
+    See `imgproxy strip metadata
+    <https://docs.imgproxy.net/usage/processing#strip-metadata>`_.
+
+    """
+
+    value: bool
+
+    _name: ClassVar[OptionType] = 'sm'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/trim.py

@@ -0,0 +1,52 @@
+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 Trim(Option):
+    """
+    Trim the surrounding background with optional color and symmetry.
+
+    Removes the surrounding background before resizing. Trimming loads
+    the full image into memory and is unsupported for animated images.
+    Omitted settings remain :data:`~imgproxykit.types.EMPTY`.
+
+    Attributes:
+        threshold: Color similarity tolerance.
+        color: Optional hex background color; ``FF00FF`` selects
+            transparent backgrounds. Omission enables automatic detection.
+        equal_hor: Trim equal amounts from the left and right sides.
+        equal_ver: Trim equal amounts from the top and bottom sides.
+
+    Usage:
+
+    >>> option = Trim(threshold=10, color='ffffff', equal_hor=True)
+    >>> option.arguments
+    (10, 'ffffff', True, EMPTY)
+
+    See `imgproxy trim
+    <https://docs.imgproxy.net/usage/processing#trim>`_.
+
+    """
+
+    threshold: float
+    color: str | EMPTY = EMPTY
+    equal_hor: bool | EMPTY = EMPTY
+    equal_ver: bool | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 't'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (
+            self.threshold,
+            self.color,
+            self.equal_hor,
+            self.equal_ver,
+        )

imgproxykit/options/watermark.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import EMPTY, Argument, OptionType, WatermarkPosition
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Watermark(Option):
+    """
+    Apply the watermark image configured on the imgproxy server.
+
+    Omitted settings remain :data:`~imgproxykit.types.EMPTY` and are
+    resolved by the server.
+
+    Attributes:
+        opacity: Multiplier applied to the configured base opacity.
+        position: Watermark anchor, or ``re`` to repeat it across the image.
+        offset_x: Horizontal offset, or horizontal spacing when repeating.
+        offset_y: Vertical offset, or vertical spacing when repeating.
+        scale: Size relative to the resulting image. Zero or omission
+            preserves the watermark size.
+
+    Usage:
+
+    >>> option = Watermark(
+    ...     opacity=0.5, position='soea', offset_x=10, offset_y=10
+    ... )
+    >>> option.arguments
+    (0.5, 'soea', 10, 10, EMPTY)
+
+    See `imgproxy watermark
+    <https://docs.imgproxy.net/usage/processing#watermark>`_
+    and `watermark image configuration
+    <https://docs.imgproxy.net/features/watermark#specifying-watermark-image>`_.
+
+    """
+
+    # Public API:
+    opacity: float
+    position: WatermarkPosition | EMPTY = EMPTY
+    offset_x: float | EMPTY = EMPTY
+    offset_y: float | EMPTY = EMPTY
+    scale: float | EMPTY = EMPTY
+
+    # Private API:
+    _name: ClassVar[OptionType] = 'wm'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (
+            self.opacity,
+            self.position,
+            self.offset_x,
+            self.offset_y,
+            self.scale,
+        )

imgproxykit/options/width.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 Width(Option):
+    """
+    Set the target width in pixels.
+
+    Zero lets imgproxy calculate width from height and aspect ratio.
+    With force resizing, zero preserves the source width.
+
+    Attributes:
+        value: Target width in pixels.
+
+    Usage:
+
+    >>> option = Width(value=300)
+    >>> option.arguments
+    (300,)
+
+    See `imgproxy width
+    <https://docs.imgproxy.net/usage/processing#width>`_.
+
+    """
+
+    value: int
+
+    _name: ClassVar[OptionType] = 'w'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/zoom.py

@@ -0,0 +1,45 @@
+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 Zoom(Option):
+    """
+    Multiply dimensions by one factor or separate X and Y factors.
+
+    Unlike DPR, zoom does not scale gravity offsets, watermark offsets,
+    or padding. Factors must be greater than zero.
+
+    Attributes:
+        factor_x: Horizontal multiplier, also used vertically when
+            ``factor_y`` is omitted.
+        factor_y: Optional vertical multiplier.
+
+    Usage:
+
+    >>> option = Zoom(factor_x=2)
+    >>> option.arguments
+    (2, EMPTY)
+    >>> option = Zoom(factor_x=2, factor_y=1.5)
+    >>> option.arguments
+    (2, 1.5)
+
+    See `imgproxy zoom
+    <https://docs.imgproxy.net/usage/processing#zoom>`_.
+
+    """
+
+    factor_x: float
+    factor_y: float | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 'z'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.factor_x, self.factor_y)

imgproxykit/signing.py

@@ -0,0 +1,114 @@
+import contextlib
+import hmac
+
+from imgproxykit.internal.constants import SIGNATURE_DIGEST, UNSAFE
+from imgproxykit.internal.encoding import encode_base64
+from imgproxykit.types import EMPTY
+
+
+class URLSigner:
+    """
+    Sign imgproxy paths using a reusable key and salt pair.
+
+    Used by :class:`~imgproxykit.Client` after path construction.
+    Credentials are decoded once during initialization and reused for
+    subsequent signatures. Omitting both credentials enables unsigned mode.
+
+    Subclass this signer and override :meth:`__call__` to customize signing.
+    Set the subclass on :attr:`imgproxykit.Client.signer_cls` to use it
+    in a client.
+
+    """
+
+    __slots__ = ('_credentials',)
+
+    # Private API:
+    _credentials: tuple[bytes, bytes] | None
+
+    def __init__(
+        self,
+        *,
+        key: str | EMPTY = EMPTY,
+        salt: str | EMPTY = EMPTY,
+    ) -> None:
+        """
+        Configure signing credentials or enable unsigned mode.
+
+        Supply both credentials to generate signatures. Omit both to return
+        the ``unsafe`` marker, for servers with signature checking disabled.
+
+        Args:
+            key: Nonempty hex-encoded signing key matching the server.
+            salt: Nonempty hex-encoded signing salt matching the server.
+
+        Raises:
+            ValueError: If only one credential is supplied, or either
+                credential is empty or contains invalid hexadecimal data.
+
+        Usage:
+
+        >>> from imgproxykit.signing import URLSigner
+        >>> unsigned = URLSigner()
+        >>> signed = URLSigner(
+        ...     key='736563726574',
+        ...     salt='73616c74',
+        ... )
+
+        These credentials are examples for local development.
+
+        """
+        self._credentials = None
+
+        # Omitting both credentials selects unsigned mode.
+        if key is EMPTY and salt is EMPTY:
+            return
+
+        # Signing requires a complete key and salt pair.
+        if key is EMPTY or salt is EMPTY:
+            raise ValueError('key and salt must be supplied together.')
+
+        self._credentials = (
+            self._decode_hex(key),
+            self._decode_hex(salt),
+        )
+
+    def __call__(self, path: str) -> str:
+        """
+        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.
+
+        Args:
+            path: Finalized path beginning with ``/``, including processing
+                options, the encoded source, and any output extension.
+                Excludes the server address and signature segment.
+
+        Returns:
+            URL-safe Base64 signature without padding, or ``unsafe`` when
+            signing credentials were omitted.
+
+        """
+        if self._credentials is None:
+            return UNSAFE
+
+        key, salt = self._credentials
+        signature = hmac.digest(
+            key,
+            salt + path.encode(),
+            SIGNATURE_DIGEST,
+        )
+        return encode_base64(signature)
+
+    def _decode_hex(self, value: str) -> bytes:
+        """
+        Decode a nonempty hexadecimal credential.
+
+        Invalid and empty values raise :class:`ValueError`.
+        """
+        with contextlib.suppress(ValueError):
+            decoded = bytes.fromhex(value)
+            if decoded:
+                return decoded
+
+        raise ValueError('Signing credentials must be nonempty hex strings.')

imgproxykit/transform.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass
+
+from imgproxykit.options import Option
+from imgproxykit.types import EMPTY, FormatType
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Transform:
+    """
+    Define reusable image processing options and an optional output format.
+
+    Instances are immutable and can be reused for multiple source images
+    and clients. Pass a transform to :meth:`imgproxykit.Client.url` to
+    include its processing options and output format in the generated URL.
+
+    Options are serialized in the supplied order. imgproxy determines the
+    image processing pipeline and resolves omitted option arguments using
+    its defaults. Creating a transform does not process an image or make
+    a network request.
+
+    Attributes:
+        options: Tuple of typed processing options. Defaults to an empty
+            tuple, which adds no processing option segments to the URL.
+        format: Output image format, such as ``webp`` or ``avif``.
+            Defaults to :data:`~imgproxykit.types.EMPTY`, leaving format
+            selection to imgproxy.
+
+    Usage:
+
+    >>> from imgproxykit import Client, Transform
+    >>> from imgproxykit.options import Quality, Resize
+    >>> thumbnail = Transform(
+    ...     options=(
+    ...         Resize(width=300, height=300, mode='fill'),
+    ...         Quality(85),
+    ...     ),
+    ...     format='webp',
+    ... )
+    >>> client = Client('https://images.example.com')
+    >>> first_url = client.url(
+    ...     'https://example.com/first.jpg',
+    ...     transform=thumbnail,
+    ... )
+    >>> second_url = client.url(
+    ...     'https://example.com/second.jpg',
+    ...     transform=thumbnail,
+    ... )
+
+    """
+
+    # TODO: Add immutable composition; define duplicate option handling,
+    # format overrides, and explicitly clearing an inherited format.
+    options: tuple[Option, ...] = ()
+    format: FormatType | EMPTY = EMPTY

imgproxykit/types.py

@@ -0,0 +1,95 @@
+from typing import Literal
+
+from imgproxykit.internal.empty import EMPTY as EMPTY  # noqa: PLC0414
+
+type Argument = str | int | float | bool | EMPTY
+type FormatType = Literal[
+    'png',
+    'jpg',
+    'jxl',
+    'webp',
+    'avif',
+    'gif',
+    'ico',
+    'svg',
+    'heic',
+    'bmp',
+    'tiff',
+]
+type OptionType = Literal[
+    'w',
+    'h',
+    'mw',
+    'mh',
+    'rt',
+    'el',
+    'ar',
+    'rot',
+    'bl',
+    'sh',
+    'pix',
+    'sm',
+    'kcr',
+    'scp',
+    'ph',
+    'eth',
+    'mb',
+    'raw',
+    'exp',
+    'att',
+    'msr',
+    'msfs',
+    'maf',
+    'mafr',
+    'mrd',
+    's',
+    'z',
+    'ex',
+    'exar',
+    'c',
+    't',
+    'pd',
+    'fl',
+    'bg',
+    'fq',
+    'skp',
+    'fn',
+    'cb',
+    'rs',
+    'g',
+    'dpr',
+    'q',
+    'wm',
+]
+type WatermarkPosition = Literal[
+    'ce',
+    'no',
+    'so',
+    'ea',
+    'we',
+    'noea',
+    'now',
+    'soea',
+    'sow',
+    're',
+]
+type ResizeType = Literal[
+    'fit',
+    'fill',
+    'fill-down',
+    'force',
+    'auto',
+]
+type Position = Literal[
+    'no',
+    'so',
+    'ea',
+    'we',
+    'noea',
+    'now',
+    'soea',
+    'sow',
+    'ce',
+    'sm',
+    'fp',
+]