imgproxykit 0.1.0__tar.gz → 0.2.1__tar.gz

imgproxykit-0.2.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: imgproxykit
+Version: 0.2.1
+Summary: A typed Python toolkit for building imgproxy URLs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: image-processing,image-transformation,images,imgproxy,url-builder
+Author: Alexander Kondratev
+Author-email: mail@kondratev.dev
+Requires-Python: >=3.12,<4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: typing-extensions (>=4.16,<5)
+Project-URL: Changelog, https://github.com/kondratevdev/imgproxykit/releases
+Project-URL: GitHub, https://github.com/kondratevdev/imgproxykit
+Project-URL: Issues, https://github.com/kondratevdev/imgproxykit/issues
+Description-Content-Type: text/markdown
+
+<h1 align="center">imgproxykit</h1>
+
+<p align="center">
+  <em>A typed Python toolkit for building imgproxy URLs.</em>
+</p>
+
+<div align="center">
+
+[![Tests Result](https://img.shields.io/github/actions/workflow/status/kondratevdev/imgproxykit/test.yml?branch=master&label=tests&labelColor=black&color=blue)](https://github.com/kondratevdev/imgproxykit/actions/workflows/test.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/imgproxykit.svg?labelColor=black&color=blue)](https://pypi.org/project/imgproxykit/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/imgproxykit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/imgproxykit)
+[![Supported Python Version](https://img.shields.io/pypi/pyversions/imgproxykit.svg?labelColor=black&color=blue)](https://pypi.org/project/imgproxykit/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?labelColor=black)](LICENSE)
+
+</div>
+
+## Features
+
+- [x] Fully typed and checked with `mypy`, `pyright`, `ty` and `pyrefly` in strict modes
+- [x] Expressive transforms: combine option objects with concise scalar arguments
+- [x] Immutable, reusable transforms for consistent image settings across your app
+- [x] Support for named presets configured on your imgproxy server
+
+---------
+
+## Installation
+
+Requires **Python 3.12+** and a running imgproxy server.
+
+```bash
+pip install imgproxykit
+```
+
+## Example
+
+Define a WebP thumbnail once and reuse it across a product catalog:
+
+```python
+from imgproxykit import Client, Transform
+from imgproxykit.options import Gravity, Resize
+
+client = Client('https://imgproxy.your-app.com')  # Your imgproxy server.
+
+thumbnail = Transform(
+    Resize(width=300, height=300, mode='fill'),  # Pass option objects.
+    Gravity(position='sm'),  # Let imgproxy choose the crop's focus.
+    quality=80,  # Or scalar, equivalent to Quality(80).
+    format='webp',
+)
+sources = [
+    'https://example.com/products/backpack.jpg',
+    'https://example.com/products/sneakers.jpg',
+]
+thumbnail_urls = [client.url(source, transform=thumbnail) for source in sources]
+```
+
+Use these URLs in your images' `src` attributes; imgproxy handles processing.
+
+Sign URLs and reuse presets configured on your imgproxy server:
+
+```python
+from imgproxykit import Client, Transform
+from imgproxykit.options import Preset
+
+client = Client(
+    'https://imgproxy.your-app.com',
+    key='736563726574',  # Example hex credentials; use your server's values.
+    salt='73616c74',
+)
+
+thumbnail = Transform(
+    Preset(names=('product-card',)),
+    format='webp',
+)
+thumbnail_url = client.url(
+    'https://example.com/products/backpack.jpg',
+    transform=product_card,
+)
+```
+
+## Contributing
+
+See the [contributing guide](CONTRIBUTING.md) for development setup and checks.
+Bug reports and feature requests are welcome on the
+[issue tracker](https://github.com/kondratevdev/imgproxykit/issues).
+
+## License
+
+[MIT](LICENSE)
+
+## Credits
+
+Generated with
+[`wemake-python-package`](https://github.com/wemake-services/wemake-python-package)
+([template version](https://github.com/wemake-services/wemake-python-package/tree/47d9dddd29da8d6d3d1a403f8a143b323a812083)).
+

imgproxykit-0.2.1/README.md

@@ -0,0 +1,95 @@
+<h1 align="center">imgproxykit</h1>
+
+<p align="center">
+  <em>A typed Python toolkit for building imgproxy URLs.</em>
+</p>
+
+<div align="center">
+
+[![Tests Result](https://img.shields.io/github/actions/workflow/status/kondratevdev/imgproxykit/test.yml?branch=master&label=tests&labelColor=black&color=blue)](https://github.com/kondratevdev/imgproxykit/actions/workflows/test.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/imgproxykit.svg?labelColor=black&color=blue)](https://pypi.org/project/imgproxykit/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/imgproxykit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/imgproxykit)
+[![Supported Python Version](https://img.shields.io/pypi/pyversions/imgproxykit.svg?labelColor=black&color=blue)](https://pypi.org/project/imgproxykit/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?labelColor=black)](LICENSE)
+
+</div>
+
+## Features
+
+- [x] Fully typed and checked with `mypy`, `pyright`, `ty` and `pyrefly` in strict modes
+- [x] Expressive transforms: combine option objects with concise scalar arguments
+- [x] Immutable, reusable transforms for consistent image settings across your app
+- [x] Support for named presets configured on your imgproxy server
+
+---------
+
+## Installation
+
+Requires **Python 3.12+** and a running imgproxy server.
+
+```bash
+pip install imgproxykit
+```
+
+## Example
+
+Define a WebP thumbnail once and reuse it across a product catalog:
+
+```python
+from imgproxykit import Client, Transform
+from imgproxykit.options import Gravity, Resize
+
+client = Client('https://imgproxy.your-app.com')  # Your imgproxy server.
+
+thumbnail = Transform(
+    Resize(width=300, height=300, mode='fill'),  # Pass option objects.
+    Gravity(position='sm'),  # Let imgproxy choose the crop's focus.
+    quality=80,  # Or scalar, equivalent to Quality(80).
+    format='webp',
+)
+sources = [
+    'https://example.com/products/backpack.jpg',
+    'https://example.com/products/sneakers.jpg',
+]
+thumbnail_urls = [client.url(source, transform=thumbnail) for source in sources]
+```
+
+Use these URLs in your images' `src` attributes; imgproxy handles processing.
+
+Sign URLs and reuse presets configured on your imgproxy server:
+
+```python
+from imgproxykit import Client, Transform
+from imgproxykit.options import Preset
+
+client = Client(
+    'https://imgproxy.your-app.com',
+    key='736563726574',  # Example hex credentials; use your server's values.
+    salt='73616c74',
+)
+
+thumbnail = Transform(
+    Preset(names=('product-card',)),
+    format='webp',
+)
+thumbnail_url = client.url(
+    'https://example.com/products/backpack.jpg',
+    transform=product_card,
+)
+```
+
+## Contributing
+
+See the [contributing guide](CONTRIBUTING.md) for development setup and checks.
+Bug reports and feature requests are welcome on the
+[issue tracker](https://github.com/kondratevdev/imgproxykit/issues).
+
+## License
+
+[MIT](LICENSE)
+
+## Credits
+
+Generated with
+[`wemake-python-package`](https://github.com/wemake-services/wemake-python-package)
+([template version](https://github.com/wemake-services/wemake-python-package/tree/47d9dddd29da8d6d3d1a403f8a143b323a812083)).

imgproxykit-0.2.1/imgproxykit/client.py

@@ -0,0 +1,153 @@
+from typing import ClassVar, overload
+
+from imgproxykit.serialization import PathSerializer
+from imgproxykit.signing import UrlSigner
+from imgproxykit.transform import Transform
+
+
+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.
+
+    Pass processing options through :class:`~imgproxykit.Transform` as
+    option instances or scalar keyword arguments. Preset options reference
+    names configured on the imgproxy server.
+
+    Subclass this client and override :attr:`path_serializer_cls` or
+    :attr:`url_signer_cls` to customize path construction or signing.
+    Each client creates its own instances of these components.
+
+    """
+
+    __slots__ = (
+        '_base_url',
+        '_path_serializer',
+        '_url_signer',
+    )
+
+    #: Component that resolves processing parameters and builds unsigned paths.
+    path_serializer_cls: ClassVar[type[PathSerializer]] = PathSerializer
+    #: Component that signs paths or returns the unsigned URL marker.
+    url_signer_cls: ClassVar[type[UrlSigner]] = UrlSigner
+
+    @overload
+    def __init__(
+        self,
+        base_url: str,
+        /,
+        *,
+        key: None = None,
+        salt: None = None,
+        unsigned_signature: str = 'unsafe',
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        base_url: str,
+        /,
+        *,
+        key: str,
+        salt: str,
+        signature_size: int = 32,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        base_url: str,
+        /,
+        *,
+        key: str | None = None,
+        salt: str | None = None,
+        signature_size: int = 32,
+        unsigned_signature: str = 'unsafe',
+    ) -> None:
+        """
+        Configure the imgproxy address and create the client components.
+
+        Supply both ``key`` and ``salt`` for signed URLs. Omit both for
+        URLs with the configured unsigned marker (``unsafe`` by default).
+        The server must accept unsigned requests or trust that marker.
+
+        Args:
+            base_url: Public imgproxy address, including any deployment path
+                prefix. Trailing slashes are removed; the address is otherwise
+                stored as supplied, without validation.
+            key: Nonempty hex-encoded signing key matching the server.
+                Supply together with ``salt``; ``None`` selects unsigned mode.
+            salt: Nonempty hex-encoded signing salt matching the server.
+                Supply together with ``key``; ``None`` selects unsigned mode.
+            signature_size: Positive digest byte count to encode. Must match
+                the server's ``IMGPROXY_SIGNATURE_SIZE``. Defaults to ``32``.
+                Values of 32 or more use the full digest.
+            unsigned_signature: URL marker used when key and salt are omitted.
+                Defaults to ``'unsafe'``. With server signing enabled,
+                configure this marker in ``IMGPROXY_TRUSTED_SIGNATURES``.
+
+        Raises:
+            ValueError: With the default signer, if only one signing
+                credential is supplied, either is empty or invalid hex,
+                or ``signature_size`` is not positive, even in unsigned mode.
+
+        Examples:
+            Create an unsigned client:
+
+            >>> from imgproxykit import Client
+            >>> client = Client('https://images.example.com')
+
+            Create a signed client with example credentials:
+
+            >>> client = Client(
+            ...     'https://images.example.com',
+            ...     key='736563726574',
+            ...     salt='73616c74',
+            ... )
+
+        """
+        self._base_url = base_url
+        self._path_serializer = self.path_serializer_cls()
+        self._url_signer = self.url_signer_cls(
+            key=key,
+            salt=salt,
+            signature_size=signature_size,
+            unsigned_signature=unsigned_signature,
+        )
+
+    def url(
+        self,
+        source: str,
+        *,
+        transform: Transform | None = None,
+    ) -> str:
+        """
+        Build a URL using processing options and server preset references.
+
+        Pass option instances or scalar keyword arguments through
+        :class:`~imgproxykit.Transform`. Use
+        :class:`~imgproxykit.options.Preset` to reference server presets.
+        Preset definitions remain on the server and are not expanded here.
+        Set the output format with ``Transform(format='webp')`` or a
+        :class:`~imgproxykit.options.Format` option. Omitted processing
+        parameters are left to the server.
+
+        Args:
+            source: Complete source URI understood by the imgproxy server.
+                The default serializer encodes its UTF-8 representation as
+                URL-safe Base64 without padding. The URI is neither validated
+                nor resolved against ``base_url``.
+            transform: Reusable processing options and optional output format.
+                Omit or pass ``None`` to add no processing options.
+
+        Returns:
+            The complete imgproxy URL, signed when credentials were supplied
+            or containing the unsigned marker otherwise. No network request
+            is made.
+        """
+        path = self._path_serializer(source, transform=transform)
+        signature = self._url_signer(path)
+        base_url = self._base_url.rstrip('/')
+        return f'{base_url}/{signature}{path}'

{imgproxykit-0.1.0 → imgproxykit-0.2.1}/imgproxykit/internal/encoding.py

@@ -7,7 +7,6 @@ def encode_base64(value: str | bytes) -> str:
 
     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-0.1.0 → imgproxykit-0.2.1}/imgproxykit/options/__init__.py

@@ -1,6 +1,7 @@
 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.base import ScalarOption as ScalarOption
 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
@@ -16,6 +17,7 @@ from imgproxykit.options.extend_aspect_ratio import (
 )
 from imgproxykit.options.filename import Filename as Filename
 from imgproxykit.options.flip import Flip as Flip
+from imgproxykit.options.format import Format as Format
 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
@@ -41,6 +43,7 @@ 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.preset import Preset as Preset
 from imgproxykit.options.quality import Quality as Quality
 from imgproxykit.options.raw import Raw as Raw
 from imgproxykit.options.resize import Resize as Resize

imgproxykit-0.2.1/imgproxykit/options/auto_rotate.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from typing import ClassVar
+
+from imgproxykit.options.base import ScalarOption
+from imgproxykit.types import OptionType
+
+
+@dataclass(frozen=True, slots=True)
+class AutoRotate(ScalarOption[bool]):
+    """
+    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(False)
+    >>> option.arguments
+    (False,)
+
+    See `imgproxy auto rotate
+    <https://docs.imgproxy.net/usage/processing#auto-rotate>`_.
+
+    """
+
+    name: ClassVar[OptionType] = 'auto_rotate'

{imgproxykit-0.1.0 → imgproxykit-0.2.1}/imgproxykit/options/background.py

@@ -1,11 +1,10 @@
 from dataclasses import dataclass
-from typing import ClassVar, final, override
+from typing import ClassVar, override
 
 from imgproxykit.options.base import Option
-from imgproxykit.types import EMPTY, Argument, OptionType
+from imgproxykit.types import Argument, OptionType
 
 
-@final
 @dataclass(frozen=True, slots=True, kw_only=True)
 class Background(Option):
     """
@@ -28,16 +27,16 @@ class Background(Option):
     (255, 255, 255)
     >>> option = Background()
     >>> option.arguments
-    (EMPTY,)
+    (None,)
 
     See `imgproxy background
     <https://docs.imgproxy.net/usage/processing#background>`_.
 
     """
 
-    color: str | tuple[int, int, int] | EMPTY = EMPTY
+    color: str | tuple[int, int, int] | None = None
 
-    _name: ClassVar[OptionType] = 'bg'
+    name: ClassVar[OptionType] = 'background'
 
     @property
     @override

imgproxykit-0.2.1/imgproxykit/options/base.py

@@ -0,0 +1,129 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, ClassVar, override
+
+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 ``None`` 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__ = ()
+
+    # Public API:
+    name: ClassVar[OptionType]
+    """
+    All subtypes must provide a supported imgproxy processing option name.
+
+    The name is shared by all instances and is not a dataclass field
+    or a constructor argument.
+    """
+
+    def __post_init__(self) -> None:
+        """Validate option arguments at construction time."""
+        self.validate()
+
+    def validate(self) -> None:  # noqa: B027
+        """
+        Validate option arguments.
+
+        Override this method to enforce server-independent constraints.
+        The default implementation does nothing.
+
+        Raises:
+            ValueError: If option arguments are invalid.
+
+        """
+        # TODO: Add per option validation
+
+    @property
+    @abstractmethod
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+
+
+type _ScalarRegistry = dict[str, type[ScalarOption[Any]]]
+
+
+@dataclass(frozen=True, slots=True)
+class ScalarOption[ValueT: Argument](Option):
+    """
+    Base class for processing options accepting one scalar value.
+
+    Subclasses are registered automatically using their processing option
+    name, with hyphens replaced by underscores. This allows passing scalar
+    values directly to :class:`~imgproxykit.Transform` as keyword arguments.
+
+    Concrete subclasses specify the value type and processing option name.
+    Override :attr:`arguments` when the option requires custom encoding.
+
+    Attributes:
+        value: Scalar processing option value.
+
+    """
+
+    value: ValueT
+
+    _registry: ClassVar[_ScalarRegistry] = {}
+
+    @override
+    def __init_subclass__(cls) -> None:
+        """Register a concrete scalar option for keyword construction."""
+        # Explicit super is required because slots=True replaces this class.
+        super(ScalarOption, cls).__init_subclass__()  # noqa: WPS608
+        # Slotted dataclasses create a replacement class. Register it again
+        # so keyword construction uses the final class, including its slots.
+        ScalarOption._registry[cls._get_kwarg_name()] = cls
+
+    @property
+    @override
+    def arguments(self) -> tuple[Argument, ...]:
+        """Positional arguments in imgproxy protocol order."""
+        return (self.value,)
+
+    @classmethod
+    def from_kwarg(cls, name: str, value: Argument) -> 'ScalarOption[Any]':
+        """
+        Construct a registered scalar option from a Transform keyword.
+
+        The concrete option constructor handles value validation and
+        protocol-specific encoding, just as with positional options.
+
+        Args:
+            name: Python keyword name of a registered scalar option.
+            value: Value passed to the concrete option constructor.
+
+        Raises:
+            TypeError: If the keyword does not identify a scalar option.
+            ValueError: If the concrete option rejects the supplied value.
+
+        """
+        option_cls = cls._registry.get(name)
+        if option_cls is None:
+            raise TypeError(
+                f'Unknown scalar processing option {name!r}. '
+                'Transform keyword arguments must name a registered scalar '
+                'option. '
+                'Pass complex processing options as positional Option '
+                'instances.',
+            )
+        return option_cls(value)
+
+    @classmethod
+    def _get_kwarg_name(cls) -> str:
+        """Convert the processing option name to its Python keyword name."""
+        return cls.name.replace('-', '_')

imgproxykit-0.2.1/imgproxykit/options/blur.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+from typing import ClassVar
+
+from imgproxykit.options.base import ScalarOption
+from imgproxykit.types import OptionType
+
+
+@dataclass(frozen=True, slots=True)
+class Blur(ScalarOption[float]):
+    """
+    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(2.0)
+    >>> option.arguments
+    (2.0,)
+
+    See `imgproxy blur
+    <https://docs.imgproxy.net/usage/processing#blur>`_.
+
+    """
+
+    name: ClassVar[OptionType] = 'blur'

{imgproxykit-0.1.0 → imgproxykit-0.2.1}/imgproxykit/options/cache_buster.py

@@ -1,14 +1,13 @@
 from dataclasses import dataclass
-from typing import ClassVar, final, override
+from typing import ClassVar, override
 from urllib.parse import quote
 
-from imgproxykit.options.base import Option
+from imgproxykit.options.base import ScalarOption
 from imgproxykit.types import Argument, OptionType
 
 
-@final
-@dataclass(frozen=True, slots=True, kw_only=True)
-class CacheBuster(Option):
+@dataclass(frozen=True, slots=True)
+class CacheBuster(ScalarOption[str]):
     """
     Add an escaped version string to the signed URL to bypass caches.
 
@@ -20,7 +19,7 @@ class CacheBuster(Option):
 
     Usage:
 
-    >>> option = CacheBuster(value='v2')
+    >>> option = CacheBuster('v2')
     >>> option.arguments
     ('v2',)
 
@@ -29,9 +28,7 @@ class CacheBuster(Option):
 
     """
 
-    value: str
-
-    _name: ClassVar[OptionType] = 'cb'
+    name: ClassVar[OptionType] = 'cachebuster'
 
     @property
     @override