imgproxykit 0.1.0__tar.gz

imgproxykit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Kondratev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imgproxykit-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: imgproxykit
+Version: 0.1.0
+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>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#example">Example</a> ·
+  <a href="https://github.com/kondratevdev/imgproxykit/issues">Issues</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+Define image transformations in Python and turn them into reusable, signed URLs.
+Your imgproxy server fetches and processes the image when the URL is requested.
+
+## Features
+
+- [x] Typed API with annotations
+- [x] Immutable, reusable transforms built from Python dataclasses
+- [x] Free imgproxy processing options, including geometry, filters, metadata,
+      quality, pixel density, gravity, and watermarks
+- [x] Output format selection, including WebP and AVIF
+- [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
+
+Create a client, define a transform, and generate a URL:
+
+```pycon
+>>> from imgproxykit import Client, Transform
+>>> from imgproxykit.options import Quality, Resize
+>>> client = Client('https://images.example.com')
+>>> thumbnail = Transform(
+...     options=(
+...         Resize(width=300, height=300, mode='fill'),
+...         Quality(85),
+...     ),
+...     format='webp',
+... )
+>>> url = client.url(
+...     'https://example.com/photo.jpg',
+...     transform=thumbnail,
+... )
+>>> url.startswith('https://images.example.com/unsafe/rs:fill:300:300/q:85/')
+True
+>>> url.endswith('.webp')
+True
+
+```
+
+Reuse `client` and `thumbnail` for other source images. Options you omit are
+left to imgproxy's defaults.
+
+Without signing credentials, URLs use the `unsafe` marker and require a server
+with signature checking disabled.
+
+### Signed URLs
+
+Supply the hex-encoded key and salt from your imgproxy server configuration:
+
+```python
+import os
+
+from imgproxykit import Client
+
+client = Client(
+    'https://images.example.com',
+    key=os.environ['IMGPROXY_KEY'],
+    salt=os.environ['IMGPROXY_SALT'],
+)
+
+url = client.url(
+    'https://example.com/photo.jpg',
+    transform=thumbnail,
+)
+```
+
+Both credentials are required together. The client signs each generated path
+automatically.
+
+### Server presets
+
+Already have presets on your imgproxy server? Reference them by name:
+
+```python
+url = client.url(
+    'https://example.com/photo.jpg',
+    presets=('thumbnail', 'watermarked'),
+    format='webp',
+)
+```
+
+Use either a Python `transform` or server `presets` in each call.
+For Python transforms, set `format` on `Transform`; for presets, pass it to
+`client.url()`.
+
+## 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.1.0/README.md

@@ -0,0 +1,121 @@
+<h1 align="center">imgproxykit</h1>
+
+<p align="center">
+  <em>A typed Python toolkit for building imgproxy URLs.</em>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#example">Example</a> ·
+  <a href="https://github.com/kondratevdev/imgproxykit/issues">Issues</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+Define image transformations in Python and turn them into reusable, signed URLs.
+Your imgproxy server fetches and processes the image when the URL is requested.
+
+## Features
+
+- [x] Typed API with annotations
+- [x] Immutable, reusable transforms built from Python dataclasses
+- [x] Free imgproxy processing options, including geometry, filters, metadata,
+      quality, pixel density, gravity, and watermarks
+- [x] Output format selection, including WebP and AVIF
+- [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
+
+Create a client, define a transform, and generate a URL:
+
+```pycon
+>>> from imgproxykit import Client, Transform
+>>> from imgproxykit.options import Quality, Resize
+>>> client = Client('https://images.example.com')
+>>> thumbnail = Transform(
+...     options=(
+...         Resize(width=300, height=300, mode='fill'),
+...         Quality(85),
+...     ),
+...     format='webp',
+... )
+>>> url = client.url(
+...     'https://example.com/photo.jpg',
+...     transform=thumbnail,
+... )
+>>> url.startswith('https://images.example.com/unsafe/rs:fill:300:300/q:85/')
+True
+>>> url.endswith('.webp')
+True
+
+```
+
+Reuse `client` and `thumbnail` for other source images. Options you omit are
+left to imgproxy's defaults.
+
+Without signing credentials, URLs use the `unsafe` marker and require a server
+with signature checking disabled.
+
+### Signed URLs
+
+Supply the hex-encoded key and salt from your imgproxy server configuration:
+
+```python
+import os
+
+from imgproxykit import Client
+
+client = Client(
+    'https://images.example.com',
+    key=os.environ['IMGPROXY_KEY'],
+    salt=os.environ['IMGPROXY_SALT'],
+)
+
+url = client.url(
+    'https://example.com/photo.jpg',
+    transform=thumbnail,
+)
+```
+
+Both credentials are required together. The client signs each generated path
+automatically.
+
+### Server presets
+
+Already have presets on your imgproxy server? Reference them by name:
+
+```python
+url = client.url(
+    'https://example.com/photo.jpg',
+    presets=('thumbnail', 'watermarked'),
+    format='webp',
+)
+```
+
+Use either a Python `transform` or server `presets` in each call.
+For Python transforms, set `format` on `Transform`; for presets, pass it to
+`client.url()`.
+
+## 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.1.0/imgproxykit/__init__.py

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

imgproxykit-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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)