imgproxykit 0.1.0__py3-none-any.whl

imgproxykit/options/crop.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import EMPTY, Argument, OptionType, Position
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Crop(Option):
+    """
+    Crop before resizing; dimensions below one are relative.
+
+    Defines the source area to process before resizing. Omitted gravity
+    uses the request gravity; omitted arguments remain
+    :data:`~imgproxykit.types.EMPTY`.
+
+    Attributes:
+        width: Crop width: pixels at or above one, relative below one.
+            Zero uses the full source width.
+        height: Crop height: pixels at or above one, relative below one.
+            Zero uses the full source height.
+        gravity: Crop anchor, such as ``ce`` or ``fp``.
+        offset_x: Horizontal gravity offset or focus X coordinate.
+        offset_y: Vertical gravity offset or focus Y coordinate.
+
+    Usage:
+
+    >>> option = Crop(width=300, height=200, gravity='ce')
+    >>> option.arguments
+    (300, 200, 'ce', EMPTY, EMPTY)
+    >>> option = Crop(
+    ...     width=0.5, height=0.5, gravity='fp', offset_x=0.5, offset_y=0.5
+    ... )
+    >>> option.arguments
+    (0.5, 0.5, 'fp', 0.5, 0.5)
+
+    See `imgproxy crop
+    <https://docs.imgproxy.net/usage/processing#crop>`_.
+
+    """
+
+    width: float | EMPTY = EMPTY
+    height: float | EMPTY = EMPTY
+    gravity: Position | EMPTY = EMPTY
+    offset_x: float | EMPTY = EMPTY
+    offset_y: float | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 'c'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (
+            self.width,
+            self.height,
+            self.gravity,
+            self.offset_x,
+            self.offset_y,
+        )

imgproxykit/options/dpr.py

@@ -0,0 +1,40 @@
+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)
+class DPR(Option):
+    """
+    Scale an image for high pixel density displays.
+
+    The factor also scales gravity offsets, watermark offsets, and padding.
+
+    Attributes:
+        value: Positive pixel density multiplier.
+
+    Usage:
+
+    >>> option = DPR(2)
+    >>> option.arguments
+    (2,)
+
+    See `imgproxy DPR
+    <https://docs.imgproxy.net/usage/processing#dpr>`_.
+
+    """
+
+    # Public API:
+    value: float
+
+    # Private API:
+    _name: ClassVar[OptionType] = 'dpr'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/enforce_thumbnail.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 EnforceThumbnail(Option):
+    """
+    Use an embedded HEIC or AVIF thumbnail when available.
+
+    Uses the embedded thumbnail instead of the main source image
+    when available. Supported for HEIC and AVIF sources.
+
+    Attributes:
+        value: Whether to prefer an embedded thumbnail.
+
+    Usage:
+
+    >>> option = EnforceThumbnail(value=True)
+    >>> option.arguments
+    (True,)
+
+    See `imgproxy enforce thumbnail
+    <https://docs.imgproxy.net/usage/processing#enforce-thumbnail>`_.
+
+    """
+
+    value: bool
+
+    _name: ClassVar[OptionType] = 'eth'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/enlarge.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 Enlarge(Option):
+    """
+    Allow upscaling smaller source images.
+
+    Allows imgproxy to upscale sources smaller than the target dimensions.
+
+    Attributes:
+        value: Whether smaller source images may be enlarged.
+
+    Usage:
+
+    >>> option = Enlarge(value=True)
+    >>> option.arguments
+    (True,)
+
+    See `imgproxy enlarge
+    <https://docs.imgproxy.net/usage/processing#enlarge>`_.
+
+    """
+
+    value: bool
+
+    _name: ClassVar[OptionType] = 'el'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/expires.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 Expires(Option):
+    """
+    Reject the URL after the given Unix timestamp.
+
+    imgproxy returns HTTP 404 after the supplied timestamp has expired.
+
+    Attributes:
+        value: Expiration time as a Unix timestamp in seconds.
+
+    Usage:
+
+    >>> option = Expires(value=1_900_000_000)
+    >>> option.arguments
+    (1900000000,)
+
+    See `imgproxy expires
+    <https://docs.imgproxy.net/usage/processing#expires>`_.
+
+    """
+
+    value: int
+
+    _name: ClassVar[OptionType] = 'exp'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/extend.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import EMPTY, Argument, OptionType, Position
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Extend(Option):
+    """
+    Extend the canvas to the target dimensions.
+
+    Omitted settings remain :data:`~imgproxykit.types.EMPTY`. The default
+    anchor is center without offsets; smart gravity is unsupported.
+
+    Attributes:
+        value: Whether canvas extension is enabled.
+        gravity: Canvas anchor, such as ``ce``, ``so``, or ``fp``.
+        offset_x: Horizontal gravity offset or focus X coordinate.
+        offset_y: Vertical gravity offset or focus Y coordinate.
+
+    Usage:
+
+    >>> option = Extend(value=True, gravity='so')
+    >>> option.arguments
+    (True, 'so', EMPTY, EMPTY)
+
+    See `imgproxy extend
+    <https://docs.imgproxy.net/usage/processing#extend>`_.
+
+    """
+
+    value: bool
+    gravity: Position | EMPTY = EMPTY
+    offset_x: float | EMPTY = EMPTY
+    offset_y: float | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 'ex'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (
+            self.value,
+            self.gravity,
+            self.offset_x,
+            self.offset_y,
+        )

