immich 1.2.1__py3-none-any.whl

immich/client/rest.py

@@ -0,0 +1,199 @@
+# coding: utf-8
+
+"""
+Immich
+
+Immich API
+
+The version of the OpenAPI document: 2.4.1
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""  # noqa: E501
+
+import io
+import json
+import re
+import ssl
+from typing import Optional, Union
+
+import aiohttp
+import aiohttp_retry
+
+from immich.client.exceptions import ApiException, ApiValueError
+
+RESTResponseType = aiohttp.ClientResponse
+
+ALLOW_RETRY_METHODS = frozenset({"DELETE", "GET", "HEAD", "OPTIONS", "PUT", "TRACE"})
+
+
+class RESTResponse(io.IOBase):
+    def __init__(self, resp) -> None:
+        self.response = resp
+        self.status = resp.status
+        self.reason = resp.reason
+        self.data = None
+
+    async def read(self):
+        if self.data is None:
+            self.data = await self.response.read()
+        return self.data
+
+    @property
+    def headers(self):
+        """Returns a CIMultiDictProxy of response headers."""
+        return self.response.headers
+
+    def getheaders(self):
+        """Returns a CIMultiDictProxy of the response headers; use ``headers`` instead."""
+        return self.response.headers
+
+    def getheader(self, name, default=None):
+        """Returns a given response header; use ``headers.get()`` instead."""
+        return self.response.headers.get(name, default)
+
+
+class RESTClientObject:
+    def __init__(self, configuration) -> None:
+        # maxsize is number of requests to host that are allowed in parallel
+        self.maxsize = configuration.connection_pool_maxsize
+
+        self.ssl_context = ssl.create_default_context(
+            cafile=configuration.ssl_ca_cert,
+            cadata=configuration.ca_cert_data,
+        )
+        if configuration.cert_file:
+            self.ssl_context.load_cert_chain(
+                configuration.cert_file, keyfile=configuration.key_file
+            )
+
+        if not configuration.verify_ssl:
+            self.ssl_context.check_hostname = False
+            self.ssl_context.verify_mode = ssl.CERT_NONE
+
+        self.proxy = configuration.proxy
+        self.proxy_headers = configuration.proxy_headers
+
+        self.retries = configuration.retries
+
+        self.pool_manager: Optional[aiohttp.ClientSession] = None
+        self.retry_client: Optional[aiohttp_retry.RetryClient] = None
+
+    async def close(self) -> None:
+        if self.pool_manager:
+            await self.pool_manager.close()
+        if self.retry_client is not None:
+            await self.retry_client.close()
+
+    async def request(
+        self,
+        method,
+        url,
+        headers=None,
+        body=None,
+        post_params=None,
+        _request_timeout=None,
+    ):
+        """Execute request
+
+        :param method: http request method
+        :param url: http request url
+        :param headers: http request headers
+        :param body: request json body, for `application/json`
+        :param post_params: request post parameters,
+                            `application/x-www-form-urlencoded`
+                            and `multipart/form-data`
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        """
+        method = method.upper()
+        assert method in ["GET", "HEAD", "DELETE", "POST", "PUT", "PATCH", "OPTIONS"]
+
+        if post_params and body:
+            raise ApiValueError(
+                "body parameter cannot be used with post_params parameter."
+            )
+
+        post_params = post_params or {}
+        headers = headers or {}
+        # url already contains the URL query string
+        timeout = _request_timeout or 5 * 60
+
+        if "Content-Type" not in headers:
+            headers["Content-Type"] = "application/json"
+
+        args = {"method": method, "url": url, "timeout": timeout, "headers": headers}
+
+        if self.proxy:
+            args["proxy"] = self.proxy
+        if self.proxy_headers:
+            args["proxy_headers"] = self.proxy_headers
+
+        # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE`
+        if method in ["POST", "PUT", "PATCH", "OPTIONS", "DELETE"]:
+            if re.search("json", headers["Content-Type"], re.IGNORECASE):
+                if body is not None:
+                    body = json.dumps(body)
+                args["data"] = body
+            elif headers["Content-Type"] == "application/x-www-form-urlencoded":
+                args["data"] = aiohttp.FormData(post_params)
+            elif headers["Content-Type"] == "multipart/form-data":
+                # must del headers['Content-Type'], or the correct
+                # Content-Type which generated by aiohttp
+                del headers["Content-Type"]
+                data = aiohttp.FormData()
+                for param in post_params:
+                    k, v = param
+                    if isinstance(v, tuple) and len(v) == 3:
+                        data.add_field(k, value=v[1], filename=v[0], content_type=v[2])
+                    else:
+                        # Ensures that dict objects are serialized
+                        if isinstance(v, dict):
+                            v = json.dumps(v)
+                        elif isinstance(v, int):
+                            v = str(v)
+                        data.add_field(k, v)
+                args["data"] = data
+
+            # Pass a `bytes` or `str` parameter directly in the body to support
+            # other content types than Json when `body` argument is provided
+            # in serialized form
+            elif isinstance(body, str) or isinstance(body, bytes):
+                args["data"] = body
+            else:
+                # Cannot generate the request from given parameters
+                msg = """Cannot prepare a request message for provided
+                         arguments. Please check that your arguments match
+                         declared content type."""
+                raise ApiException(status=0, reason=msg)
+
+        pool_manager: Union[aiohttp.ClientSession, aiohttp_retry.RetryClient]
+
+        # https pool manager
+        if self.pool_manager is None:
+            self.pool_manager = aiohttp.ClientSession(
+                connector=aiohttp.TCPConnector(
+                    limit=self.maxsize, ssl=self.ssl_context
+                ),
+                trust_env=True,
+            )
+        pool_manager = self.pool_manager
+
+        if self.retries is not None and method in ALLOW_RETRY_METHODS:
+            if self.retry_client is None:
+                self.retry_client = aiohttp_retry.RetryClient(
+                    client_session=self.pool_manager,
+                    retry_options=aiohttp_retry.ExponentialRetry(
+                        attempts=self.retries,
+                        factor=2.0,
+                        start_timeout=0.1,
+                        max_timeout=120.0,
+                    ),
+                )
+            pool_manager = self.retry_client
+
+        r = await pool_manager.request(**args)
+
+        return RESTResponse(r)

immich/client_wrapper/__init__.py

@@ -0,0 +1,15 @@
+from immich.client_wrapper.assets_api_wrapped import (
+    AssetsApiWrapped as AssetsApiWrapped,
+)
+from immich.client_wrapper.download_api_wrapped import (
+    DownloadApiWrapped as DownloadApiWrapped,
+)
+from immich.client_wrapper.users_api_wrapped import (
+    UsersApiWrapped as UsersApiWrapped,
+)
+
+__all__ = [
+    "AssetsApiWrapped",
+    "DownloadApiWrapped",
+    "UsersApiWrapped",
+]

immich/client_wrapper/assets_api_wrapped.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+from uuid import UUID
+
+from pydantic import StrictStr
+
+from immich.client.api.assets_api import AssetsApi
+from immich.client.models.asset_media_size import AssetMediaSize
+from immich.utils import resolve_output_filename
+
+
+class AssetsApiWrapped(AssetsApi):
+    async def download_asset_to_file(
+        self,
+        id: UUID,
+        out_dir: Path,
+        key: Optional[StrictStr] = None,
+        slug: Optional[StrictStr] = None,
+        filename: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Path:
+        """
+        Download an asset to a file.
+
+        :param id: The asset ID.
+        :param out_dir: The directory to write the asset to.
+        :param key: Public share key (the last path segment of a public share URL, i.e. `/share/<key>`). When provided, the asset can be accessed via the public share link without an API key. Typically you pass either `key` or `slug`.
+        :param slug: Public share slug for custom share URLs (the last path segment of `/s/<slug>`). Allows access without authentication. Typically you pass either `slug` or `key`.
+        :param filename: The filename to use. If not provided, we use the original filename from the headers or default to "orig-" + asset_id.
+        :param kwargs: Additional arguments to pass to the `download_asset_with_http_info` method.
+
+        For exact request/response behavior, inspect `AssetsApi.download_asset_with_http_info`
+        in the generated client.
+        """
+        resp = await super().download_asset_with_http_info(
+            id=id, key=key, slug=slug, **kwargs
+        )
+        name = resolve_output_filename(
+            resp.headers,
+            name=filename,
+            default_base=f"orig-{id}",
+        )
+
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / name
+        out_path.write_bytes(bytes(resp.data))
+        return out_path
+
+    async def view_asset_to_file(
+        self,
+        id: UUID,
+        out_dir: Path,
+        key: Optional[StrictStr] = None,
+        size: Optional[AssetMediaSize] = None,
+        slug: Optional[StrictStr] = None,
+        filename: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Path:
+        """
+        Save an asset's thumbnail to a file.
+
+        :param id: The asset ID.
+        :param out_dir: The directory to write the asset to.
+        :param key: Public share key (the last path segment of a public share URL, i.e. `/share/<key>`). When provided, the thumbnail can be fetched via the public share link without an API key. Typically you pass either `key` or `slug`.
+        :param size: Thumbnail size.
+        :param slug: Public share slug for custom share URLs (the last path segment of `/s/<slug>`). Allows access without authentication. Typically you pass either `slug` or `key`.
+        :param filename: The filename to use. If not provided, we use the original filename from the headers or default to "thumb-" + asset_id.
+        :param kwargs: Additional arguments to pass to the `view_asset_with_http_info` method.
+
+        For exact request/response behavior, inspect `AssetsApi.view_asset_with_http_info`
+        in the generated client.
+        """
+        resp = await super().view_asset_with_http_info(
+            id=id, key=key, size=size, slug=slug, **kwargs
+        )
+        name = resolve_output_filename(
+            resp.headers,
+            name=filename,
+            default_base=f"thumb-{id}",
+        )
+
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / name
+        out_path.write_bytes(bytes(resp.data))
+        return out_path

immich/client_wrapper/download_api_wrapped.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any, Optional
+
+import tqdm
+from pydantic import StrictStr
+
+from immich.client.api.download_api import DownloadApi
+from immich.client.models.asset_ids_dto import AssetIdsDto
+from immich.client.models.download_info_dto import DownloadInfoDto
+
+
+class DownloadApiWrapped(DownloadApi):
+    async def download_archive_to_file(
+        self,
+        download_info: DownloadInfoDto,
+        out_dir: Path,
+        key: Optional[StrictStr] = None,
+        slug: Optional[StrictStr] = None,
+        show_progress_bars: bool = True,
+        **kwargs: Any,
+    ) -> list[Path]:
+        """
+        Download one or more asset archives and save them to ZIP files.
+
+        Note: This method intentionally downloads archives **sequentially** (not in parallel) by default.
+        Immich has to build ZIP archives server-side; parallelizing many archive requests can put significant
+        CPU/disk load on the Immich server and may lead to timeouts or degraded performance for other users.
+        If you choose to parallelize, keep concurrency low and do so at your own risk.
+
+        :param download_info: The download info (two-step flow; downloads all archives returned by `get_download_info`).
+        :param out_dir: The directory to write the ZIP archive to.
+        :param key: Public share key (the last path segment of a public share URL, i.e. `/share/<key>`). Allows access without authentication. Typically you pass either `key` or `slug`.
+        :param slug: Public share slug for custom share URLs (the last path segment of `/s/<slug>`). Allows access without authentication. Typically you pass either `slug` or `key`.
+        :param show_progress_bars: Whether to show tqdm progress bars (per-archive bytes + overall archive count).
+        :param kwargs: Additional arguments to pass to the underlying SDK calls.
+
+        :return: The list of paths to the downloaded archives.
+
+        For exact request/response behavior, inspect `DownloadApi.download_archive_without_preload_content`
+        in the generated client.
+        """
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        # Normalize to a list of archive requests.
+        info = await super().get_download_info(
+            download_info, key=key, slug=slug, **kwargs
+        )
+        archive_requests: list[tuple[AssetIdsDto, int]] = [
+            (AssetIdsDto(asset_ids=archive.asset_ids), int(archive.size))
+            for archive in info.archives
+        ]
+
+        out_paths: list[Path] = []
+
+        archives_pbar = tqdm.tqdm(
+            total=len(archive_requests),
+            desc="archives",
+            unit="archive",
+            position=0,
+            leave=True,
+            dynamic_ncols=True,
+            disable=not show_progress_bars,
+        )
+        try:
+            for asset_ids_dto, expected_size in archive_requests:
+                resp = await super().download_archive_without_preload_content(
+                    asset_ids_dto=asset_ids_dto,
+                    key=key,
+                    slug=slug,
+                    **kwargs,
+                )
+
+                out_path = out_dir / f"archive-{uuid.uuid4()}.zip"
+                temp_path = out_path.with_suffix(out_path.suffix + ".part")
+
+                bytes_pbar = tqdm.tqdm(
+                    total=expected_size or None,
+                    unit="B",
+                    unit_scale=True,
+                    desc=str(out_path.name),
+                    position=1,
+                    leave=False,
+                    dynamic_ncols=True,
+                    disable=not show_progress_bars,
+                )
+                try:
+                    async with resp:
+                        with temp_path.open("wb") as f:
+                            async for chunk in resp.content.iter_chunked(1024 * 1024):
+                                if not chunk:
+                                    continue
+                                f.write(chunk)
+                                bytes_pbar.update(len(chunk))
+                except Exception:
+                    # Clean up partial download on error
+                    if temp_path.exists():
+                        temp_path.unlink()
+                    raise
+                finally:
+                    bytes_pbar.close()
+
+                temp_path.replace(out_path)
+                out_paths.append(out_path)
+                archives_pbar.update(1)
+        finally:
+            archives_pbar.close()
+
+        return out_paths

immich/client_wrapper/users_api_wrapped.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+from uuid import UUID
+
+from immich.client.api.users_api import UsersApi
+from immich.utils import resolve_output_filename
+
+
+class UsersApiWrapped(UsersApi):
+    async def get_profile_image_to_file(
+        self,
+        id: UUID,
+        out_dir: Path,
+        filename: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Path:
+        """
+        Download a user's profile image and save it to a file.
+
+        :param id: The user ID.
+        :param out_dir: The directory to write the profile image to.
+        :param filename: The filename to use. If not provided, we try to derive it from the headers
+            or default to "profile-" + user_id.
+        :param kwargs: Additional arguments to pass to the `get_profile_image_with_http_info` method.
+
+        For exact request/response behavior, inspect `UsersApi.get_profile_image_with_http_info`
+        in the generated client.
+        """
+        resp = await super().get_profile_image_with_http_info(id=id, **kwargs)
+        name = resolve_output_filename(
+            resp.headers,
+            name=filename,
+            default_base=f"profile-{id}",
+        )
+
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / name
+        out_path.write_bytes(bytes(resp.data))
+        return out_path