immich 1.2.1__py3-none-any.whl

immich/sdk.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from aiohttp import ClientSession  # type: ignore[import-not-found]
+
+from immich.client.api_client import ApiClient
+from immich.client.configuration import Configuration
+
+from immich.client.api.activities_api import ActivitiesApi
+from immich.client.api.albums_api import AlbumsApi
+from immich.client.api.api_keys_api import APIKeysApi
+from immich.client_wrapper.assets_api_wrapped import AssetsApiWrapped
+from immich.client.api.authentication_admin_api import AuthenticationAdminApi
+from immich.client.api.authentication_api import AuthenticationApi
+from immich.client.api.deprecated_api import DeprecatedApi
+from immich.client_wrapper.download_api_wrapped import DownloadApiWrapped
+from immich.client.api.duplicates_api import DuplicatesApi
+from immich.client.api.faces_api import FacesApi
+from immich.client.api.jobs_api import JobsApi
+from immich.client.api.libraries_api import LibrariesApi
+from immich.client.api.maintenance_admin_api import MaintenanceAdminApi
+from immich.client.api.map_api import MapApi
+from immich.client.api.memories_api import MemoriesApi
+from immich.client.api.notifications_admin_api import NotificationsAdminApi
+from immich.client.api.notifications_api import NotificationsApi
+from immich.client.api.partners_api import PartnersApi
+from immich.client.api.people_api import PeopleApi
+from immich.client.api.plugins_api import PluginsApi
+from immich.client.api.queues_api import QueuesApi
+from immich.client.api.search_api import SearchApi
+from immich.client.api.server_api import ServerApi
+from immich.client.api.sessions_api import SessionsApi
+from immich.client.api.shared_links_api import SharedLinksApi
+from immich.client.api.stacks_api import StacksApi
+from immich.client.api.sync_api import SyncApi
+from immich.client.api.system_config_api import SystemConfigApi
+from immich.client.api.system_metadata_api import SystemMetadataApi
+from immich.client.api.tags_api import TagsApi
+from immich.client.api.timeline_api import TimelineApi
+from immich.client.api.trash_api import TrashApi
+from immich.client.api.users_admin_api import UsersAdminApi
+from immich.client_wrapper.users_api_wrapped import UsersApiWrapped
+from immich.client.api.views_api import ViewsApi
+from immich.client.api.workflows_api import WorkflowsApi
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def _build_configuration(
+    *,
+    api_key: Optional[str],
+    bearer_token: Optional[str],
+    cookie: Optional[str],
+    base_url: str,
+) -> Configuration:
+    config = Configuration(host=_normalize_base_url(base_url))
+    if api_key:
+        # Security scheme name is `api_key` (header: x-api-key)
+        config.api_key["api_key"] = api_key
+    if cookie:
+        # Security scheme name is `cookie` (cookie: immich_access_token)
+        config.api_key["cookie"] = cookie
+    if bearer_token:
+        # JWT access token (Authorization: Bearer <token>)
+        config.access_token = bearer_token
+    return config
+
+
+class AsyncClient:
+    """
+    Async client for the Immich API.
+    """
+
+    activities: ActivitiesApi
+    """An activity is a like or a comment made by a user on an asset or album.
+
+    https://api.immich.app/endpoints/activities
+    """
+
+    albums: AlbumsApi
+    """An album is a collection of assets that can be shared with other users or via shared links.
+
+    https://api.immich.app/endpoints/albums
+    """
+
+    api_keys: APIKeysApi
+    """An api key can be used to programmatically access the Immich API.
+
+    https://api.immich.app/endpoints/api-keys
+    """
+
+    assets: AssetsApiWrapped
+    """An asset is an image or video that has been uploaded to Immich.
+
+    https://api.immich.app/endpoints/assets
+    """
+
+    authentication: AuthenticationApi
+    """Endpoints related to user authentication, including OAuth.
+
+    https://api.immich.app/endpoints/authentication
+    """
+
+    authentication_admin: AuthenticationAdminApi
+    """Administrative endpoints related to authentication.
+
+    https://api.immich.app/endpoints/authentication-(admin)
+    """
+
+    deprecated: DeprecatedApi
+    """Deprecated endpoints that are planned for removal in the next major release.
+
+    https://api.immich.app/endpoints/deprecated
+    """
+
+    download: DownloadApiWrapped
+    """Endpoints for downloading assets or collections of assets.
+
+    https://api.immich.app/endpoints/download
+    """
+
+    duplicates: DuplicatesApi
+    """Endpoints for managing and identifying duplicate assets.
+
+    https://api.immich.app/endpoints/duplicates
+    """
+
+    faces: FacesApi
+    """A face is a detected human face within an asset, which can be associated with a person. Faces are normally detected via machine learning, but can also be created via manually.
+
+    https://api.immich.app/endpoints/faces
+    """
+
+    jobs: JobsApi
+    """Queues and background jobs are used for processing tasks asynchronously. Queues can be paused and resumed as needed.
+
+    https://api.immich.app/endpoints/jobs
+    """
+
+    libraries: LibrariesApi
+    """An external library is made up of input file paths or expressions that are scanned for asset files. Discovered files are automatically imported. Assets much be unique within a library, but can be duplicated across libraries. Each user has a default upload library, and can have one or more external libraries.
+
+    https://api.immich.app/endpoints/libraries
+    """
+
+    maintenance_admin: MaintenanceAdminApi
+    """Maintenance mode allows you to put Immich in a read-only state to perform various operations.
+
+    https://api.immich.app/endpoints/maintenance-(admin)
+    """
+
+    map: MapApi
+    """Map endpoints include supplemental functionality related to geolocation, such as reverse geocoding and retrieving map markers for assets with geolocation data.
+
+    https://api.immich.app/endpoints/map
+    """
+
+    memories: MemoriesApi
+    """A memory is a specialized collection of assets with dedicated viewing implementations in the web and mobile clients. A memory includes fields related to visibility and are automatically generated per user via a background job.
+
+    https://api.immich.app/endpoints/memories
+    """
+
+    notifications: NotificationsApi
+    """A notification is a specialized message sent to users to inform them of important events. Currently, these notifications are only shown in the Immich web application.
+
+    https://api.immich.app/endpoints/notifications
+    """
+
+    notifications_admin: NotificationsAdminApi
+    """Notification administrative endpoints.
+
+    https://api.immich.app/endpoints/notifications-(admin)
+    """
+
+    partners: PartnersApi
+    """A partner is a link with another user that allows sharing of assets between two users.
+
+    https://api.immich.app/endpoints/partners
+    """
+
+    people: PeopleApi
+    """A person is a collection of faces, which can be favorited and named. A person can also be merged into another person. People are automatically created via the face recognition job.
+
+    https://api.immich.app/endpoints/people
+    """
+
+    plugins: PluginsApi
+    """A plugin is an installed module that makes filters and actions available for the workflow feature.
+
+    https://api.immich.app/endpoints/plugins
+    """
+
+    queues: QueuesApi
+    """Queues and background jobs are used for processing tasks asynchronously. Queues can be paused and resumed as needed.
+
+    https://api.immich.app/endpoints/queues
+    """
+
+    search: SearchApi
+    """Endpoints related to searching assets via text, smart search, optical character recognition (OCR), and other filters like person, album, and other metadata. Search endpoints usually support pagination and sorting.
+
+    https://api.immich.app/endpoints/search
+    """
+
+    server: ServerApi
+    """Information about the current server deployment, including version and build information, available features, supported media types, and more.
+
+    https://api.immich.app/endpoints/server
+    """
+
+    sessions: SessionsApi
+    """A session represents an authenticated login session for a user. Sessions also appear in the web application as "Authorized devices".
+
+    https://api.immich.app/endpoints/sessions
+    """
+
+    shared_links: SharedLinksApi
+    """A shared link is a public url that provides access to a specific album, asset, or collection of assets. A shared link can be protected with a password, include a specific slug, allow or disallow downloads, and optionally include an expiration date.
+
+    https://api.immich.app/endpoints/shared-links
+    """
+
+    stacks: StacksApi
+    """A stack is a group of related assets. One asset is the "primary" asset, and the rest are "child" assets. On the main timeline, stack parents are included by default, while child assets are hidden.
+
+    https://api.immich.app/endpoints/stacks
+    """
+
+    sync: SyncApi
+    """A collection of endpoints for the new mobile synchronization implementation.
+
+    https://api.immich.app/endpoints/sync
+    """
+
+    system_config: SystemConfigApi
+    """Endpoints to view, modify, and validate the system configuration settings.
+
+    https://api.immich.app/endpoints/system-config
+    """
+
+    system_metadata: SystemMetadataApi
+    """Endpoints to view, modify, and validate the system metadata, which includes information about things like admin onboarding status.
+
+    https://api.immich.app/endpoints/system-metadata
+    """
+
+    tags: TagsApi
+    """A tag is a user-defined label that can be applied to assets for organizational purposes. Tags can also be hierarchical, allowing for parent-child relationships between tags.
+
+    https://api.immich.app/endpoints/tags
+    """
+
+    timeline: TimelineApi
+    """Specialized endpoints related to the timeline implementation used in the web application. External applications or tools should not use or rely on these endpoints, as they are subject to change without notice.
+
+    https://api.immich.app/endpoints/timeline
+    """
+
+    trash: TrashApi
+    """Endpoints for managing the trash can, which includes assets that have been discarded. Items in the trash are automatically deleted after a configured amount of time.
+
+    https://api.immich.app/endpoints/trash
+    """
+
+    users_admin: UsersAdminApi
+    """Administrative endpoints for managing users, including creating, updating, deleting, and restoring users. Also includes endpoints for resetting passwords and PIN codes.
+
+    https://api.immich.app/endpoints/users-(admin)
+    """
+
+    users: UsersApiWrapped
+    """Endpoints for viewing and updating the current users, including product key information, profile picture data, onboarding progress, and more.
+
+    https://api.immich.app/endpoints/users
+    """
+
+    views: ViewsApi
+    """Endpoints for specialized views, such as the folder view.
+
+    https://api.immich.app/endpoints/views
+    """
+
+    workflows: WorkflowsApi
+    """A workflow is a set of actions that run whenever a triggering event occurs. Workflows also can include filters to further limit execution.
+
+    https://api.immich.app/endpoints/workflows
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        cookie: Optional[str] = None,
+        base_url: str,
+        http_client: Optional[ClientSession] = None,
+    ) -> None:
+        self._owns_http_client = http_client is None
+        self._injected_http_client = http_client
+        self.config = _build_configuration(
+            api_key=api_key,
+            bearer_token=bearer_token,
+            cookie=cookie,
+            base_url=base_url,
+        )
+        self.base_client = ApiClient(configuration=self.config)
+        self.base_client.user_agent = "immich-python-client"
+
+        # Allow caller to inject a pre-configured aiohttp session.
+        if http_client is not None:
+            self.base_client.rest_client.pool_manager = http_client
+
+        # API groups (single upstream API, not microservices)
+        self.activities = ActivitiesApi(self.base_client)
+        self.albums = AlbumsApi(self.base_client)
+        self.api_keys = APIKeysApi(self.base_client)
+        self.assets = AssetsApiWrapped(self.base_client)
+        self.authentication = AuthenticationApi(self.base_client)
+        self.authentication_admin = AuthenticationAdminApi(self.base_client)
+        self.deprecated = DeprecatedApi(self.base_client)
+        self.download = DownloadApiWrapped(self.base_client)
+        self.duplicates = DuplicatesApi(self.base_client)
+        self.faces = FacesApi(self.base_client)
+        self.jobs = JobsApi(self.base_client)
+        self.libraries = LibrariesApi(self.base_client)
+        self.maintenance_admin = MaintenanceAdminApi(self.base_client)
+        self.map = MapApi(self.base_client)
+        self.memories = MemoriesApi(self.base_client)
+        self.notifications = NotificationsApi(self.base_client)
+        self.notifications_admin = NotificationsAdminApi(self.base_client)
+        self.partners = PartnersApi(self.base_client)
+        self.people = PeopleApi(self.base_client)
+        self.plugins = PluginsApi(self.base_client)
+        self.queues = QueuesApi(self.base_client)
+        self.search = SearchApi(self.base_client)
+        self.server = ServerApi(self.base_client)
+        self.sessions = SessionsApi(self.base_client)
+        self.shared_links = SharedLinksApi(self.base_client)
+        self.stacks = StacksApi(self.base_client)
+        self.sync = SyncApi(self.base_client)
+        self.system_config = SystemConfigApi(self.base_client)
+        self.system_metadata = SystemMetadataApi(self.base_client)
+        self.tags = TagsApi(self.base_client)
+        self.timeline = TimelineApi(self.base_client)
+        self.trash = TrashApi(self.base_client)
+        self.users = UsersApiWrapped(self.base_client)
+        self.users_admin = UsersAdminApi(self.base_client)
+        self.views = ViewsApi(self.base_client)
+        self.workflows = WorkflowsApi(self.base_client)
+
+    async def close(self) -> None:
+        # If the caller injected the aiohttp session, don't close it.
+        if not self._owns_http_client and self._injected_http_client is not None:
+            self.base_client.rest_client.pool_manager = None
+        await self.base_client.close()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()

immich/utils.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from email.message import Message
+from mimetypes import guess_extension
+from pathlib import Path
+from typing import Optional
+
+
+def filename_from_headers(
+    headers: dict[str, str] | None, *, fallback_base: str
+) -> Optional[str]:
+    """
+    Derive a filename from response headers.
+
+    Order of precedence:
+    - Content-Disposition filename (if present)
+      - if it has no extension, append an extension derived from Content-Type (if available)
+    - Content-Type derived extension + `fallback_base`
+
+    :param headers: The response headers.
+    :param fallback_base: The filename without extension if we cannot derive the original filename from the Content-Disposition header.
+
+    :returns: The derived filename or None if we cannot derive the filename from the headers.
+    """
+    if not headers:
+        return None
+
+    def h(name: str) -> Optional[str]:
+        return next((v for k, v in headers.items() if k.lower() == name.lower()), None)
+
+    cd_name: Optional[str] = None
+    if cd := h("content-disposition"):
+        msg = Message()
+        msg["content-disposition"] = cd
+        if filename := msg.get_filename():
+            cd_name = Path(filename).name
+
+    ext = (
+        guess_extension(ct.partition(";")[0].strip())
+        if (ct := h("content-type"))
+        else None
+    )
+
+    # Content-Disposition wins for the base name; Content-Type is the safety net for the extension.
+    if cd_name:
+        return cd_name if Path(cd_name).suffix or not ext else f"{cd_name}{ext}"
+
+    return f"{fallback_base}{ext}" if ext else None
+
+
+def resolve_output_filename(
+    headers: dict[str, str] | None,
+    *,
+    name: Optional[str] = None,
+    default_base: str,
+    default_ext: Optional[str] = None,
+) -> str:
+    """
+    Resolve an output filename by selecting a base name and an extension.
+
+    Base name precedence:
+    - user-supplied `name`
+    - Content-Disposition filename
+    - `default_base`
+
+    Extension precedence:
+    - `default_ext` (if provided; overrides any other extension)
+    - extension present on the chosen base name (e.g. from Content-Disposition)
+    - Content-Type derived extension
+    - none
+
+    :param headers: The response headers.
+    :param name: The user-supplied name.
+    :param default_base: The default base name, used when no user/header filename can be derived.
+    :param default_ext: The default extension (must start with `.`), used when you want to force a specific extension (e.g. `.zip`).
+
+    :returns: The resolved filename.
+    """
+    if default_ext and not default_ext.startswith("."):
+        raise ValueError("default_ext must start with '.' (e.g. '.zip')")
+
+    base = default_base
+    ext = None
+
+    header_path = None
+    if _ := filename_from_headers(headers, fallback_base=default_base):
+        header_path = Path(_)
+
+    # Base name
+    if name:
+        base = Path(name).stem
+    elif header_path:
+        base = header_path.stem
+
+    # Extension
+    if default_ext:
+        ext = default_ext
+    elif header_path:
+        ext = header_path.suffix
+    return f"{base}{ext}" if ext else base

immich-1.2.1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: immich
+Version: 1.2.1
+Summary: Unofficial Python client for Immich
+Keywords: immich,photos,backup,client,api
+Author: Immich Python Client
+Author-email: Immich Python Client <contact@timonrieger.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp>=3.8.4,<4.0.0
+Requires-Dist: aiohttp-retry>=2.8.3,<3.0.0
+Requires-Dist: pydantic>=2.0.0,<3.0.0
+Requires-Dist: python-dateutil>=2.8.2,<3.0.0
+Requires-Dist: requests>=2.32.0,<3.0.0
+Requires-Dist: tqdm>=4.67.0,<5.0.0
+Requires-Dist: typing-extensions>=4.7.1,<5.0.0
+Requires-Dist: urllib3>=1.25.3,<3.0.0
+Requires-Dist: uv==0.9.21 ; extra == 'build'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/timonrieger/immich-python-client/releases
+Project-URL: Repository, https://github.com/timonrieger/immich-python-client
+Provides-Extra: build
+Description-Content-Type: text/markdown
+
+# Immich API Client
+
+<p align="center">
+    <a href="https://coderabbit.ai" target="_blank" rel="noopener noreferrer">
+        <img src="https://img.shields.io/coderabbit/prs/github/timonrieger/immich-python-client?utm_source=oss&utm_medium=github&utm_campaign=timonrieger%2Fimmich-python-client&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews" alt="CodeRabbit Pull Request Reviews">
+    </a>
+    <a href="https://github.com/timonrieger/immich-python-client/actions/workflows/test.yml">
+        <img src="https://github.com/timonrieger/immich-python-client/actions/workflows/test.yml/badge.svg" alt="Tests">
+    </a>
+    <a href="https://pypi.org/project/immich" target="_blank" rel="noopener noreferrer">
+        <img src="https://img.shields.io/pypi/v/immich?color=%2334D058&label=pypi%20package" alt="Package version">
+    </a>
+    <a href="https://pypi.org/project/immich" target="_blank" rel="noopener noreferrer">
+        <img src="https://img.shields.io/pypi/pyversions/immich.svg?color=%2334D058" alt="Supported Python versions">
+    </a>
+</p>
+
+Unofficial Python client for the [Immich](https://immich.app) API.
+
+> [!IMPORTANT]
+> This repository is **auto-generated** from the Immich OpenAPI specification.
+> **Do not open pull requests**. See [CONTRIBUTING](CONTRIBUTING.md) for more details.
+
+## Status
+
+- **Unofficial**: Not affiliated with or endorsed by Immich.
+- **Auto-synced**: Kept in sync with the **latest Immich release** (regenerated as upstream changes land).
+
+## Installation
+
+You need Python 3.10–3.14 installed to be able to use this library.
+
+Install the latest stable version from PyPI:
+
+```bash
+pip install immich
+```
+
+If you want the latest version (which may be a pre-release):
+
+```bash
+pip install --pre immich
+```
+
+## Structure
+
+This SDK is **async-only**. The client exposes API groups as attributes, and endpoints as methods on those groups. Groups and endpoints are documented in the [Immich API documentation](https://api.immich.app/endpoints).
+
+## Authentication
+
+Immich supports API keys. Create one in your server and pass it via `api_key=...`. Cookie and Bearer tokens are also supported.
+
+## Usage
+
+With a context manager (recommended):
+
+```python
+from immich import AsyncClient
+
+async with AsyncClient(api_key="your-immich-api-key", base_url="http://localhost:2283/api") as client:
+    await client.server.get_about_info()
+```
+
+Without a context manager:
+
+```python
+import asyncio
+from immich import AsyncClient
+
+async def main():
+    client = AsyncClient(api_key="your-immich-api-key", base_url="http://localhost:2283/api")
+    try:
+        await client.server.get_about_info()
+    finally:
+        await client.close()
+
+asyncio.run(main())
+```
+
+## Response Types
+
+There are three different available output formats you can choose from:
+
+### Serialized Response
+
+You can get fully serialized responses as Pydantic models. Using this, you get the full benefits of Pydantic's type checking.
+
+```python
+res = await client.server.get_about_info()
+```
+
+The output would look like this:
+
+```python
+ServerAboutResponseDto(...)
+```
+
+### Serialized Response with HTTP Info
+
+```python
+res = await client.server.get_about_info_with_http_info()
+```
+
+The output would look like this:
+
+```python
+status_code=200 headers={'Content-Type': 'application/json'} data=ServerAboutResponseDto(...) raw_data=b'{"...": "..."}'
+```
+
+### JSON Response
+
+You can receive a classical JSON response by suffixing the function name with `_without_preload_content`:
+
+```python
+response = await client.server.get_about_info_without_preload_content()
+await response.json()
+```
+
+## Session management
+
+The client can manage a shared `aiohttp.ClientSession`, or you can pass your own via `http_client=...` (you are responsible for its lifecycle).
+
+## Versioning
+
+This package follows **[Semantic Versioning](https://semver.org)**.
+
+- **Package version is not the server version**: `immich` package `X.Y.Z` is the client’s own version.
+- **Upstream breaking changes ⇒ major bump**: Breaking Immich changes that require breaking client changes produce a new **major** version.
+- **Supported Immich server version**: `IMMICH-VERSION` (repo root) tracks the Immich version this client was generated from.
+  - If you run an **older** Immich server version, you can install an **older** `immich` package release where `IMMICH-VERSION` matches your server.
+  - This client supports **Immich v2.4.1** and above.