imgproxykit/options/extend_aspect_ratio.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import EMPTY, Argument, OptionType, Position
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExtendAspectRatio(Option):
+    """
+    Extend the canvas to the requested aspect ratio.
+
+    Omitted settings remain :data:`~imgproxykit.types.EMPTY`. The default
+    anchor is center without offsets; smart gravity is unsupported.
+
+    Attributes:
+        value: Whether canvas extension is enabled.
+        gravity: Canvas anchor, such as ``ce``, ``so``, or ``fp``.
+        offset_x: Horizontal gravity offset or focus X coordinate.
+        offset_y: Vertical gravity offset or focus Y coordinate.
+
+    Usage:
+
+    >>> option = ExtendAspectRatio(value=True, gravity='so')
+    >>> option.arguments
+    (True, 'so', EMPTY, EMPTY)
+
+    See `imgproxy extend aspect ratio
+    <https://docs.imgproxy.net/usage/processing#extend-aspect-ratio>`_.
+
+    """
+
+    value: bool
+    gravity: Position | EMPTY = EMPTY
+    offset_x: float | EMPTY = EMPTY
+    offset_y: float | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 'exar'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (
+            self.value,
+            self.gravity,
+            self.offset_x,
+            self.offset_y,
+        )

imgproxykit/options/filename.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.internal.encoding import encode_base64
+from imgproxykit.options.base import Option
+from imgproxykit.types import Argument, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Filename(Option):
+    """
+    Set the response filename using URL-safe Base64 encoding.
+
+    Sets the filename in the Content-Disposition response header.
+    The name is encoded as URL-safe Base64 automatically. Combine with
+    ReturnAttachment to request downloading in the browser.
+
+    Attributes:
+        value: Response filename, supplied as unencoded text.
+
+    Usage:
+
+    >>> option = Filename(value='product photo.jpg')
+    >>> option.arguments
+    ('cHJvZHVjdCBwaG90by5qcGc', True)
+
+    See `imgproxy filename
+    <https://docs.imgproxy.net/usage/processing#filename>`_.
+
+    """
+
+    value: str
+
+    _name: ClassVar[OptionType] = 'fn'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (encode_base64(self.value), True)

imgproxykit/options/flip.py

@@ -0,0 +1,44 @@
+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 Flip(Option):
+    """
+    Flip the image horizontally and/or vertically.
+
+    Omitted axes remain :data:`~imgproxykit.types.EMPTY` and use
+    imgproxy defaults.
+
+    Attributes:
+        horizontal: Whether to mirror the image horizontally.
+        vertical: Whether to mirror the image vertically.
+
+    Usage:
+
+    >>> option = Flip(horizontal=True)
+    >>> option.arguments
+    (True, EMPTY)
+    >>> option = Flip(horizontal=True, vertical=True)
+    >>> option.arguments
+    (True, True)
+
+    See `imgproxy flip
+    <https://docs.imgproxy.net/usage/processing#flip>`_.
+
+    """
+
+    horizontal: bool | EMPTY = EMPTY
+    vertical: bool | EMPTY = EMPTY
+
+    _name: ClassVar[OptionType] = 'fl'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.horizontal, self.vertical)

imgproxykit/options/format_quality.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, FormatType, OptionType
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FormatQuality(Option):
+    """
+    Set quality for each supplied output format.
+
+    Adds or overrides server quality settings for the listed formats.
+
+    Attributes:
+        qualities: Ordered pairs of output format and quality percentage.
+
+    Usage:
+
+    >>> option = FormatQuality(qualities=(('jpg', 85), ('webp', 80)))
+    >>> option.arguments
+    ('jpg', 85, 'webp', 80)
+
+    See `imgproxy format quality
+    <https://docs.imgproxy.net/usage/processing#format-quality>`_.
+
+    """
+
+    qualities: tuple[tuple[FormatType, int], ...]
+
+    _name: ClassVar[OptionType] = 'fq'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return tuple(argument for pair in self.qualities for argument in pair)

imgproxykit/options/gravity.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+from typing import ClassVar, final, override
+
+from imgproxykit.options.base import Option
+from imgproxykit.types import EMPTY, Argument, OptionType, Position
+
+
+@final
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Gravity(Option):
+    """
+    Choose the image area retained when cropping.
+
+    Omitted offsets remain :data:`~imgproxykit.types.EMPTY`.
+
+    Attributes:
+        position: Anchor such as ``ce`` (center), ``sm`` (smart),
+            or ``fp`` (focus point).
+        offset_x: Horizontal offset; with ``fp``, the focus X coordinate.
+        offset_y: Vertical offset; with ``fp``, the focus Y coordinate.
+
+    Usage:
+
+    >>> option = Gravity(position='ce')
+    >>> option.arguments
+    ('ce', EMPTY, EMPTY)
+    >>> option = Gravity(position='fp', offset_x=0.25, offset_y=0.5)
+    >>> option.arguments
+    ('fp', 0.25, 0.5)
+
+    See `imgproxy gravity
+    <https://docs.imgproxy.net/usage/processing#gravity>`_.
+
+    """
+
+    # Public API:
+    position: Position
+    offset_x: float | EMPTY = EMPTY
+    offset_y: float | EMPTY = EMPTY
+
+    # Private API:
+    _name: ClassVar[OptionType] = 'g'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.position, self.offset_x, self.offset_y)

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

imgproxykit/options/keep_copyright.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 KeepCopyright(Option):
+    """
+    Preserve copyright information when stripping metadata.
+
+    Applies when metadata is being stripped from the output image.
+
+    Attributes:
+        value: Whether to retain copyright metadata.
+
+    Usage:
+
+    >>> option = KeepCopyright(value=True)
+    >>> option.arguments
+    (True,)
+
+    See `imgproxy keep copyright
+    <https://docs.imgproxy.net/usage/processing#keep-copyright>`_.
+
+    """
+
+    value: bool
+
+    _name: ClassVar[OptionType] = 'kcr'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/max_animation_frame_resolution.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 MaxAnimationFrameResolution(Option):
+    """
+    Override frame megapixel limit; requires ALLOW_SECURITY_OPTIONS.
+
+    Overrides the corresponding server limit for this request. Requires
+    ``IMGPROXY_ALLOW_SECURITY_OPTIONS=true`` on the imgproxy server.
+
+    Attributes:
+        value: Animation frame resolution limit in megapixels.
+
+    Usage:
+
+    >>> option = MaxAnimationFrameResolution(value=20)
+    >>> option.arguments
+    (20,)
+
+    See `imgproxy max animation frame resolution
+    <https://docs.imgproxy.net/usage/processing#max-animation-frame-resolution>`_.
+
+    """
+
+    value: float
+
+    _name: ClassVar[OptionType] = 'mafr'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/max_animation_frames.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 MaxAnimationFrames(Option):
+    """
+    Override animation frame limit; requires ALLOW_SECURITY_OPTIONS.
+
+    Overrides the corresponding server limit for this request. Requires
+    ``IMGPROXY_ALLOW_SECURITY_OPTIONS=true`` on the imgproxy server.
+
+    Attributes:
+        value: Maximum number of animation frames.
+
+    Usage:
+
+    >>> option = MaxAnimationFrames(value=100)
+    >>> option.arguments
+    (100,)
+
+    See `imgproxy max animation frames
+    <https://docs.imgproxy.net/usage/processing#max-animation-frames>`_.
+
+    """
+
+    value: int
+
+    _name: ClassVar[OptionType] = 'maf'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)

imgproxykit/options/max_bytes.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 MaxBytes(Option):
+    """
+    Reduce output quality to meet the requested byte limit.
+
+    imgproxy may encode the image repeatedly to reduce its quality.
+    Applicable to JPEG, WebP, HEIC, and TIFF output.
+
+    Attributes:
+        value: Maximum requested output size in bytes; zero disables it.
+
+    Usage:
+
+    >>> option = MaxBytes(value=100_000)
+    >>> option.arguments
+    (100000,)
+
+    See `imgproxy max bytes
+    <https://docs.imgproxy.net/usage/processing#max-bytes>`_.
+
+    """
+
+    value: int
+
+    _name: ClassVar[OptionType] = 'mb'
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)