From 2994ffcc52dc77f85bcc0b80c1e1725ab0da826f Mon Sep 17 00:00:00 2001 From: Lucas Vivo Date: Mon, 2 Nov 2026 14:25:06 +0100 Subject: [PATCH] feat(immich): add immich-folder-album script,add restore user script github: create albums from immich ext library folders restore deleted user script --- immich-scripts/immich-folder-album-creator.sh | 7 + immich-scripts/immich_auto_album.py | 3635 +++++++++++++++++ immich-scripts/requirements.txt | 7 + immich-scripts/restore_user.py | 45 + 4 files changed, 3694 insertions(+) create mode 100755 immich-scripts/immich-folder-album-creator.sh create mode 100755 immich-scripts/immich_auto_album.py create mode 100755 immich-scripts/requirements.txt create mode 100755 immich-scripts/restore_user.py diff --git a/immich-scripts/immich-folder-album-creator.sh b/immich-scripts/immich-folder-album-creator.sh new file mode 100755 index 0000000..366fcf2 --- /dev/null +++ b/immich-scripts/immich-folder-album-creator.sh @@ -0,0 +1,7 @@ +./immich_auto_album.py \ + --share-with "Mimi" \ + --share-role "editor" \ + --album-levels 3,7 \ + /library \ + https://fotos.someoneslinux.selfhost.eu/api \ + "gy78jOBMvwPNiTf8iHkllZa9H0lU9ir6oDDP1tzo1M" \ diff --git a/immich-scripts/immich_auto_album.py b/immich-scripts/immich_auto_album.py new file mode 100755 index 0000000..6cf9c10 --- /dev/null +++ b/immich-scripts/immich_auto_album.py @@ -0,0 +1,3635 @@ +#!/home/lucas/scripts/immich/.venv/bin/python +"""Python script for creating albums in Immich from folder names in an external library.""" + +# pylint: disable=too-many-lines +from __future__ import annotations +import contextlib +from concurrent.futures import ThreadPoolExecutor, Future +from functools import partial +from time import perf_counter +import asyncio +import threading +from dataclasses import dataclass +from typing import Awaitable, Callable, Optional, Tuple, TypeVar, Any, Coroutine +from logging import LogRecord +import argparse +import logging +import sys +import fnmatch +import os +import datetime +from collections import OrderedDict, defaultdict +import random +from urllib.error import HTTPError +import traceback +from uuid import UUID +import unicodedata +import signal +import regex +import yaml +from aiohttp import TCPConnector, ClientSession, ClientTimeout + +from immichpy.client.generated import ( + AddUsersDto, + AlbumResponseDto, + AlbumUserAddDto, + AlbumUserRole, + AssetBulkDeleteDto, + AssetBulkUpdateDto, + AssetOrder, + AssetResponseDto, + AssetVisibility, + BoolFilter, + BulkIdsDto, + CreateAlbumDto, + LibraryResponseDto, + MetadataSearchDto, + SearchFilter, + SearchResponseDto, + ServerVersionResponseDto, + UpdateAlbumDto, + UpdateAlbumUserDto, + UserResponseDto, +) +from immichpy.client.generated.models import EnumFilterAssetVisibility, IdsFilter +from immichpy import AsyncClient +from immichpy.client.generated.exceptions import ( + ApiException, + UnauthorizedException, + BadRequestException, +) +from tenacity import ( + retry_if_exception, + retry_if_exception_type, + stop_after_attempt, + wait_exponential, + AsyncRetrying, +) + +# Script Constants +# Environment variable to check if the script is running inside Docker +ENV_IS_DOCKER = "IS_DOCKER" + +T = TypeVar("T") + + +@dataclass +class ApiClientConfig: + """ + Configuration for the API client + """ + + # The number of assets to add to an album with a single API call + chunk_size: int + # The number of assets to fetch with a single API call + fetch_chunk_size: int + # The timeout to use for API calls in seconds + api_timeout: int + # Flag indicating whether to skip SSL certificate validation + insecure: bool + # The maximum number of times to retry an API call if it timed out before failing + max_retry_count: int + # # Number of threads to fetch assets with in parallel + threads: int + + def __init__(self, main_config: Configuration) -> None: + self.chunk_size = main_config.chunk_size + self.fetch_chunk_size = main_config.fetch_chunk_size + self.api_timeout = main_config.api_timeout + self.insecure = main_config.insecure + self.max_retry_count = main_config.max_retry_count + self.threads = main_config.threads + + +# pylint: disable=R0902,R0904 +class ApiClient: + """Encapsulates Immich API Calls in a client object""" + + # Default value for the maximum number of assets to add to an album in a single API call + CHUNK_SIZE_DEFAULT = 2000 + # Maximum number of assets that can be fetched in a single API call using the search endpoint + FETCH_CHUNK_SIZE_MAX = 1000 + # Default value for the maximum number of assets to fetch in a single API call + FETCH_CHUNK_SIZE_DEFAULT = 1000 + # Default value for API request timeout ins econds + API_TIMEOUT_DEFAULT = 20 + # Number of times to retry an API call if it times out + MAX_RETRY_COUNT_ON_TIMEOUT_DEFAULT = 3 + # Number of threads to fetch assets with in parallel + # Deprecated + THREADS_DEFAULT = 4 + # Maximum number of threads to fetch assets with in parallel + THREADS_MAX = 20 + + # List of allowed share user roles + SHARE_ROLES = [AlbumUserRole.EDITOR, AlbumUserRole.VIEWER] + + def __init__(self, api_url: str, api_key: str, api_client_config: ApiClientConfig): + """ + :param api_url: The Immich Server's API base URL + :param api_key: The Immich API key to use for authentication + :param conifg: The API client configuration + :raises AssertionError: When validation of options failed + """ + # The Immich API URL to connect to + self.api_url: str = api_url + # The API key to use + self.api_key: str = api_key + # Addditional configuration + self.config: ApiClientConfig = api_client_config + + self.__validate_config() + + # Define internal variables for long-lived loop keeping our ClientSession alive + self._loop: Optional[asyncio.AbstractEventLoop] = None + self._thread: Optional[threading.Thread] = None + self._session: Any = None # aiohttp.ClientSession + self._session_fut: Optional[Future[None]] = None + self._closing = threading.Event() + self._closed = threading.Event() + self._active_futures: set[Future[Any]] = set() + self._active_futures_lock = threading.Lock() + + self.server_version: ServerVersionResponseDto | None = None + + self._is_docker = bool(os.environ.get(ENV_IS_DOCKER, False)) + + def __validate_config(self): + """ + Validates all set configuration values. + + :raises: ValueError if any config value does not pass validation + """ + Utils.assert_not_none_or_empty("api_url", self.api_url) + Utils.assert_not_none_or_empty("api_key", self.api_key) + Utils.assert_not_none_or_empty("chunk_size", self.config.chunk_size) + Utils.assert_not_none_or_empty("fetch_chunk_size", self.config.fetch_chunk_size) + Utils.assert_not_none_or_empty("api_timeout", self.config.api_timeout) + Utils.assert_not_none_or_empty("insecure", self.config.insecure) + Utils.assert_not_none_or_empty("threads", self.config.threads) + + if not Utils.is_integer(self.config.chunk_size) or self.config.chunk_size < 1: + raise ValueError("chunk_size must be an integer > 0!") + + if ( + not Utils.is_integer(self.config.fetch_chunk_size) + or self.config.fetch_chunk_size < 1 + ): + raise ValueError("fetch_chunk_size must be an integer > 0!") + + if not Utils.is_integer(self.config.api_timeout) or self.config.api_timeout < 1: + raise ValueError("api_timeout must be an integer > 0!") + + if ( + not Utils.is_integer(self.config.threads) + or self.config.threads < 1 + or self.config.threads > ApiClient.THREADS_MAX + ): + raise ValueError( + f"api_timeout must be an integer between 1 and {ApiClient.THREADS_MAX}!" + ) + + async def __aenter__(self) -> "ApiClient": + self._loop = asyncio.new_event_loop() + + def run_loop() -> None: + asyncio.set_event_loop(self._loop) + + try: + self._loop.run_forever() + finally: + # Cancel anything still pending on the API loop. + pending = asyncio.all_tasks(self._loop) + + for task in pending: + task.cancel() + + if pending: + self._loop.run_until_complete( + asyncio.gather(*pending, return_exceptions=True) + ) + + self._loop.run_until_complete(self._loop.shutdown_asyncgens()) + self._loop.close() + + self._thread = threading.Thread( + target=run_loop, + name="immich-api-client-loop", + daemon=False, + ) + self._thread.start() + + async def create_session() -> None: + connector = TCPConnector( + ssl=not self.config.insecure, + use_dns_cache=True, + ttl_dns_cache=900, + ) + + self._session = ClientSession( + timeout=ClientTimeout(total=self.config.api_timeout), + connector=connector, + ) + + self._session_fut = self._submit(create_session()) + await asyncio.wrap_future(self._session_fut) + + # Verify server communication + self.server_version: ServerVersionResponseDto | None = ( + self.__fetch_server_version_safe() + ) + if self.server_version is None: + raise AssertionError( + "Communication with Immich Server API failed! Make sure the API URL is correct and verify the API Key!" + ) + + return self + + async def __aexit__( + self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: Any + ) -> None: + if self._closed.is_set(): + return + + self._closing.set() + + loop = self._loop + thread = self._thread + + if loop is None or thread is None: + self._closed.set() + return + + async def close_session() -> None: + if self._session is not None and not self._session.closed: + await self._session.close() + + try: + # Cancel API calls waiting in Future.result(). + with self._active_futures_lock: + futures = list(self._active_futures) + + for future in futures: + future.cancel() + + # Close aiohttp on the event-loop thread. + close_future = asyncio.run_coroutine_threadsafe( + close_session(), + loop, + ) + + try: + await asyncio.wrap_future(close_future) + except asyncio.CancelledError: + close_future.cancel() + with contextlib.suppress(Exception): + await asyncio.wrap_future(close_future) + raise + + finally: + # Stop the loop only after session cleanup has completed. + loop.call_soon_threadsafe(loop.stop) + + # __aexit__ runs on the main thread, so joining here is safe. + thread.join(timeout=10) + + if thread.is_alive(): + logging.error("API event-loop thread did not stop cleanly") + + self._closed.set() + + def __run_in_loop(self, coro: Coroutine[object, object, T]) -> T: + """ + Passes the coroutine to the long-living loop and returns the result + + :param coro: The coroutine to run asynchronously + :returns: The routine's result + :rtype: T + """ + future = self._submit(coro) + + try: + return future.result() + except KeyboardInterrupt: + # Ctrl+C happened while waiting for an API operation. + future.cancel() + raise + + def _submit(self, coro: Coroutine[Any, Any, T]) -> Future[T]: + if self._closing.is_set(): + # Avoid leaking an unawaited coroutine if shutdown already started. + coro.close() + raise RuntimeError("ApiClient is shutting down") + + if self._loop is None or self._loop.is_closed(): + coro.close() + raise RuntimeError("ApiClient event loop is not running") + + future = asyncio.run_coroutine_threadsafe(coro, self._loop) + + with self._active_futures_lock: + self._active_futures.add(future) + + def remove_future(done: Future[Any]) -> None: + with self._active_futures_lock: + self._active_futures.discard(done) + + future.add_done_callback(remove_future) + return future + + def _is_retryable(self, e: BaseException) -> bool: + """ + Checks if the exception is retryable. + + :param e: The exception to check + :returns: True if the exception is retryable, otherwise False + :rtype: bool + """ + return isinstance(e, asyncio.TimeoutError) or ( + isinstance(e, ApiException) and e.status in {429, 500, 502, 503, 504} + ) + + def __request_api(self, fn: Callable[[AsyncClient], Awaitable[T]]) -> T: + """ + Run an Immich client API call. Creates an AsyncClient with self.api_key and self.api_url, + passes it to fn, runs the returned awaitable, and handles ApiException and generic + exceptions (log and re-raise). Return type is inferred from the callable. + + :param fn: Callable that receives the AsyncClient and returns an awaitable (e.g. lambda c: c.server.get_server_version()). + :returns: The API method return value. + :raises: ApiException or Exception on failure. + """ + + async def runner() -> T: + async def call_once() -> T: + if self._session is None: + raise RuntimeError("ClientSession not initialized") + + async with AsyncClient( + api_key=self.api_key, + base_url=self.api_url, + http_client=self._session, + ) as client: + return await fn(client) + + async for attempt in AsyncRetrying( + retry=retry_if_exception_type(Exception) + & retry_if_exception(self._is_retryable), + wait=wait_exponential(multiplier=1, min=1, max=30), + stop=stop_after_attempt(self.config.max_retry_count), + reraise=True, + ): + with attempt: + return await call_once() + + raise RuntimeError("Should never reach here") + + try: + return self.__run_in_loop(runner()) + except ApiException as e: + msg = e.body if e.body else "API error" + logging.error("%s (status %s)", msg, e.status) + logging.debug(traceback.format_exc()) + raise + except asyncio.TimeoutError as e: + logging.error("Timeout error: %s", str(e).strip()) + logging.debug(traceback.format_exc()) + raise + except Exception as e: + logging.error("Unexpected error: %s", str(e).strip()) + logging.debug(traceback.format_exc()) + raise + + def fetch_server_version(self) -> ServerVersionResponseDto: + """ + Fetches the API version from the immich server. + + If the API endpoint for getting the server version cannot be reached, + raises HTTPError + + :returns: ServerVersionResponseDto + :rtype: ServerVersionResponseDto + :raises ValueError: If the server version is not valid + :raises ApiException: If the API call fails + """ + server_version = self.__request_api(lambda c: c.server.get_server_version()) + try: + assert server_version.major is not None + assert server_version.minor is not None + assert server_version.patch is not None + except AssertionError as e: + raise ValueError from e + logging.info( + "Detected Immich server version %s.%s.%s", + server_version.major, + server_version.minor, + server_version.patch, + ) + return server_version + + # pylint: disable=W0718 + # Catching too general exception Exception (broad-exception-caught + # That's the whole point of this method + def __fetch_server_version_safe(self) -> Optional[ServerVersionResponseDto]: + """ + Fetches the API version from the Immich server, suppressing any raised errors. + On error, an error message is getting logged to ERRRO level, and the exception stacktrace + is logged to DEBUG level. + + :returns: ServerVersionResponseDto or None in case of an error + :rtype: ServerVersionResponseDto + """ + try: + return self.fetch_server_version() + except Exception: + # JSONDecodeError happens if the URL is valid, but does not return valid JSON + # Anything below this line is deemed an error + logging.debug("Error requesting server version!") + logging.debug(traceback.format_exc()) + return None + + def fetch_assets( + self, is_not_in_album: bool, visibility_options: list[AssetVisibility] + ) -> list[AssetResponseDto]: + """ + Fetches assets from the Immich API. + + Uses the /search/meta-data call. Much more efficient than the legacy method + since this call allows to filter for assets that are not in an album only. + + :param is_not_in_album: Flag indicating whether to fetch only assets that are not part + of an album or not. If set to False, will find images in albums and not part of albums + :param visibility_options: A list of visibility options to find and return assets with + :returns: An array of asset objects + :rtype: list[AssetResponseDto] + """ + asset_list: list[AssetResponseDto] = [] + + try: + asset_list = self.fetch_assets_with_options( + MetadataSearchDto( + is_not_in_album=is_not_in_album, visibility=AssetVisibility.TIMELINE + ) + ) + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + for visiblity_option in visibility_options: + # Do not fetch agin for 'timeline', that's the default! + if visiblity_option != AssetVisibility.TIMELINE: + asset_list += self.fetch_assets_with_options( + MetadataSearchDto( + is_not_in_album=is_not_in_album, visibility=visiblity_option + ) + ) + except BadRequestException: + # { "filter": {"hasAlbums": { "eq": false}, "visibility": { "in" : ["timeline", "archive", "hidden"]} }} + search_filter: SearchFilter = SearchFilter( + visibility=EnumFilterAssetVisibility( + var_in=list(set(visibility_options + [AssetVisibility.TIMELINE])) + ) + ) + # Only add the hasAlbums filter if we only want assets that are not assigned to any album + # Otherwise omit the filter completely to get assets in albums as well as assets without albums + if is_not_in_album: + search_filter.hasAlbums = BoolFilter(eq=not is_not_in_album) + asset_list = self.fetch_assets_with_filter(search_filter) + + return asset_list + + # pylint: disable=R0914 + def fetch_assets_with_filter( + self, search_filter: SearchFilter + ) -> list[AssetResponseDto]: + """ + Fetches assets from the Immich API the specififed search filter. + Assets are retreived in parallel based on configured number of threads. + + :param search_filter: SearchFilter object containing all filter options to use + :returns: An array of asset objects + :rtype: list[AssetResponseDto] + """ + assets_found: list[AssetResponseDto] = [] + # prepare request body + + # Record time when we started fetching + start_time = perf_counter() + query_count: int = 0 + cursor: str = None + + while query_count == 0 or cursor is not None: + query_count += 1 + response = self.__fetch_asset_chunk(search_filter, cursor) + assets_found = assets_found + response.assets.items + logging.debug( + "Received %s assets with chunk %s (cursor %s)", + len(response.assets.items), + query_count, + cursor, + ) + cursor = response.assets.next_cursor + logging.debug("Next cursor = %s", response.assets.next_cursor) + + end_time = perf_counter() + logging.info( + "Fetching %s assets with %s thread took %s s", + len(assets_found), + 1, + round(end_time - start_time, 2), + ) + return assets_found + + # pylint: disable=R0914 + def fetch_assets_with_options( + self, search_options: MetadataSearchDto + ) -> list[AssetResponseDto]: + """ + Deprecated: Use fetch_assets_with_filter() instead! + + Fetches assets from the Immich API using specific search options. + The search options directly correspond to the body used for the search API request. + Assets are retreived in parallel based on configured number of threads. + + :param search_options: Dictionary containing options to pass to the search/metadata API endpoint + :returns: An array of asset objects + :rtype: list[AssetResponseDto] + """ + assets_found: list[AssetResponseDto] = [] + # prepare request body + # This API call allows a maximum page size of 1000 + number_of_assets_to_fetch_per_request_search = min( + 1000, self.config.fetch_chunk_size + ) + search_options.size = number_of_assets_to_fetch_per_request_search + # Initial API call, let's fetch our first chunk + page = 1 + # Record time when we started fetching + start_time = perf_counter() + page_fetched, response = self.__fetch_asset_chunk_with_options( + search_options, page + ) + assets_received = response.assets.items + assets_found = assets_found + assets_received + logging.debug( + "Received %s assets with chunk %s", len(assets_received), page_fetched + ) + + page += 1 + # Create a callable with the static arguments already set, we're going to iterate over the page to fetch only. + partial_fetch_asset_chunk = partial( + self.__fetch_asset_chunk_with_options, search_options + ) + # If we got a full chunk size back, let's perform subsequent calls until we get less than a full chunk size + asset_count_received_with_chunk = len(assets_received) + while ( + asset_count_received_with_chunk + == number_of_assets_to_fetch_per_request_search + ): + pages_to_fetch_in_parallel = list(range(page, page + self.config.threads)) + with ThreadPoolExecutor(max_workers=self.config.threads) as exe: + # Maps the method 'cube' with a list of values. + results = exe.map(partial_fetch_asset_chunk, pages_to_fetch_in_parallel) + + for page_fetched, result in results: + assets_received = result.assets.items + # Remember the minimum number of assets received with any chunk; if there is a chunk with + # less than our chunk size we know we fetched everything. + asset_count_received_with_chunk = min( + asset_count_received_with_chunk, len(assets_received) + ) + # Determine the fetched page from the results; if there is a next page, the current page is next page - 1. If there is + # no next page, it was the last. + # page_fetched : str = str(int(result['assets']['nextPage']) - 1) if result['assets']['nextPage'] is not None else 'last' + logging.debug( + "Received %s assets with chunk %s", + len(assets_received), + page_fetched, + ) + assets_found = assets_found + assets_received + + # advance page by number of parallel threads + page = page + self.config.threads + end_time = perf_counter() + logging.info( + "Fetching %s assets with %s threads took %s s", + len(assets_found), + self.config.threads, + round(end_time - start_time, 2), + ) + return assets_found + + def __fetch_asset_chunk_with_options( + self, search_options: MetadataSearchDto, page: int + ) -> Tuple[int, SearchResponseDto]: + """ + Deprecated: Use __fetch_asset_chunk() instead! + + Fetches a single page of assets from the Immich API using specific search options. + + :param search_options: MetadataSearchDto containing options to pass to the search/metadata API endpoint + :param page: The result page to fetch + :returns: A tuple with the fetched page as first argument and the returned SearchResponseDto as second argument + :rtype: Tuple[int, SearchResponseDto] + """ + + # copy search options, since we are going to insert the page number + metadata_search_dto = search_options.model_copy(update={"page": page}) + logging.debug("requesting %s", metadata_search_dto) + r = self.__request_api(lambda c: c.search.search_assets(metadata_search_dto)) + + return (page, r) + + def __fetch_asset_chunk( + self, search_filter: SearchFilter, cursor: None | str + ) -> SearchResponseDto: + """ + Fetches a single page of assets from the Immich API using specific search options and cursor. + If cursor is None, it is not passed to the API, starting a new search + + :param search_filter: SearchFilter containing options to pass to the search/metadata API endpoint + :param cursor: The cursor for the result page to fetch + :returns: The SearchResponseDto returned by the API + :rtype: SearchResponseDto + """ + # This API call allows a maximum page size of 1000 + number_of_assets_to_fetch_per_request_search = min( + 1000, self.config.fetch_chunk_size + ) + + # copy search options, since we are going to insert the cursor and size + metadata_search_dto: MetadataSearchDto = MetadataSearchDto( + filter=search_filter.model_copy(deep=True) + ) + metadata_search_dto.size = number_of_assets_to_fetch_per_request_search + metadata_search_dto.cursor = cursor + + logging.debug("requesting %s", metadata_search_dto) + return self.__request_api(lambda c: c.search.search_assets(metadata_search_dto)) + + def fetch_albums(self) -> list[AlbumResponseDto]: + """ + Fetches albums from the Immich API + + :returns: A list of album objects + :rtype: list[AlbumResponseDto] + """ + return self.__request_api(lambda c: c.albums.get_all_albums(is_owned=True)) + + def fetch_album_info(self, album_id_for_info: UUID) -> AlbumResponseDto: + """ + Fetches information about a specific album + + :param album_id_for_info: The ID of the album to fetch information for + + :returns: A AlbumResponseDto containing album information + :rtype: AlbumResponseDto + """ + + return self.__request_api( + lambda c: c.albums.get_album_info(id=album_id_for_info) + ) + + def delete_album(self, album_delete_id: UUID) -> bool: + """ + Deletes an album identified by album_delete_id + + If the album could not be deleted, logs an error. + + :param album_delete_id: The ID of the album to delete + + :returns: True if the album was deleted, otherwise False + :rtype: bool + """ + logging.debug("Deleting Album: Album ID = %s", album_delete_id) + try: + self.__request_api(lambda c: c.albums.delete_album(id=album_delete_id)) + return True + except Exception as e: + logging.error("Error deleting album %s: %s", album_delete_id, e) + return False + + def create_album(self, album_name_to_create: str) -> UUID: + """ + Creates an album with the provided name and returns the ID of the created album + + + :param album_name_to_create: Name of the album to create + + :returns: The ID of the created album + :rtype: str + + :raises: Exception if the API call failed + """ + + return self.__request_api( + lambda c: c.albums.create_album( + CreateAlbumDto(albumName=album_name_to_create) + ) + ).id + + def add_assets_to_album( + self, assets_add_album_id: UUID, asset_list: list[UUID] + ) -> list[UUID]: + """ + Adds the assets IDs provided in assets to the provided albumId. + + If assets if larger than self.chunk_size, the list is chunked + and one API call is performed per chunk. + Only logs errors and successes. + + Returns + + :param assets_add_album_id: The ID of the album to add assets to + :param asset_list: A list of asset IDs to add to the album + + :returns: The asset UUIDs that were actually added to the album (not respecting assets that were already part of the album) + :rtype: list[str] + """ + asset_list_added: list[UUID] = [] + for assets_chunk in list( + Utils.divide_chunks(asset_list, self.config.chunk_size) + ): + r = self.__request_api( + lambda c, chunk=assets_chunk: c.albums.add_assets_to_album( + id=assets_add_album_id, bulk_ids_dto=BulkIdsDto(ids=chunk) + ) + ) + for res in r: + if not res.success: + if res.error != "duplicate": + logging.warning( + "Error adding an asset to an album: %s", res.error + ) + else: + asset_list_added.append(res.id) + + return asset_list_added + + def fetch_users(self) -> list[UserResponseDto]: + """ + Queries and returns all users + + :returns: A list of user objects + :rtype: list[UserResponseDto] + """ + + return self.__request_api(lambda c: c.users.search_users()) + + def unshare_album_with_user( + self, album_id_to_unshare: UUID, unshare_user_id: str + ) -> None: + """ + Unshares the provided album with the provided user + + :param album_id_to_unshare: The ID of the album to unshare + :param unshare_user_id: The user ID to remove from the album's share list + + :raises: Exception if the API call fails + """ + self.__request_api( + lambda c: c.albums.remove_user_from_album( + id=album_id_to_unshare, user_id=unshare_user_id + ) + ) + + def update_album_share_user_role( + self, + album_id_to_share: UUID, + share_user_id: str, + share_user_role: AlbumUserRole, + ) -> None: + """ + Updates the user's share role for the provided album ID. + + :param album_id_to_share: The ID of the album to share + :param share_user_id: The user ID to update the share role for + :param share_user_role: The share role to update the user to + + :raises: Exception if the API call fails + """ + self.__request_api( + lambda c: c.albums.update_album_user( + id=album_id_to_share, + user_id=share_user_id, + update_album_user_dto=UpdateAlbumUserDto(role=share_user_role), + ) + ) + + def share_album_with_user_and_role( + self, + album_id_to_share: UUID, + user_ids_to_share_with: list[str], + user_share_role: AlbumUserRole, + ) -> None: + """ + Shares the album with the provided album_id with all provided share_user_ids + using share_role as a role. + + :param album_id_to_share: The ID of the album to share + :param user_ids_to_share_with: IDs of users to share the album with + :param user_share_role: The share role to use when sharing the album, valid values are `viewer` or `editor` + :raises: AssertionError if user_share_role contains an invalid value + :raises: HTTPError if the API call fails + """ + self.__request_api( + lambda c: c.albums.add_users_to_album( + id=album_id_to_share, + add_users_dto=AddUsersDto( + albumUsers=[ + AlbumUserAddDto(userId=user_id, role=user_share_role) + for user_id in user_ids_to_share_with + ] + ), + ) + ) + + def trigger_offline_asset_removal(self) -> None: + """ + Synchronously deletes offline assets. + + Uses the searchMetadata endpoint to find all assets marked as offline, then + issues a delete call for these asset UUIDs. + + :raises: Exception if any API call fails + """ + offline_assets: list[AssetResponseDto] = [] + # To find all offline assets we need to check for each possible visibility + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + try: + for visibility_setting in AssetVisibility: + # exclude locked folder + if visibility_setting == AssetVisibility.LOCKED: + continue + try: + offline_assets += self.fetch_assets_with_options( + MetadataSearchDto( + is_offline=True, visibility=visibility_setting + ) + ) + except UnauthorizedException: + logging.warning( + "Admin-level API key required to check for offline assets in locked folder, skipping..." + ) + except BadRequestException: + # Single search: { "filter": {"isOffline": { "eq": true}, "visibility": { "in" : ["timeline", "archive", "hidden"]}} } + search_filter: SearchFilter = SearchFilter( + isOffline=BoolFilter(eq=True), + visibility=EnumFilterAssetVisibility( + var_in=[ + AssetVisibility.TIMELINE, + AssetVisibility.ARCHIVE, + AssetVisibility.HIDDEN, + ] + ), + ) + offline_assets = self.fetch_assets_with_filter(search_filter) + + if len(offline_assets) > 0: + logging.info("Deleting %s offline assets", len(offline_assets)) + logging.debug( + "Deleting the following offline assets (count: %d): %s", + len(offline_assets), + [asset.original_file_name for asset in offline_assets], + ) + self.delete_assets(offline_assets, True) + else: + logging.info("No offline assets found!") + + def delete_assets( + self, assets_to_delete: list[AssetResponseDto], force: bool + ) -> None: + """ + Deletes the provided assets from Immich. + + :param assets_to_delete: A list of asset objects with key `id` + :param force: Force flag to pass to the API call + + :raises: Exception if the API call fails + """ + + self.__request_api( + lambda c: c.assets.delete_assets( + asset_bulk_delete_dto=AssetBulkDeleteDto( + ids=[asset.id for asset in assets_to_delete], force=force + ) + ) + ) + + def fetch_libraries(self) -> list[LibraryResponseDto]: + """ + Queries and returns all libraries + + :raises: Exception if any API call fails + """ + + return self.__request_api(lambda c: c.libraries.get_all_libraries()) + + def set_album_thumb( + self, thumbnail_album_id: UUID, thumbnail_asset_id: str + ) -> None: + """ + Sets asset as thumbnail of album + + :param thumbnail_album_id: The ID of the album for which to set the thumbnail + :param thumbnail_asset_id: The ID of the asset to be set as thumbnail + + :raises: Exception if the API call fails + """ + self.__request_api( + lambda c: c.albums.update_album_info( + id=thumbnail_album_id, + update_album_dto=UpdateAlbumDto( + albumThumbnailAssetId=thumbnail_asset_id + ), + ) + ) + + def update_album_properties(self, album_to_update: AlbumModel) -> None: + """ + Sets album properties in Immich to the properties of the AlbumModel + + :param album_to_update: The album model to use for updating the album + + :raises: Exception if the API call fails + """ + data = UpdateAlbumDto( + description=album_to_update.description, + order=album_to_update.sort_order, + is_activity_enabled=album_to_update.comments_and_likes_enabled, + album_thumbnail_asset_id=album_to_update.thumbnail_asset_uuid, + ) + assert album_to_update.id is not None, "Album ID must be set" + self.__request_api( + lambda c: c.albums.update_album_info( + id=album_to_update.id, update_album_dto=data + ) + ) + + def set_assets_visibility( + self, asset_ids_for_visibility: list[UUID], visibility_setting: AssetVisibility + ) -> None: + """ + Sets the visibility of assets identified by the passed list of UUIDs. + + :param asset_ids_for_visibility: A list of asset IDs to set visibility for + :param visibility_setting: The visibility to set + + :raises: Exception if the API call fails + """ + self.__request_api( + lambda c: c.assets.update_assets( + asset_bulk_update_dto=AssetBulkUpdateDto( + ids=asset_ids_for_visibility, visibility=visibility_setting + ) + ) + ) + + def delete_all_albums( + self, assets_visibility: AssetVisibility | None, force_delete: bool + ): + """ + Deletes all albums in Immich if force_delete is True. Otherwise lists all albums + that would be deleted. + If assets_visibility is set, all assets in deleted albums + will be set to that visibility. + + :param assets_visibility: The visibility to set for assets for which an album was deleted. Can be used to. e.g. revert archival + :param force_delete: Flag indicating whether to actually delete albums (True) or only to perform a dry-run (False) + + :raises: HTTPError if the API call fails + """ + + all_albums = self.fetch_albums() + logging.info("%d existing albums identified", len(all_albums)) + # Delete Confirm check + if not force_delete: + album_names = [] + for album_to_delete in all_albums: + album_names.append(album_to_delete.album_name) + print("Would delete the following albums (ALL albums!):") + print(album_names) + if self._is_docker: + print( + "Run the container with environment variable DELETE_CONFIRM set to 1 to actually delete these albums!" + ) + else: + print("Call with --delete-confirm to actually delete albums!") + sys.exit(0) + + deleted_album_count = 0 + for album_to_delete in all_albums: + # Fetch assets before delete so we can set visibility after; once deleted, album is gone + assets_in_deleted_album: list[AssetResponseDto] = [] + if assets_visibility is not None: + # { "filter": {"albumIds": { "all": ["9eab1ebe-c998-4bdc-a2cc-1722c719e292"]}}} + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + try: + assets_in_deleted_album = self.fetch_assets_with_options( + MetadataSearchDto(album_ids=[album_to_delete.id]) + ) + except BadRequestException: + # { "filter": {"albumIds": { "all": ["9eab1ebe-c998-4bdc-a2cc-1722c719e292"]}}} + search_filter: SearchFilter = SearchFilter( + album_ids=IdsFilter(all=[album_to_delete.id]) + ) + assets_in_deleted_album = self.fetch_assets_with_filter( + search_filter + ) + if self.delete_album(album_to_delete.id): + logging.info("Deleted album %s", album_to_delete.album_name) + deleted_album_count += 1 + if assets_in_deleted_album and assets_visibility is not None: + self.set_assets_visibility( + [asset.id for asset in assets_in_deleted_album], + assets_visibility, + ) + logging.info( + "Set visibility for %d assets to %s", + len(assets_in_deleted_album), + assets_visibility.value, + ) + logging.info("Deleted %d/%d albums", deleted_album_count, len(all_albums)) + + def cleanup_albums( + self, + albums_to_delete: list[AlbumModel], + asset_visibility: AssetVisibility | None, + force_delete: bool, + ) -> int: + """ + Instead of creating, deletes albums in Immich if force_delete is True. Otherwise lists all albums + that would be deleted. + If unarchived_assets is set to true, all archived assets in deleted albums + will be unarchived. + + :param albums_to_delete: A list of AlbumModel records to delete + :param asset_visibility: The visibility to set for assets for which an album was deleted. Can be used to e.g. revert archival + :param force_delete: Flag indicating whether to actually delete albums (True) or only to perform a dry-run (False) + + :returns: Number of successfully deleted albums + :rtype: int + + :raises: HTTPError if the API call fails + """ + # Delete Confirm check + if not force_delete: + print("Would delete the following albums:") + print([a.get_final_name() for a in albums_to_delete]) + if self._is_docker: + print( + "Run the container with environment variable DELETE_CONFIRM set to 1 to actually delete these albums!" + ) + else: + print(" Call with --delete-confirm to actually delete albums!") + return 0 + + # At this point force_delete is true! + cpt = 0 + for album_to_delete in albums_to_delete: + assert album_to_delete.id is not None, "Album ID must be set" + # If the archived flag is set it means we need to unarchived all images of deleted albums; + # In order to do so, we need to fetch all assets of the album we're going to delete + assets_in_album: list[AssetResponseDto] = [] + # For cleanup, we only respect the global visibility flag to be able to either do not change + # visibility at all, or to override whatever might be set in .ablumprops and revert to something else + if asset_visibility is not None: + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + try: + assets_in_album = self.fetch_assets_with_options( + MetadataSearchDto(album_ids=[album_to_delete.id]) + ) + except BadRequestException: + # filter: { "filter": {"albumIds": { "all": ["9eab1ebe-c998-4bdc-a2cc-1722c719e292"]}}} + search_filter: SearchFilter = SearchFilter( + album_ids=IdsFilter(all=[album_to_delete.id]) + ) + assets_in_album = self.fetch_assets_with_filter(search_filter) + if self.delete_album(album_to_delete.id): + logging.info("Deleted album %s", album_to_delete.get_final_name()) + cpt += 1 + # Archive flag is set, so we need to unarchive assets + if asset_visibility is not None and len(assets_in_album) > 0: + self.set_assets_visibility( + [asset.id for asset in assets_in_album], asset_visibility + ) + logging.info( + "Set visibility for %d assets to %s", + len(assets_in_album), + asset_visibility.value, + ) + return cpt + + # Disable pylint for too many branches + # pylint: disable=R0912,R0914 + def update_album_shared_state( + self, + album_to_share: AlbumModel, + unshare_users: bool, + known_users: list[UserResponseDto], + ) -> None: + """ + Makes sure the album is shared with the users set in the model with the correct roles. + This involves fetching album info from Immich to check if/who the album is shared with and the share roles, + then either updating the share role, removing the user, or adding the users + + :param album_to_share: The album to share, with the expected share_with setting + :param unshare_users: Flag indicating whether to actively unshare albums if shared with a user that is not in the current share settings + :param known_users: A list of all users Immich knows to find the user IDs to share/unshare with + + :raises: HTTPError if the API call fails + """ + assert album_to_share.id is not None, "Album ID must be set" + # Parse and prepare expected share roles + # List all share users by share role + share_users_to_roles_expected: dict[str, AlbumUserRole] = {} + for share_user in album_to_share.share_with: + # Find the user by configured name or email + share_user_in_immich = FolderAlbumCreator.find_user_by_name_or_email( + share_user.user, known_users + ) + if not share_user_in_immich: + logging.warning( + "User %s to share album %s with does not exist!", + share_user.user, + album_to_share.get_final_name(), + ) + continue + # Use 'viewer' as default role if not specified + share_role_local = share_user.role or AlbumUserRole.VIEWER + share_users_to_roles_expected[str(share_user_in_immich.id)] = ( + share_role_local + ) + + # No users to share with and unsharing is disabled? + if len(share_users_to_roles_expected) == 0 and not unshare_users: + return + + # Now fetch reality + album_to_share_info = self.fetch_album_info(album_to_share.id) + # Dict mapping a user ID to share role + album_share_info: dict[str, AlbumUserRole] = {} + for share_user_actual in album_to_share_info.album_users: + album_share_info[str(share_user_actual.user.id)] = share_user_actual.role + # Group share users by share role + share_roles_to_users_expected: dict[AlbumUserRole, list[str]] = defaultdict( + list + ) + # Now compare expectation with reality and update + for ( + user_to_share_with, + share_role_expected, + ) in share_users_to_roles_expected.items(): + # Case: Album is not share with user + if user_to_share_with not in album_share_info: + # Gather all users to share the album with for this role + share_roles_to_users_expected[share_role_expected].append( + user_to_share_with + ) + + # Case: Album is shared, but with wrong role except if the user to share with is already the owner + elif ( + album_share_info[user_to_share_with] != share_role_expected + and album_share_info[user_to_share_with] != AlbumUserRole.OWNER + ): + try: + self.update_album_share_user_role( + album_to_share.id, user_to_share_with, share_role_expected + ) + print(share_role_expected) + logging.debug( + "Sharing: Updated share role for user %s in album %s to %s", + user_to_share_with, + album_to_share.get_final_name(), + share_role_expected.value, + ) + except HTTPError as ex: + logging.warning( + "Sharing: Error updating share role for user %s in album %s to %s", + user_to_share_with, + album_to_share.get_final_name(), + share_role_expected.value, + ) + logging.debug("Error: %s", ex) + + # Now check if the album is shared with any users it should not be shared with + if unshare_users: + for shared_user, shared_user_role in album_share_info.items(): + # We never remove the owner + if shared_user_role == AlbumUserRole.OWNER: + continue + if shared_user not in share_users_to_roles_expected: + try: + self.unshare_album_with_user(album_to_share.id, shared_user) + logging.debug( + "Sharing: User %s removed from album %s", + shared_user, + album_to_share.get_final_name(), + ) + except HTTPError as ex: + logging.warning( + "Sharing: Error removing user %s from album %s", + shared_user, + album_to_share.get_final_name(), + ) + logging.debug("Error: %s", ex) + + # Now share album with all users it is not already shared with + if len(share_roles_to_users_expected) > 0: + # Share album for users by role + for share_role_group, share_users in share_roles_to_users_expected.items(): + # Convert list of user dicts to list of user IDs + try: + self.share_album_with_user_and_role( + album_to_share.id, share_users, share_role_group + ) + logging.debug( + "Album %s shared with users IDs %s in role: %s", + album_to_share.get_final_name(), + share_users, + share_role_group.value, + ) + except (AssertionError, HTTPError) as ex: + logging.warning( + "Error sharing album %s for users %s in role %s", + album_to_share.get_final_name(), + share_users, + share_role_group.value, + ) + logging.debug("Album share error: %s", ex) + + +class AlbumMergeError(Exception): + """Error thrown when trying to override an existing property""" + + +class AlbumModelValidationError(Exception): + """Error thrown when validating album model plausibility fails""" + + +# Disable pylint rule for too many instance attributes +# pylint: disable=R0902 +class AlbumModel: + """Model of an album with all properties necessary for handling albums in the scope of this script""" + + # Album Merge Mode indicating only properties should be merged that are + # not already set in the merge target + ALBUM_MERGE_MODE_EXCLUSIVE = 1 + # Same as ALBUM_MERGE_MODE_EXCLUSIVE, but also raises an error + # if attempting to overwrite an existing property when merging + ALBUM_MERGE_MODE_EXCLUSIVE_EX = 2 + # Override any property in the merge target if already exists + ALBUM_MERGE_MODE_OVERRIDE = 3 + # List of class attribute names that are relevant for album properties handling + # This list is used for album model merging and validation + ALBUM_PROPERTIES_VARIABLES = [ + "override_name", + "description", + "share_with", + "thumbnail_setting", + "sort_order", + "visibility", + "comments_and_likes_enabled", + ] + + # List of class attribute names that are relevant for inheritance + ALBUM_INHERITANCE_VARIABLES = ["inherit", "inherit_properties"] + + @dataclass + class ShareWith: + """Represents a user to share an album with and their role.""" + + user: str + role: Optional[AlbumUserRole] = None + + def __init__(self, name: str | None): + # The album ID, set after it was created + self.id: Optional[UUID] = None + # The album name + self.name: Optional[str] = name + # The override album name, takes precedence over name for album creation + self.override_name: Optional[str] = None + # The description to set for the album + self.description: Optional[str] = None + # A list of dicts with Immich assets + self.assets: list[AssetResponseDto] = [] + # a list of dicts with keys user and role, listing all users and their role to share the album with + self.share_with: list[AlbumModel.ShareWith] = [] + # Either a fully qualified asset path or one of 'first', 'last', 'random' + self.thumbnail_setting: Optional[str] = None + self.thumbnail_asset_uuid: Optional[UUID] = None + # Sorting order for this album, 'asc' or 'desc' + self.sort_order: Optional[AssetOrder] = None + # String indicating asset visibility, allowed values: archive, locked, timeline + self.visibility: Optional[AssetVisibility] = None + # Boolean indicating whether assets in this albums can be commented on and liked + self.comments_and_likes_enabled: Optional[bool] = None + # Boolean indicating whether properties should be inherited down the directory tree + self.inherit: Optional[bool] = None + # List of property names that should be inherited + self.inherit_properties: Optional[list[str]] = None + + def get_album_properties_dict(self) -> dict[str, Any]: + """ + Returns this class' attributes relevant for album properties handling + as a dictionary + + :returns: A dictionary of all album properties + :rtype: dict + """ + props = dict(vars(self)) + for prop in list(props.keys()): + if prop not in AlbumModel.ALBUM_PROPERTIES_VARIABLES: + del props[prop] + return props + + def __str__(self) -> str: + """ + Returns a string representation of this most important album properties + + :returns: A string for printing this album model's properties + :rtype: str + """ + return str(self.get_album_properties_dict()) + + def get_asset_uuids(self) -> list[UUID]: + """ + Gathers UUIDs of all assets and returns them + + :returns: A list of asset UUIDs + :rtype: list[UUID] + """ + return [asset_to_add.id for asset_to_add in self.assets] + + def find_incompatible_properties(self, other: AlbumModel) -> list[str]: + """ + Checks whether this Album Model and the other album model are compatible in terms of + describing the same album for creation in a way that no album properties are in conflict + with each other. + All properties must either bei the same or not present in both objects, except for + - `id` + - `name` + - `assets` + + :param other: The other album model to check against + + :returns: A list of string representations for incompatible properties. The list is empty + if there are no incompatible properties + :rtype: list[str] + """ + if not isinstance(other, AlbumModel): + return [] + incompatible_props = [] + props = self.get_album_properties_dict() + other_props = other.get_album_properties_dict() + for prop in props: + if props[prop] != other_props[prop]: + incompatible_props.append( + f"{prop}: {props[prop]} vs {other_props[prop]}" + ) + + return incompatible_props + + def merge_from(self, other: AlbumModel, merge_mode: int): + """ + Merges properties of other in self. The only properties not + considered for merging are + - `id` + - `name` + - `assets` + + :param other: The other album model to merge properties from + :param merge_mode: Defines how the merge should be performed: + + - `AlbumModel.ALBUM_MERGE_MODE_EXCLUSIVE`: Only merge properties that are not already set in the merge target + - `AlbumModel.ALBUM_MERGE_MODE_EXCLUSIVE_EX`: Same as above, but also raises an exception if attempting to merge an existing property + - `AlbumModel.ALBUM_MERGE_MODE_OVERRIDE`: Overrides any existing property in merge target + """ + # Do not try to merge unrelated types + if not isinstance(other, AlbumModel): + logging.warning("Trying to merge AlbumModel with incompatible type!") + return + own_attribs = vars(self) + other_attribs = vars(other) + + # Override merge mode + if merge_mode == AlbumModel.ALBUM_MERGE_MODE_OVERRIDE: + for prop_name in AlbumModel.ALBUM_PROPERTIES_VARIABLES: + if other_attribs[prop_name]: + own_attribs[prop_name] = other_attribs[prop_name] + + # Exclusive merge modes + elif merge_mode in [ + AlbumModel.ALBUM_MERGE_MODE_EXCLUSIVE, + AlbumModel.ALBUM_MERGE_MODE_EXCLUSIVE_EX, + ]: + for prop_name in AlbumModel.ALBUM_PROPERTIES_VARIABLES: + if other_attribs[prop_name]: + if ( + own_attribs[prop_name] + and merge_mode == AlbumModel.ALBUM_MERGE_MODE_EXCLUSIVE_EX + ): + raise AlbumMergeError( + f"Attempting to override {prop_name} in {self.name} with {other_attribs[prop_name]}" + ) + own_attribs[prop_name] = other_attribs[prop_name] + + def merge_inherited_share_with( + self, inherited_share_with: list[AlbumModel.ShareWith] + ) -> list[AlbumModel.ShareWith]: + """ + Merges inherited share_with settings with current share_with settings. + Handles special share_with inheritance logic: + - Users can be added from parent folders + - Users can be removed by setting role to 'none' (and once removed, cannot be re-added) + - User roles follow most restrictive policy: viewer is more restrictive than editor + - Most restrictive role wins when there are conflicts + + :param inherited_share_with: List of inherited share_with settings from parent folders + :return: Merged share_with list + """ + if not inherited_share_with: + return self.share_with if self.share_with else [] + + if not self.share_with: + return inherited_share_with + + # Create a dict to track users by name/email for easier manipulation + user_roles = {} + users_set_to_none = set() # Track users that have been explicitly set to 'none' + + # Add inherited users first + for inherited_user in inherited_share_with: + if inherited_user.role is None: + users_set_to_none.add(inherited_user.user) + else: + user_roles[inherited_user.user] = inherited_user.role + + # Apply current folder's share_with settings + for current_user in self.share_with: + if current_user.role is None: + # Remove user from sharing and mark as explicitly set to none + user_roles.pop(current_user.user, None) + users_set_to_none.add(current_user.user) + elif current_user.user not in users_set_to_none: + # Only add/modify user if they haven't been set to 'none' + if current_user.user in user_roles: + # Apply most restrictive role: viewer is more restrictive than editor + current_role = user_roles[current_user.user] + new_role = current_user.role + + if AlbumUserRole.VIEWER in (current_role, new_role): + user_roles[current_user.user] = AlbumUserRole.VIEWER + else: + user_roles[current_user.user] = new_role + else: + # Add new user with their role + user_roles[current_user.user] = current_user.role + + # Convert back to list format + return [ + AlbumModel.ShareWith(user=user, role=role) + for user, role in user_roles.items() + ] + + def get_final_name(self) -> str: + """ + Gets the album model's name to use when talking to Immich, i.e. + returns override_name if set, otherwise name. + + :returns: override_name if set, otherwise name + :rtype: str + """ + if self.override_name: + return self.override_name + assert self.name is not None, "Album name must be set" + return self.name + + @staticmethod + def parse_album_properties_file(album_properties_file_path: str): + """ + Parses the provided album properties file into an AlbumModel + + :param album_properties_file_path: The fully qualified path to a valid album properties file + + :returns: An AlbumModel that represents the album properties + :rtype: str + + :raises YAMLError: If the provided album properties file could not be found or parsed + """ + try: + with open(album_properties_file_path, "r", encoding="utf-8") as stream: + album_properties = yaml.safe_load(stream) + except UnicodeDecodeError: + logging.warning( + "File '%s' is not UTF-8 encoded. Please save it as UTF-8.", + album_properties_file_path, + ) + raise + + if album_properties: + album_props_template = AlbumModel(None) + album_props_template_vars = vars(album_props_template) + + # Parse standard album properties + for album_prop_name in AlbumModel.ALBUM_PROPERTIES_VARIABLES: + if album_prop_name in album_properties: + value = album_properties[album_prop_name] + # Convert raw dicts from YAML to ShareWith dataclass instances + if album_prop_name == "share_with" and isinstance(value, list): + share_with_list: list[AlbumModel.ShareWith] = [] + for entry in value: + role: AlbumUserRole | None = ( + AlbumUserRole(entry["role"]) + if entry["role"] != "none" + else None + ) + share_with_list.append( + AlbumModel.ShareWith(user=entry["user"], role=role) + ) + value = share_with_list + elif album_prop_name == "visibility": + value = AssetVisibility(value) + album_props_template_vars[album_prop_name] = value + + # Parse inheritance properties + for inheritance_prop_name in AlbumModel.ALBUM_INHERITANCE_VARIABLES: + if inheritance_prop_name in album_properties: + album_props_template_vars[inheritance_prop_name] = album_properties[ + inheritance_prop_name + ] + + return album_props_template + + return None + + +class Configuration: + """A configuration object for the main class, controlling everything from API key, root path and all the other options the script offers""" + + # Constants holding script run modes + # Create albums based on folder names and script arguments + SCRIPT_MODE_CREATE = "CREATE" + # Create album names based on folder names, but delete these albums + SCRIPT_MODE_CLEANUP = "CLEANUP" + # Delete ALL albums + SCRIPT_MODE_DELETE_ALL = "DELETE_ALL" + + # Constants for album thumbnail setting + ALBUM_THUMBNAIL_RANDOM_ALL = "random-all" + ALBUM_THUMBNAIL_RANDOM_FILTERED = "random-filtered" + ALBUM_THUMBNAIL_SETTINGS = ["first", "last", "random"] + ALBUM_THUMBNAIL_SETTINGS_GLOBAL = ALBUM_THUMBNAIL_SETTINGS + [ + ALBUM_THUMBNAIL_RANDOM_ALL, + ALBUM_THUMBNAIL_RANDOM_FILTERED, + ] + ALBUM_THUMBNAIL_STATIC_INDICES = { + "first": 0, + "last": -1, + } + + # Default values for config options that cannot be None + CONFIG_DEFAULTS: dict[str, AlbumUserRole | bool | int | str] = { + "api_key_type": "literal", + "unattended": False, + "album_levels": 1, + "album_separator": " ", + "album_order": False, + "chunk_size": ApiClient.CHUNK_SIZE_DEFAULT, + "fetch_chunk_size": ApiClient.FETCH_CHUNK_SIZE_DEFAULT, + "log_level": "INFO", + "insecure": False, + "mode": SCRIPT_MODE_CREATE, + "delete_confirm": False, + "share_role": AlbumUserRole.VIEWER, + "sync_mode": 0, + "find_assets_in_albums": False, + "find_archived_assets": False, + "read_album_properties": False, + "api_timeout": ApiClient.API_TIMEOUT_DEFAULT, + "comments_and_likes_enabled": False, + "comments_and_likes_disabled": False, + "update_album_props_mode": 0, + "max_retry_count": ApiClient.MAX_RETRY_COUNT_ON_TIMEOUT_DEFAULT, + # Deprecated + "threads": ApiClient.THREADS_DEFAULT, + } + + # Static (Global) configuration options + log_level: str = str(CONFIG_DEFAULTS["log_level"]) + + # Translation of GLOB-style patterns to Regex + # Source: https://stackoverflow.com/a/63212852 + # FIXME_EVENTUALLY: Replace with glob.translate() introduced with Python 3.13 + __escaped_glob_tokens_to_re = OrderedDict( + ( + # Order of ``**/`` and ``/**`` in RE tokenization pattern doesn't matter because ``**/`` will be caught first no matter what, making ``/**`` the only option later on. + # W/o leading or trailing ``/`` two consecutive asterisks will be treated as literals. + ( + "/\\*\\*", + "(?:/.+?)*", + ), # Edge-case #1. Catches recursive globs in the middle of path. Requires edge case #2 handled after this case. + ( + "\\*\\*/", + "(?:^.+?/)*", + ), # Edge-case #2. Catches recursive globs at the start of path. Requires edge case #1 handled before this case. ``^`` is used to ensure proper location for ``**/``. + ( + "\\*", + "[^/]*", + ), # ``[^/]*`` is used to ensure that ``*`` won't match subdirs, as with naive ``.*?`` solution. + ("\\?", "."), + ("\\[\\*\\]", "\\*"), # Escaped special glob character. + ("\\[\\?\\]", "\\?"), # Escaped special glob character. + ( + "\\[!", + "[^", + ), # Requires ordered dict, so that ``\\[!`` preceded ``\\[`` in RE pattern. + # Needed mostly to differentiate between ``!`` used within character class ``[]`` and outside of it, to avoid faulty conversion. + ("\\[", "["), + ("\\]", "]"), + ) + ) + + __escaped_glob_replacement = regex.compile( + "(%s)" % "|".join(__escaped_glob_tokens_to_re).replace("\\", "\\\\\\") + ) + + def __init__(self, args: dict[str, Any]): + """ + Instantiates the configuration object using the provided arguments. + + :param args: A dictionary containing well-defined key-value pairs + """ + self.root_paths = args["root_path"] + self.root_url = args["api_url"] + self.api_key = args["api_key"] + self.chunk_size = Utils.get_value_or_config_default( + "chunk_size", args, Configuration.CONFIG_DEFAULTS["chunk_size"] + ) + self.fetch_chunk_size = Utils.get_value_or_config_default( + "fetch_chunk_size", args, Configuration.CONFIG_DEFAULTS["fetch_chunk_size"] + ) + # D Deprecated + self.threads = Utils.get_value_or_config_default( + "threads", args, Configuration.CONFIG_DEFAULTS["threads"] + ) + if args["threads"] is not None: + logging.warning( + "Using the threads argument is deprecated. It will be removed in a future version!" + ) + self.unattended = Utils.get_value_or_config_default( + "unattended", args, Configuration.CONFIG_DEFAULTS["unattended"] + ) + self.album_levels = Utils.get_value_or_config_default( + "album_levels", args, Configuration.CONFIG_DEFAULTS["album_levels"] + ) + # Album Levels Range handling + self.album_levels_range_arr: tuple[()] = () + self.album_level_separator = Utils.get_value_or_config_default( + "album_separator", args, Configuration.CONFIG_DEFAULTS["album_separator"] + ) + self.album_name_post_regex = args["album_name_post_regex"] + self.album_order = Utils.get_value_or_config_default( + "album_order", args, Configuration.CONFIG_DEFAULTS["album_order"] + ) + self.insecure = Utils.get_value_or_config_default( + "insecure", args, Configuration.CONFIG_DEFAULTS["insecure"] + ) + self.ignore_albums = args["ignore"] + self.mode = Utils.get_value_or_config_default( + "mode", args, Configuration.CONFIG_DEFAULTS["mode"] + ) + self.delete_confirm: bool = Utils.get_value_or_config_default( + "delete_confirm", args, Configuration.CONFIG_DEFAULTS["delete_confirm"] + ) + self.share_with: Optional[list[str]] = args["share_with"] + self.share_role = Utils.get_value_or_config_default( + "share_role", args, Configuration.CONFIG_DEFAULTS["share_role"] + ) + self.sync_mode = Utils.get_value_or_config_default( + "sync_mode", args, Configuration.CONFIG_DEFAULTS["sync_mode"] + ) + self.find_assets_in_albums = Utils.get_value_or_config_default( + "find_assets_in_albums", + args, + Configuration.CONFIG_DEFAULTS["find_assets_in_albums"], + ) + self.path_filter = args["path_filter"] + self.set_album_thumbnail = args["set_album_thumbnail"] + self.visibility: Optional[AssetVisibility] = ( + AssetVisibility(args["visibility"]) if args["visibility"] else None + ) + self.find_archived_assets = Utils.get_value_or_config_default( + "find_archived_assets", + args, + Configuration.CONFIG_DEFAULTS["find_archived_assets"], + ) + self.read_album_properties = Utils.get_value_or_config_default( + "read_album_properties", + args, + Configuration.CONFIG_DEFAULTS["read_album_properties"], + ) + self.api_timeout = Utils.get_value_or_config_default( + "api_timeout", args, Configuration.CONFIG_DEFAULTS["api_timeout"] + ) + self.comments_and_likes_enabled = Utils.get_value_or_config_default( + "comments_and_likes_enabled", + args, + Configuration.CONFIG_DEFAULTS["comments_and_likes_enabled"], + ) + self.comments_and_likes_disabled = Utils.get_value_or_config_default( + "comments_and_likes_disabled", + args, + Configuration.CONFIG_DEFAULTS["comments_and_likes_disabled"], + ) + + self.update_album_props_mode = Utils.get_value_or_config_default( + "update_album_props_mode", + args, + Configuration.CONFIG_DEFAULTS["update_album_props_mode"], + ) + self.max_retry_count = Utils.get_value_or_config_default( + "max_retry_count", args, Configuration.CONFIG_DEFAULTS["max_retry_count"] + ) + + if self.mode != Configuration.SCRIPT_MODE_CREATE: + # Override unattended if we're running in destructive mode + self.unattended = False + + # Create ignore regular expressions + self.ignore_albums_regex: list[str] = ( + args["ignore_regex"] if args["ignore_regex"] is not None else [] + ) + if self.ignore_albums: + for ignore_albums_entry in self.ignore_albums: + self.ignore_albums_regex.append( + Configuration.__glob_to_re( + Configuration.__expand_to_glob(ignore_albums_entry) + ) + ) + + # Create path filter regular expressions + self.path_filter_regex: list[str] = ( + args["path_filter_regex"] if args["path_filter_regex"] is not None else [] + ) + if self.path_filter: + for path_filter_entry in self.path_filter: + self.path_filter_regex.append( + Configuration.__glob_to_re( + Configuration.__expand_to_glob(path_filter_entry) + ) + ) + + # append trailing slash to all root paths + # pylint: disable=C0200 + for i in range(len(self.root_paths)): + if self.root_paths[i][-1] != "/": + self.root_paths[i] = self.root_paths[i] + "/" + + # append trailing slash to root URL + if self.root_url[-1] != "/": + self.root_url = self.root_url + "/" + + self.__validate_config() + # self.api_client = new ApiClient() + + def __validate_config(self): + """ + Validates all set configuration values. + + :raises: ValueError if any config value does not pass validation + """ + Utils.assert_not_none_or_empty("root_path", self.root_paths) + Utils.assert_not_none_or_empty("root_url", self.root_url) + Utils.assert_not_none_or_empty("api_key", self.api_key) + + if self.comments_and_likes_disabled and self.comments_and_likes_enabled: + raise ValueError( + "Arguments --comments-and-likes-enabled and --comments-and-likes-disabled cannot be used together! Choose one!" + ) + + if ( + not Utils.is_integer(self.threads) + or int(self.threads) < 1 + or int(self.threads) > ApiClient.THREADS_MAX + ): + raise ValueError( + f"--threads must be an integer between 1 and {ApiClient.THREADS_MAX}" + ) + self.threads = int(self.threads) + + self.__validate_album_range() + + def __validate_album_range(self): + """ + Performs logic validation for album level range setting. + """ + # Verify album levels range + if not Utils.is_integer(self.album_levels): + album_levels_range_split = self.album_levels.split(",") + if any( + [ + len(album_levels_range_split) != 2, + not Utils.is_integer(album_levels_range_split[0]), + not Utils.is_integer(album_levels_range_split[1]), + int(album_levels_range_split[0]) == 0, + int(album_levels_range_split[1]) == 0, + ( + int(album_levels_range_split[1]) + < 0 + <= int(album_levels_range_split[0]) + ), + ( + int(album_levels_range_split[0]) + < 0 + <= int(album_levels_range_split[1]) + ), + ( + int(album_levels_range_split[0]) < 0 + and int(album_levels_range_split[1]) < 0 + and int(album_levels_range_split[0]) + > int(album_levels_range_split[1]) + ), + ] + ): + raise ValueError( + ( + "Invalid album_levels range format! If a range should be set, the start level and end level must be separated by a comma like ','. " + "If negative levels are used in a range, must be less than or equal to ." + ) + ) + self.album_levels_range_arr = album_levels_range_split + # Convert to int + self.album_levels_range_arr[0] = int(album_levels_range_split[0]) + self.album_levels_range_arr[1] = int(album_levels_range_split[1]) + # Special case: both levels are negative and end level is -1, which is equivalent to just negative album level of start level + if ( + self.album_levels_range_arr[0] < 0 + and self.album_levels_range_arr[1] == -1 + ): + self.album_levels = self.album_levels_range_arr[0] + self.album_levels_range_arr = () + logging.debug( + "album_levels is a range with negative start level and end level of -1, converted to album_levels = %d", + self.album_levels, + ) + else: + logging.debug("valid album_levels range argument supplied") + logging.debug( + "album_levels_start_level = %d", self.album_levels_range_arr[0] + ) + logging.debug( + "album_levels_end_level = %d", self.album_levels_range_arr[1] + ) + # Deduct 1 from album start levels, since album levels start at 1 for user convenience, but arrays start at index 0 + if self.album_levels_range_arr[0] > 0: + self.album_levels_range_arr[0] -= 1 + self.album_levels_range_arr[1] -= 1 + + @staticmethod + def __glob_to_re(pattern: str) -> str: + """ + Converts the provided GLOB pattern to + a regular expression. + + :param pattern: A GLOB-style pattern to convert to a regular expression + + :returns: A regular expression matching the same strings as the provided GLOB pattern + :rtype: str + """ + return Configuration.__escaped_glob_replacement.sub( + lambda match: Configuration.__escaped_glob_tokens_to_re[match.group(0)], + regex.escape(pattern), + ) + + @staticmethod + def __expand_to_glob(expr: str) -> str: + """ + Expands the passed expression to a glob-style + expression if it doesn't contain neither a slash nor an asterisk. + The resulting glob-style expression matches any path that contains the + original expression anywhere. + + :param expr: Expression to expand to a GLOB-style expression if not already one + :returns: The original expression if it contained a slash or an asterisk, otherwise `**/**/**` + :rtype: str + """ + if "/" not in expr and "*" not in expr: + glob_expr = f"**/*{expr}*/**" + logging.debug("expanding %s to %s", expr, glob_expr) + return glob_expr + return expr + + @staticmethod + def get_arg_parser() -> argparse.ArgumentParser: + """ + Creates a the argument parser for parsing command line arguments. + + :returns: The ArgumentParser with all options the script supports + :rtype: argparse.ArgumentParser + """ + + parser = argparse.ArgumentParser( + description="Create Immich Albums from an external library path based on the top level folders", + formatter_class=argparse.ArgumentDefaultsHelpFormatter, + ) + parser.add_argument( + "root_path", + action="append", + help="The external library's root path in Immich", + ) + parser.add_argument( + "api_url", + help="The root API URL of immich, e.g. https://immich.mydomain.com/api/", + ) + parser.add_argument( + "api_key", + action="append", + help="The Immich API Key to use. Set --api-key-type to 'file' if a file path is provided.", + ) + parser.add_argument( + "--api-key", + action="append", + help="Additional API Keys to run the script for; May be specified multiple times for running the script for multiple users.", + ) + parser.add_argument( + "-t", + "--api-key-type", + default=Configuration.CONFIG_DEFAULTS["api_key_type"], + choices=["literal", "file"], + help="The type of the Immich API Key", + ) + parser.add_argument( + "-r", + "--root-path", + action="append", + help="Additional external library root path in Immich; May be specified multiple times for multiple import paths or external libraries.", + ) + parser.add_argument( + "-u", + "--unattended", + action="store_true", + help="Do not ask for user confirmation after identifying albums. Set this flag to run script as a cronjob.", + ) + parser.add_argument( + "-a", + "--album-levels", + default=Configuration.CONFIG_DEFAULTS["album_levels"], + type=str, + help="""Number of sub-folders or range of sub-folder levels below the root path used for album name creation. + Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be 0. + If a range should be set, the start level and end level must be separated by a comma like ','. + If negative levels are used in a range, must be less than or equal to .""", + ) + parser.add_argument( + "-s", + "--album-separator", + default=Configuration.CONFIG_DEFAULTS["album_separator"], + type=str, + help="Separator string to use for compound album names created from nested folders. Only effective if -a is set to a value > 1", + ) + parser.add_argument( + "-R", + "--album-name-post-regex", + nargs="+", + action="append", + metavar=("PATTERN", "REPL"), + help='Regex pattern and optional replacement (use "" for empty replacement). Can be specified multiple times.', + ) + parser.add_argument( + "-c", + "--chunk-size", + default=Configuration.CONFIG_DEFAULTS["chunk_size"], + type=int, + help="Maximum number of assets to add to an album with a single API call", + ) + parser.add_argument( + "-C", + "--fetch-chunk-size", + default=Configuration.CONFIG_DEFAULTS["fetch_chunk_size"], + type=int, + help="Maximum number of assets to fetch with a single API call", + ) + parser.add_argument( + "-l", + "--log-level", + default=Configuration.CONFIG_DEFAULTS["log_level"], + choices=["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"], + help="Log level to use. ATTENTION: Log level DEBUG logs API key in clear text!", + ) + parser.add_argument( + "-k", + "--insecure", + action="store_true", + help="Pass to ignore SSL verification", + ) + parser.add_argument( + "-i", + "--ignore", + action="append", + help="""Use either literals or glob-like patterns to ignore assets for album name creation. + This filter is evaluated after any values passed with --path-filter. May be specified multiple times.""", + ) + parser.add_argument( + "--ignore-regex", + action="append", + help="""As regular expressions to ignore assets from album name creation. If an asset's path after the root path is matching the regular expression, it is ignored. + This filter is evaluated after any values passed with --path-filter or --path-filter-regex. May be specified multiple times.""", + ) + parser.add_argument( + "-m", + "--mode", + default=Configuration.CONFIG_DEFAULTS["mode"], + choices=[ + Configuration.SCRIPT_MODE_CREATE, + Configuration.SCRIPT_MODE_CLEANUP, + Configuration.SCRIPT_MODE_DELETE_ALL, + ], + help="""Mode for the script to run with. + CREATE = Create albums based on folder names and provided arguments; + CLEANUP = Create album names based on current images and script arguments, but delete albums if they exist; + DELETE_ALL = Delete all albums. + If the mode is anything but CREATE, --unattended does not have any effect. + Only performs deletion if -d/--delete-confirm option is set, otherwise only performs a dry-run.""", + ) + parser.add_argument( + "-d", + "--delete-confirm", + action="store_true", + help="""Confirm deletion of albums when running in mode """ + + Configuration.SCRIPT_MODE_CLEANUP + + """ or """ + + Configuration.SCRIPT_MODE_DELETE_ALL + + """. + If this flag is not set, these modes will perform a dry run only. Has no effect in mode """ + + Configuration.SCRIPT_MODE_CREATE, + ) + parser.add_argument( + "-x", + "--share-with", + action="append", + help="""A user name (or email address of an existing user) to share newly created albums with. + Sharing only happens if the album was actually created, not if new assets were added to an existing album. + If the the share role should be specified by user, the format = must be used, where must be one of 'viewer' or 'editor'. + May be specified multiple times to share albums with more than one user.""", + ) + parser.add_argument( + "-o", + "--share-role", + default=Configuration.CONFIG_DEFAULTS["share_role"], + choices=ApiClient.SHARE_ROLES, + help="""The default share role for users newly created albums are shared with. + Only effective if --share-with is specified at least once and the share role is not specified within --share-with.""", + ) + parser.add_argument( + "-S", + "--sync-mode", + default=Configuration.CONFIG_DEFAULTS["sync_mode"], + type=int, + choices=[0, 1, 2], + help="""Synchronization mode to use. Synchronization mode helps synchronizing changes in external libraries structures to Immich after albums + have already been created. Possible Modes: 0 = do nothing; 1 = Delete any empty albums; 2 = Delete offline assets AND any empty albums""", + ) + parser.add_argument( + "-O", + "--album-order", + default=Configuration.CONFIG_DEFAULTS["album_order"], + type=str, + choices=[False, "asc", "desc"], + help="Set sorting order for newly created albums to newest or oldest file first, Immich defaults to newest file first", + ) + parser.add_argument( + "-A", + "--find-assets-in-albums", + action="store_true", + help="""By default, the script only finds assets that are not assigned to any album yet. + Set this option to make the script discover assets that are already part of an album and handle them as usual. + If --find-archived-assets is set as well, both options apply.""", + ) + parser.add_argument( + "-f", + "--path-filter", + action="append", + help="""Use either literals or glob-like patterns to filter assets before album name creation. + This filter is evaluated before any values passed with --ignore. May be specified multiple times.""", + ) + parser.add_argument( + "--path-filter-regex", + action="append", + help="""Use regular expressions to for filter assets before album name creation. Only assets for which the path after the root path matches the regular expression + are considered. + This filter is evaluated before any values passed with --ignore or --ignore-regex. May be specified multiple times.""", + ) + parser.add_argument( + "--set-album-thumbnail", + choices=Configuration.ALBUM_THUMBNAIL_SETTINGS_GLOBAL, + help="""Set first/last/random image as thumbnail for newly created albums or albums assets have been added to. + If set to """ + + Configuration.ALBUM_THUMBNAIL_RANDOM_FILTERED + + """, thumbnails are shuffled for all albums whose assets would not be + filtered out or ignored by the ignore or path-filter options, even if no assets were added during the run. + If set to """ + + Configuration.ALBUM_THUMBNAIL_RANDOM_ALL + + """, the thumbnails for ALL albums will be shuffled on every run.""", + ) + parser.add_argument( + "--visibility", + choices=["archive", "locked", "timeline"], + help="""Set this option to automatically set the visibility of all assets that are discovered by the script and assigned to albums. + If --update-album-props-mode is set as well, visibility will be set for all assets in the discovered albums. + Exception for value 'locked': Assets will not be added to any albums, but to the 'locked' folder only. + Also applies if -m/--mode is set to CLEAN_UP or DELETE_ALL; then it affects all assets in the deleted albums.""", + ) + parser.add_argument( + "--find-archived-assets", + action="store_true", + help="""By default, the script only finds assets with visibility set to 'timeline' (which is the default). + Set this option to make the script discover assets with visibility 'archive' as well. + If -A/--find-assets-in-albums is set as well, both options apply.""", + ) + parser.add_argument( + "--read-album-properties", + action="store_true", + help="""If set, the script tries to access all passed root paths and recursively search for .albumprops files in all contained folders. + These properties will be used to set custom options on an per-album level. Check the readme for a complete documentation.""", + ) + parser.add_argument( + "--api-timeout", + default=Configuration.CONFIG_DEFAULTS["api_timeout"], + type=int, + help="Timeout when requesting Immich API in seconds", + ) + parser.add_argument( + "--comments-and-likes-enabled", + action="store_true", + help="Pass this argument to enable comment and like functionality in all albums this script adds assets to. Cannot be used together with --comments-and-likes-disabled", + ) + parser.add_argument( + "--comments-and-likes-disabled", + action="store_true", + help="Pass this argument to disable comment and like functionality in all albums this script adds assets to. Cannot be used together with --comments-and-likes-enabled", + ) + parser.add_argument( + "--update-album-props-mode", + type=int, + choices=[0, 1, 2], + default=Configuration.CONFIG_DEFAULTS["update_album_props_mode"], + help="""Change how album properties are updated whenever new assets are added to an album. Album properties can either come from script arguments or the .albumprops file. + Possible values: + 0 = Do not change album properties. + 1 = Only override album properties but do not change the share status. + 2 = Override album properties and share status, this will remove all users from the album which are not in the SHARE_WITH list.""", + ) + parser.add_argument( + "--max-retry-count", + type=int, + default=Configuration.CONFIG_DEFAULTS["max_retry_count"], + help="Number of times to retry an Immich API call if it timed out before failing.", + ) + parser.add_argument( + "--threads", + type=int, + default=Configuration.CONFIG_DEFAULTS["threads"], + choices=range(1, ApiClient.THREADS_MAX + 1), + help="DEPRECATED! Number of threads to fetch assets with in parallel.", + ) + return parser + + @staticmethod + def init_global_config() -> None: + """ + Initializes global configuration options from global config file () + + :returns: All configurations the script should run with + :rtype: None + """ + parser = Configuration.get_arg_parser() + args = vars(parser.parse_args()) + Configuration.log_level = Utils.get_value_or_config_default( + "log_level", args, Configuration.CONFIG_DEFAULTS["log_level"] + ) + + @classmethod + def get_configurations(cls) -> list[Configuration]: + """ + Creates and returns a list of configuration objects from the script's arguments. + + :returns: All configurations the script should run with + :rtype: list[Configuration] + """ + parser = Configuration.get_arg_parser() + args = vars(parser.parse_args()) + created_configs: list[Configuration] = [] + api_key_type = Utils.get_value_or_config_default( + "api_key_type", args, Configuration.CONFIG_DEFAULTS["api_key_type"] + ) + # Create a configuration for each passed API key + for api_key_arg in args["api_key"]: + api_keys = Configuration.__determine_api_key(api_key_arg, api_key_type) + config_args = args + for api_key in api_keys: + # replace the API key array with the current api key for that configuration args + config_args["api_key"] = api_key + created_configs.append(cls(config_args)) + # Return a list with a single configuration + return created_configs + + @staticmethod + def __determine_api_key(api_key_source: str, key_type: str) -> list[str]: + """ + For key_type `literal`, api_key_source is returned in a list with a single record. + For key_type `file`, api_key_source is a path to a file containing the API key, + each line in that file is interpreted as an API key. and a list with each line as a record + is returned. + + :param api_key_source: An API key or path to a file containing an API key + :param key_type: Must be either 'literal' or 'file' + + :returns: A list of API keys to use + :rtype: list[str] + """ + assert key_type is not None, "API key type must be set!" + assert key_type in ["literal", "file"], ( + "API key type must be either 'literal' or 'file'!" + ) + if key_type == "file": + return Utils.read_file(api_key_source).splitlines() + + # case: 'literal' + return [api_key_source] + + @staticmethod + def log_debug_global(): + """ + Logs global configuration options on `DEBUG` log level + """ + logging.debug("%s = '%s'", "log_level", Configuration.log_level) + + def log_debug(self): + """ + Logs all its own properties on `DEBUG` log level + """ + props = dict(vars(self)) + for prop in list(props.keys()): + logging.debug("%s = '%s'", prop, props[prop]) + + +class FolderAlbumCreator: + """The Folder Album Creator class creating albums from folder structures based on the passed configuration""" + + # File name to use for album properties files + ALBUMPROPS_FILE_NAME = ".albumprops" + + def __init__(self, configuration: Configuration): + self.config = configuration + self.api_client = ApiClient( + self.config.root_url, self.config.api_key, ApiClientConfig(configuration) + ) + self._is_docker = bool(os.environ.get(ENV_IS_DOCKER, False)) + + @staticmethod + def find_albumprops_files(paths: list[str]) -> list[str]: + """ + Recursively finds all album properties files in all passed paths. + + :param paths: A list of paths to search for album properties files + + :returns: A list of paths with all album properties files + :rtype: list[str] + """ + albumprops_files = [] + for path in paths: + if not os.path.isdir(path): + logging.warning( + "Album Properties Discovery: Path %s does not exist!", path + ) + continue + for path_tuple in os.walk(path): + root = path_tuple[0] + filenames = path_tuple[2] + for filename in fnmatch.filter( + filenames, FolderAlbumCreator.ALBUMPROPS_FILE_NAME + ): + albumprops_files.append(os.path.join(root, filename)) + return albumprops_files + + @staticmethod + def __identify_root_path(path: str, root_path_list: list[str]) -> str | None: + """ + Identifies which root path is the parent of the provided path. + + :param path: The path to find the root path for + :type path: str + :param root_path_list: The list of root paths to get the one path is a child of from + :type root_path_list: list[str] + :return: The root path from root_path_list that is the parent of path or None if the path is not in any root path + :rtype: str + """ + for root_path in root_path_list: + if root_path in path: + return root_path + return None + + @staticmethod + def check_for_and_log_incompatible_properties( + model1: AlbumModel, + model2: AlbumModel, + album_name_to_album_properties_file_path: dict[str, Any], + ) -> bool: + """ + Checks if model1 and model2 have incompatible properties (same properties set to different values). If so, + logs the the incompatible properties and returns True. + + :param model1: The first album model to check for incompatibility with the second model + :param model2: The second album model to check for incompatibility with the first model + :param album_name_to_album_properties_file_path: A dictionary where the key is an album name and the value is the path to the album properties file the + album was generated from. This method expects one entry in this dictionary for every AlbumModel in album_props_templates + + :returns: False if model1 and model2 are compatible, otherwise True + :rtype: bool + """ + assert model1.name is not None, "First album model does not have a name!" + assert model2.name is not None, "Second album model does not have a name!" + + incompatible_props = model1.find_incompatible_properties(model2) + if len(incompatible_props) > 0: + logging.fatal( + "Album properties files %s and %s define the same override_name but have incompatible properties:", + album_name_to_album_properties_file_path[model1.name], + album_name_to_album_properties_file_path[model2.name], + ) + for incompatible_prop in incompatible_props: + logging.fatal(incompatible_prop) + return True + return False + + @staticmethod + def build_inheritance_chain_for_album_path( + album_path: str, root_path: str, albumprops_cache_param: dict[str, AlbumModel] + ) -> list[AlbumModel]: + """ + Builds the inheritance chain for a given album path by walking up the directory tree + and finding all .albumprops files with inherit=True. + + :param album_path: The full path to the album directory + :param root_path: The root path to stop the inheritance chain at + :param albumprops_cache: Dictionary mapping .albumprops file paths to AlbumModel objects + + :returns: List of AlbumModel objects in inheritance order (root to current) + :rtype: list[AlbumModel] + """ + inheritance_chain = [] + current_path = os.path.normpath(album_path) + root_path = os.path.normpath(root_path) + + # Walk up the directory tree until we reach the root path + while len(current_path) >= len(root_path): + albumprops_path = os.path.join( + current_path, FolderAlbumCreator.ALBUMPROPS_FILE_NAME + ) + + if albumprops_path in albumprops_cache_param: + album_model_local = albumprops_cache_param[albumprops_path] + inheritance_chain.insert( + 0, album_model_local + ) # Insert at beginning for correct order + + # If this level doesn't have inherit=True, stop the inheritance chain + if not album_model_local.inherit: + break + + # If we've reached the root path, stop + if current_path == root_path: + break + + # Move up one directory level + parent_path = os.path.dirname(current_path) + if parent_path == current_path: # Reached filesystem root + break + current_path = parent_path + + return inheritance_chain + + # pylint: disable=R0912 + @staticmethod + def apply_inheritance_to_album_model( + album_model_param: AlbumModel | None, inheritance_chain: list[AlbumModel] + ) -> AlbumModel: + """ + Applies inheritance from the inheritance chain to the given album model. + + :param album_model: The target album model to apply inheritance to (can be None if no local .albumprops) + :param inheritance_chain: List of AlbumModel objects in inheritance order (root to current, excluding current) + + :returns: The album model with inherited properties applied + :rtype: AlbumModel + """ + if not inheritance_chain: + assert album_model_param is not None, ( + "Album model must be set if there is not .albumprops file!" + ) + return album_model_param + + # Create a new model to hold inherited properties + if album_model_param is not None: + inherited_model: AlbumModel = AlbumModel(album_model_param.name) + # Copy all properties from the original model first + for prop_name in ( + AlbumModel.ALBUM_PROPERTIES_VARIABLES + + AlbumModel.ALBUM_INHERITANCE_VARIABLES + ): + setattr( + inherited_model, prop_name, getattr(album_model_param, prop_name) + ) + inherited_model.id = album_model_param.id + inherited_model.assets = album_model_param.assets + else: + inherited_model = AlbumModel(None) + + inherited_share_with: list[AlbumModel.ShareWith] = [] + + # Apply inheritance from root to current (inheritance_chain is already in correct order) + for parent_model in inheritance_chain: + if not parent_model.inherit_properties: + # If no inherit_properties specified, inherit all properties + inherit_props = AlbumModel.ALBUM_PROPERTIES_VARIABLES + else: + inherit_props = parent_model.inherit_properties + + # Apply inherited properties + parent_attribs = vars(parent_model) + inherited_attribs = vars(inherited_model) + + for prop_name in inherit_props: + if ( + prop_name in AlbumModel.ALBUM_PROPERTIES_VARIABLES + and parent_attribs[prop_name] is not None + ): + if prop_name == "share_with": + # Special handling for share_with - accumulate users + if parent_attribs[prop_name]: + inherited_share_with.extend(parent_attribs[prop_name]) + else: + # For other properties, only set if not already set (parent properties have lower precedence) + if inherited_attribs[prop_name] is None: + inherited_attribs[prop_name] = parent_attribs[prop_name] + + # Apply accumulated inherited share_with if the current model doesn't have share_with + if inherited_share_with and not inherited_model.share_with: + inherited_model.share_with = inherited_share_with + elif inherited_share_with and inherited_model.share_with: + # Merge inherited and current share_with using the special merge logic + temp_model = AlbumModel(None) + temp_model.share_with = inherited_share_with + inherited_model.share_with = inherited_model.merge_inherited_share_with( + temp_model.share_with + ) + + return inherited_model + + def build_albumprops_cache(self) -> dict[str, AlbumModel]: + """ + Builds a cache of all .albumprops files found in root paths. + + :returns: Dictionary mapping .albumprops file paths to AlbumModel objects + :rtype: dict[str, AlbumModel] + """ + albumprops_files = FolderAlbumCreator.find_albumprops_files( + self.config.root_paths + ) + albumprops_path_to_model_dict: dict[str, AlbumModel] = {} + + # Parse all .albumprops files + for albumprops_path in albumprops_files: + if self.is_path_ignored(albumprops_path): + continue + + try: + album_model_local = AlbumModel.parse_album_properties_file( + albumprops_path + ) + if album_model_local: + albumprops_path_to_model_dict[albumprops_path] = album_model_local + logging.debug( + "Loaded .albumprops from %s: %s", + albumprops_path, + album_model_local, + ) + except yaml.YAMLError as ex: + logging.error( + "Could not parse album properties file %s: %s", albumprops_path, ex + ) + + return albumprops_path_to_model_dict + + @staticmethod + def get_album_properties_with_inheritance( + album_name: str, + album_path: str, + root_path: str, + albumprops_cache_param: dict[str, AlbumModel], + ) -> AlbumModel | None: + """ + Gets the album properties for an album, applying inheritance from parent folders. + + :param album_name: The name of the album + :param album_path: The full path to the album directory + :param root_path: The root path for this album + :param albumprops_cache: Dictionary mapping .albumprops file paths to AlbumModel objects + + :returns: The album model with inheritance applied, or None if no properties found + :rtype: AlbumModel + """ + # Check if the album directory has its own .albumprops file + albumprops_path = os.path.join( + album_path, FolderAlbumCreator.ALBUMPROPS_FILE_NAME + ) + local_album_model: Optional[AlbumModel] = None + + logging.debug( + "Checking for album properties: album_path=%s, albumprops_path=%s", + album_path, + albumprops_path, + ) + + if albumprops_path in albumprops_cache_param: + local_album_model = albumprops_cache_param[albumprops_path] + local_album_model.name = album_name + logging.debug("Found local .albumprops for album '%s'", album_name) + + # Build inheritance chain (excluding the current level) + inheritance_chain = FolderAlbumCreator.build_inheritance_chain_for_album_path( + album_path, root_path, albumprops_cache_param + ) + + # Remove the current level from inheritance chain if it exists + if inheritance_chain and albumprops_path in albumprops_cache_param: + current_model = albumprops_cache_param[albumprops_path] + if inheritance_chain and inheritance_chain[-1] is current_model: + inheritance_chain = inheritance_chain[:-1] + + logging.debug( + "Inheritance chain for album '%s' has %d levels", + album_name, + len(inheritance_chain), + ) + + # Apply inheritance + if inheritance_chain or local_album_model: + final_model = FolderAlbumCreator.apply_inheritance_to_album_model( + local_album_model, inheritance_chain + ) + if final_model and final_model.name is None: + final_model.name = album_name + + # Log final properties for this album + if final_model and (inheritance_chain or local_album_model): + logging.info( + "Final album properties for '%s' (with inheritance): %s", + album_name, + final_model, + ) + + return final_model + + return None + + @staticmethod + def __parse_separated_string( + separated_string: str, separator: str + ) -> tuple[str, str | None]: + """ + Parse a key, value pair, separated by the provided separator. + + That's the reverse of ShellArgs. + On the command line (argparse) a declaration will typically look like: + foo=hello + or + foo="hello world" + + :param separated_string: The string to parse + :param separator: The separator to parse separated_string at + :return: A tuple with the first value being the string on the left side of the separator + and the second value the string on the right side of the separator + """ + items = separated_string.split(separator) + key = items[0].strip() # we remove blanks around keys, as is logical + value = None + if len(items) > 1: + # rejoin the rest: + value = separator.join(items[1:]) + return key, value + + # pylint: disable=R0912 + def create_album_name( + self, + asset_path_chunks: list[str], + album_separator: str, + album_name_postprocess_regex: list[str], + ) -> str | None: + """ + Create album names from provided path_chunks string array. + + The method uses global variables album_levels_range_arr or album_levels to + generate album names either by level range or absolute album levels. If multiple + album path chunks are used for album names they are separated by album_separator. + :param asset_path_chunks: A list of strings representing the folder names parsed from an asset's path + :param album_seprator: The separator used for album names spanning multiple folder levels + :param album_name_postprocess_regex: List of pairs of regex and replace, optional + + :returns: The created album name or None if the album levels range does not apply to the path chunks. + :rtype: str + """ + + album_name_chunks = () + logging.debug("path chunks = %s", list(asset_path_chunks)) + # Check which path to take: album_levels_range or album_levels + if len(self.config.album_levels_range_arr) == 2: + if self.config.album_levels_range_arr[0] < 0: + album_levels_start_level_capped = min( + len(asset_path_chunks), abs(self.config.album_levels_range_arr[0]) + ) + album_levels_end_level_capped = ( + self.config.album_levels_range_arr[1] + 1 + ) + album_levels_start_level_capped *= -1 + else: + # If our start range is already out of range of our path chunks, do not create an album from that. + if len(asset_path_chunks) - 1 < self.config.album_levels_range_arr[0]: + logging.debug( + "Skipping asset chunks since out of range: %s", + asset_path_chunks, + ) + return None + album_levels_start_level_capped = min( + len(asset_path_chunks) - 1, self.config.album_levels_range_arr[0] + ) + # Add 1 to album_levels_end_level_capped to include the end index, which is what the user intended to. It's not a problem + # if the end index is out of bounds. + album_levels_end_level_capped = ( + min( + len(asset_path_chunks) - 1, + self.config.album_levels_range_arr[1], + ) + + 1 + ) + logging.debug( + "album_levels_start_level_capped = %d", album_levels_start_level_capped + ) + logging.debug( + "album_levels_end_level_capped = %d", album_levels_end_level_capped + ) + # album start level is not equal to album end level, so we want a range of levels + if album_levels_start_level_capped is not album_levels_end_level_capped: + # if the end index is out of bounds. + if album_levels_end_level_capped < 0 and abs( + album_levels_end_level_capped + ) >= len(asset_path_chunks): + album_name_chunks = asset_path_chunks[ + album_levels_start_level_capped: + ] + else: + album_name_chunks = asset_path_chunks[ + album_levels_start_level_capped:album_levels_end_level_capped + ] + # album start and end levels are equal, we want exactly that level + else: + # create on-the-fly array with a single element taken from + album_name_chunks = [asset_path_chunks[album_levels_start_level_capped]] + else: + album_levels_int = int(self.config.album_levels) + # either use as many path chunks as we have, + # or the specified album levels + album_name_chunk_size = min(len(asset_path_chunks), abs(album_levels_int)) + if album_levels_int < 0: + album_name_chunk_size *= -1 + + # Copy album name chunks from the path to use as album name + album_name_chunks = asset_path_chunks[:album_name_chunk_size] + if album_name_chunk_size < 0: + album_name_chunks = asset_path_chunks[album_name_chunk_size:] + logging.debug("album_name_chunks = %s", album_name_chunks) + + # final album name before regex + album_name = album_separator.join(album_name_chunks) + logging.debug("Album Name %s", album_name) + + # apply regex if any + if album_name_postprocess_regex: + for pattern, *repl in album_name_postprocess_regex: + # If no replacement string provided, default to empty string + replace = repl[0] if repl else "" + album_name = regex.sub(pattern, replace, album_name) + logging.debug( + "Album Post Regex s/%s/%s/g --> %s", pattern, replace, album_name + ) + + return album_name.strip() + + def choose_thumbnail( + self, thumbnail_setting: str, thumbnail_asset_list: list[AssetResponseDto] + ) -> Optional[AssetResponseDto]: + """ + Tries to find an asset to use as thumbnail depending on thumbnail_setting. + + :param thumbnail_setting: Either a fully qualified asset path or one of `first`, `last`, `random`, `random-filtered` + :param asset_list: A list of assets to choose a thumbnail from, based on thumbnail_setting + + :returns: An Immich asset dict or None if no thumbnail was found based on thumbnail_setting + :rtype: Optional[AssetResponseDto] + """ + # Case: fully qualified path + if thumbnail_setting not in Configuration.ALBUM_THUMBNAIL_SETTINGS_GLOBAL: + for asset in thumbnail_asset_list: + if asset.original_path == thumbnail_setting: + return asset + # at this point we could not find the thumbnail asset by path + return None + + # Case: Anything but fully qualified path + # Apply filtering to assets + thumbnail_assets = thumbnail_asset_list + if thumbnail_setting == Configuration.ALBUM_THUMBNAIL_RANDOM_FILTERED: + thumbnail_assets[:] = [ + asset + for asset in thumbnail_assets + if not self.is_path_ignored(asset.original_path) + ] + + if len(thumbnail_assets) > 0: + # Sort assets by creation date + thumbnail_assets.sort(key=lambda x: x.file_created_at) + if thumbnail_setting not in Configuration.ALBUM_THUMBNAIL_STATIC_INDICES: + idx = random.randint(0, len(thumbnail_assets) - 1) + else: + idx = Configuration.ALBUM_THUMBNAIL_STATIC_INDICES[thumbnail_setting] + return thumbnail_assets[idx] + + # Case: Invalid thumbnail_setting + return None + + def is_path_ignored(self, path_to_check: str) -> bool: + """ + Determines if the asset should be ignored for the purpose of this script + based in its originalPath and global ignore and path_filter options. + + :param asset_to_check: The asset to check if it must be ignored or not. Must have the key 'originalPath'. + + :returns: True if the asset must be ignored, otherwise False + :rtype: bool + """ + is_path_ignored_result = False + asset_root_path = None + for root_path_to_check in self.config.root_paths: + if root_path_to_check in path_to_check: + asset_root_path = root_path_to_check + break + logging.debug( + "Identified root_path for asset %s = %s", path_to_check, asset_root_path + ) + if asset_root_path: + # First apply filter, if any + if len(self.config.path_filter_regex) > 0: + any_match = False + for path_filter_regex_entry in self.config.path_filter_regex: + if regex.fullmatch( + path_filter_regex_entry, + path_to_check.replace(asset_root_path, ""), + ): + any_match = True + if not any_match: + logging.debug( + "Ignoring path %s due to path_filter setting!", path_to_check + ) + is_path_ignored_result = True + # If the asset "survived" the path filter, check if it is in the ignore_albums argument + if not is_path_ignored_result and len(self.config.ignore_albums_regex) > 0: + for ignore_albums_regex_entry in self.config.ignore_albums_regex: + if regex.fullmatch( + ignore_albums_regex_entry, + path_to_check.replace(asset_root_path, ""), + ): + is_path_ignored_result = True + logging.debug( + "Ignoring path %s due to ignore_albums setting!", + path_to_check, + ) + break + + return is_path_ignored_result + + @staticmethod + def get_album_id_by_name( + albums_list: list[AlbumResponseDto], album_name: str + ) -> UUID | None: + """ + Finds the album with the provided name in the list of albums and returns its id. + + :param albums_list: List of albums to find a particular album in + :param album_name: Name of album to find the ID for + + :returns: The ID of the requested album or None if not found + :rtype: str + """ + normalized_album_name = unicodedata.normalize("NFC", album_name) + for _ in albums_list: + if unicodedata.normalize("NFC", _.album_name) == normalized_album_name: + return _.id + return None + + def check_for_and_remove_live_photo_video_components( + self, + asset_list: list[AssetResponseDto], + is_not_in_album: bool, + find_archived: bool, + ) -> list[AssetResponseDto]: + """ + Checks asset_list for any asset with file ending .mov. This is indicative of a possible video component + of an Apple Live Photo. There is display bug in the Immich iOS app that prevents live photos from being + show correctly if the static AND video component are added to the album. We only want to add the static component to an album, + so we need to filter out all video components belonging to a live photo. The static component has a property livePhotoVideoId set + with the asset ID of the video component. + + :param is_not_in_album: Flag indicating whether to fetch only assets that are not part + of an album or not. If this and find_archived are True, we can assume asset_list is complete + and should contain any static components. + :param find_archived: Flag indicating whether to only fetch assets that are archived. If this and is_not_in_album are + True, we can assume asset_list is complete and should contain any static components. + + :returns: An asset list without live photo video components + :rtype: list[AssetResponseDto] + """ + logging.info("Checking for live photo video components") + # Filter for all quicktime assets + asset_list_mov = [ + asset for asset in asset_list if asset.original_mime_type == "video" + ] + + if len(asset_list_mov) == 0: + logging.debug("No live photo video components found") + return asset_list + + # If either is not True, we need to fetch all assets + if is_not_in_album or not find_archived: + logging.debug("Fetching all assets for live photo video component check") + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + try: + full_asset_list = self.api_client.fetch_assets_with_options( + MetadataSearchDto(isNotInAlbum=False) + ) + full_asset_list += self.api_client.fetch_assets_with_options( + MetadataSearchDto( + isNotInAlbum=False, visibility=AssetVisibility.ARCHIVE + ) + ) + except BadRequestException: + # Use an empty filter to fetch all assets + full_asset_list = self.api_client.fetch_assets_with_filter( + SearchFilter() + ) + else: + full_asset_list = asset_list + + # Find all assets with a live ID set + asset_list_with_live_id = [ + asset for asset in full_asset_list if asset.live_photo_video_id is not None + ] + + # Find all video components + asset_list_video_components_ids = [] + for asset_static_component in asset_list_with_live_id: + for asset_mov in asset_list_mov: + if asset_mov.id == asset_static_component.live_photo_video_id: + asset_list_video_components_ids.append(asset_mov.id) + logging.debug( + "File %s is a video component of a live photo, removing from list", + asset_mov.original_path, + ) + + logging.info( + "Removing %s live photo video components from asset list", + len(asset_list_video_components_ids), + ) + # Remove all video components from the asset list + asset_list_without_video_components = [ + asset + for asset in asset_list + if asset.id not in asset_list_video_components_ids + ] + return asset_list_without_video_components + + # pylint: disable=R0914 + def set_album_properties_in_model(self, album_model_to_update: AlbumModel) -> None: + """ + Sets the album_model's properties based on script options set. + + :param album_model: The album model to set the properties for + """ + # Set share_with + if self.config.share_with: + for album_share_user in self.config.share_with: + # Resolve share user-specific share role syntax = + share_user_name, share_user_role_local = ( + FolderAlbumCreator.__parse_separated_string(album_share_user, "=") + ) + # Fallback to default + if share_user_role_local is None: + share_user_role_local = self.config.share_role + + album_model_to_update.share_with.append( + AlbumModel.ShareWith( + user=share_user_name, role=AlbumUserRole(share_user_role_local) + ) + ) + + # Thumbnail Setting + if self.config.set_album_thumbnail: + album_model_to_update.thumbnail_setting = self.config.set_album_thumbnail + + # Archive setting + if self.config.visibility is not None: + album_model_to_update.visibility = self.config.visibility + + # Sort Order + if self.config.album_order: + album_model_to_update.sort_order = self.config.album_order + + # Comments and Likes + if self.config.comments_and_likes_enabled: + album_model_to_update.comments_and_likes_enabled = True + elif self.config.comments_and_likes_disabled: + album_model_to_update.comments_and_likes_enabled = False + + # pylint: disable=R0914,R1702,R0915 + def build_album_list( + self, + asset_list: list[AssetResponseDto], + root_path_list: list[str], + albumprops_cache_param: Optional[dict[str, AlbumModel]] = None, + ) -> dict[str, AlbumModel]: + """ + Builds a list of album models, enriched with assets assigned to each album. + Returns a dict where the key is the album name and the value is the model. + Attention! + + :param asset_list: List of assets dictionaries fetched from Immich API + :param root_path_list: List of root paths to use for album creation + :param albumprops_cache_param: Dictionary mapping .albumprops file paths to AlbumModel objects (for inheritance) + + :returns: A dict with album names as keys and an AlbumModel as value + :rtype: dict[str, AlbumModel] + """ + album_models: dict[str, AlbumModel] = {} + logged_albums = set() # Track which albums we've already logged properties for + + for asset_to_add in asset_list: + asset_path = asset_to_add.original_path + # This method will log the ignore reason, so no need to log anything again. + if self.is_path_ignored(asset_path): + continue + + # Identify the root path + asset_root_path = FolderAlbumCreator.__identify_root_path( + asset_path, root_path_list + ) + if not asset_root_path: + continue + + # Chunks of the asset's path below root_path + path_chunks = asset_path.replace(asset_root_path, "").split("/") + # A single chunk means it's just the image file in no sub folder, ignore + if len(path_chunks) == 1: + continue + + # remove last item from path chunks, which is the file name + del path_chunks[-1] + album_name = self.create_album_name( + path_chunks, + self.config.album_level_separator, + self.config.album_name_post_regex, + ) + # Silently skip album, create_album_name already did debug logging + if album_name is None: + continue + + if len(album_name) > 0: + # Check if we already created this album model + final_album_name = album_name + + # Check for album properties with inheritance if albumprops_cache is provided + inherited_album_model = None + if albumprops_cache_param: + # Reconstruct the full album directory path + album_dir_path = os.path.join(asset_root_path, *path_chunks) + inherited_album_model = ( + FolderAlbumCreator.get_album_properties_with_inheritance( + album_name, + album_dir_path, + asset_root_path, + albumprops_cache_param, + ) + ) + if inherited_album_model and inherited_album_model.override_name: + final_album_name = inherited_album_model.override_name + + # Check if we already have this album model + if final_album_name in album_models: + new_album_model = album_models[final_album_name] + + # Merge properties when adding assets to an existing album with same final name + if inherited_album_model: + # For share_with, we need to accumulate all users from all directories + # using the most restrictive role policy + if inherited_album_model.share_with: + # Create a temporary model to merge the new share_with settings + # with the already accumulated settings in the existing album + temp_merge_model = AlbumModel(new_album_model.name) + temp_merge_model.share_with = ( + new_album_model.share_with + if new_album_model.share_with + else [] + ) + + # Use the merge logic to properly handle user conflicts, roles, and 'none' users + new_album_model.share_with = ( + temp_merge_model.merge_inherited_share_with( + inherited_album_model.share_with + ) + ) + + # For other properties, only update if not already set (preserve first album's properties as base) + temp_model = AlbumModel(new_album_model.name) + # Copy only non-share_with properties to avoid overwriting our accumulated share_with + for prop_name in AlbumModel.ALBUM_PROPERTIES_VARIABLES: + if ( + prop_name != "share_with" + and getattr(inherited_album_model, prop_name) + is not None + ): + setattr( + temp_model, + prop_name, + getattr(inherited_album_model, prop_name), + ) + new_album_model.merge_from( + temp_model, AlbumModel.ALBUM_MERGE_MODE_EXCLUSIVE + ) + + else: + new_album_model = AlbumModel(album_name) + # Apply album properties from set options + self.set_album_properties_in_model(new_album_model) + + # Apply inherited properties if available + if inherited_album_model: + new_album_model.merge_from( + inherited_album_model, AlbumModel.ALBUM_MERGE_MODE_OVERRIDE + ) + + # Log final album properties (only once per album) + if final_album_name not in logged_albums: + logging.info( + "Final album properties for '%s' (with inheritance): %s", + final_album_name, + new_album_model, + ) + logged_albums.add(final_album_name) + else: + # Log final album properties for albums without .albumprops (only once per album) + if final_album_name not in logged_albums: + logging.info( + "Final album properties for '%s': %s", + final_album_name, + new_album_model, + ) + logged_albums.add(final_album_name) + + # Add asset to album model + new_album_model.assets.append(asset_to_add) + album_models[new_album_model.get_final_name()] = new_album_model + else: + logging.warning( + "Got empty album name for asset path %s, check your album_level settings!", + asset_path, + ) + return album_models + + # pylint: disable=R1705 + @staticmethod + def find_user_by_name_or_email( + name_or_email: str, user_list: list[UserResponseDto] + ) -> Optional[UserResponseDto]: + """ + Finds a user identified by name_or_email in the provided user_list. + + :param name_or_email: The user name or email address to find the user by + :param user_list: A list of user dictionaries with the following mandatory keys: `id`, `name`, `email` + + :returns: A user with matching name or email or None if no matching user was found + :rtype: UserResponseDto + """ + for user in user_list: + # Search by name or mail address + if name_or_email in (user.name, user.email): + return user + return None + + async def run(self) -> None: + """ + Performs the actual logic of the script, i.e. creating albums from external library folder structures and everything else. + """ + async with self.api_client: + # Special case: Run Mode DELETE_ALL albums + if self.config.mode == Configuration.SCRIPT_MODE_DELETE_ALL: + self.api_client.delete_all_albums( + self.config.visibility, self.config.delete_confirm + ) + return + + albumprops_cache: Optional[dict[str, AlbumModel]] = None + if self.config.read_album_properties: + logging.debug( + "Albumprops: Finding, parsing and loading %s files with inheritance support", + FolderAlbumCreator.ALBUMPROPS_FILE_NAME, + ) + albumprops_cache = self.build_albumprops_cache() + + logging.info("Requesting all assets") + # only request images that are not in any album if we are running in CREATE mode, + # otherwise we need all images, even if they are part of an album + if self.config.mode == Configuration.SCRIPT_MODE_CREATE: + assets = self.api_client.fetch_assets( + not self.config.find_assets_in_albums, + [AssetVisibility.ARCHIVE] + if self.config.find_archived_assets + else [], + ) + else: + assets = self.api_client.fetch_assets(False, [AssetVisibility.ARCHIVE]) + + # Remove live photo video components + assets = self.check_for_and_remove_live_photo_video_components( + assets, + not self.config.find_assets_in_albums, + self.config.find_archived_assets, + ) + logging.info("%d photos found", len(assets)) + logging.info("Sorting assets to corresponding albums using folder name") + albums_to_create = self.build_album_list( + assets, self.config.root_paths, albumprops_cache + ) + albums_to_create = dict( + sorted(albums_to_create.items(), key=lambda item: item[0]) + ) + + logging.info("%d albums identified", len(albums_to_create)) + logging.info("Album list: %s", list(albums_to_create.keys())) + + if ( + not self.config.unattended + and self.config.mode == Configuration.SCRIPT_MODE_CREATE + ): + if self._is_docker: + print( + "Check that this is the list of albums you want to create. Run the container with environment variable UNATTENDED set to 1 to actually create these albums." + ) + return + try: + input("Press enter to create these albums, Ctrl+C to abort") + except KeyboardInterrupt: + print("Aborting...") + return + + logging.info("Listing existing albums on immich") + + albums = self.api_client.fetch_albums() + logging.info("%d existing albums identified", len(albums)) + + album: AlbumModel + for album in albums_to_create.values(): + # fetch the id if same album name exist + album.id = FolderAlbumCreator.get_album_id_by_name( + albums, album.get_final_name() + ) + + # mode CLEANUP + if self.config.mode == Configuration.SCRIPT_MODE_CLEANUP: + # Filter list of albums to create for existing albums only + albums_to_cleanup: dict[UUID, AlbumModel] = {} + for album in albums_to_create.values(): + # Only cleanup existing albums (has id set) and no duplicates (due to override_name) + if album.id and album.id not in albums_to_cleanup: + albums_to_cleanup[album.id] = album + # pylint: disable=C0103 + number_of_deleted_albums = self.api_client.cleanup_albums( + list(albums_to_cleanup.values()), + self.config.visibility, + self.config.delete_confirm, + ) + logging.info( + "Deleted %d/%d albums", + number_of_deleted_albums, + len(albums_to_cleanup), + ) + return + + # Get all users in preparation for album sharing + users = self.api_client.fetch_users() + logging.debug("Found users: %s", users) + + # mode CREATE + logging.info("Create / Append to Albums") + created_albums: list[AlbumModel] = [] + # List for gathering all asset UUIDs for later archiving + asset_uuids_added: list[UUID] = [] + for album in albums_to_create.values(): + # Special case: Add assets to Locked folder + # Locked assets cannot be part of an album, so don't create albums in the first place + if album.visibility == AssetVisibility.LOCKED: + self.api_client.set_assets_visibility( + album.get_asset_uuids(), album.visibility + ) + logging.info( + "Added %d assets to locked folder", len(album.get_asset_uuids()) + ) + continue + + # Create album if inexistent: + if not album.id: + album.id = self.api_client.create_album(album.get_final_name()) + created_albums.append(album) + logging.info("Album %s added!", album.get_final_name()) + + logging.info("Adding assets to album %s", album.get_final_name()) + assets_added = self.api_client.add_assets_to_album( + album.id, album.get_asset_uuids() + ) + if len(assets_added) > 0: + asset_uuids_added += assets_added + logging.info( + "%d new assets added to %s", + len(assets_added), + album.get_final_name(), + ) + + # Fetch assets to be sure to have up-to-date asset list + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + try: + album_assets = self.api_client.fetch_assets_with_options( + MetadataSearchDto(album_ids=[album.id]) + ) + except BadRequestException: + # filter: { "filter": {"albumIds": { "all": ["9eab1ebe-c998-4bdc-a2cc-1722c719e292"]}}} + search_filter: SearchFilter = SearchFilter( + album_ids=IdsFilter(all=[album.id]) + ) + album_assets = self.api_client.fetch_assets_with_filter( + search_filter + ) + + # Set asset visibility (if assets were actually added and visibility is not set anyway when updating album properties) + if ( + album.visibility is not None + and len(assets_added) > 0 + and self.config.update_album_props_mode == 0 + ): + self.api_client.set_assets_visibility( + assets_added, album.visibility + ) + logging.info( + "Set visibility for %d assets to %s", + len(assets_added), + album.visibility.value, + ) + + # Update album thumbnail if assets have been added or update_album_props_mode is set + # Thumbnail setting 'random-all' is handled separately + if ( + (len(assets_added) > 0 or self.config.update_album_props_mode > 0) + and album.thumbnail_setting + and album.thumbnail_setting + != Configuration.ALBUM_THUMBNAIL_RANDOM_ALL + ): + thumbnail_asset = self.choose_thumbnail( + album.thumbnail_setting, album_assets + ) + # Set album thumbnail + if thumbnail_asset: + logging.info( + "Using asset %s as thumbnail for album %s", + thumbnail_asset.original_path, + album.get_final_name(), + ) + album.thumbnail_asset_uuid = thumbnail_asset.id + else: + logging.warning( + "Unable to determine thumbnail for setting '%s' in album %s", + album.thumbnail_setting, + album.get_final_name(), + ) + + # Update album properties depending on mode or if newly created + if self.config.update_album_props_mode > 0 or (album in created_albums): + # Set asset visibility for all assets in album + if album.visibility is not None and len(album_assets) > 0: + album_asset_uuids: list[str] = [ + asset.id for asset in album_assets + ] + self.api_client.set_assets_visibility( + album_asset_uuids, album.visibility + ) + logging.info( + "Set visibility for %d assets to %s", + len(album_asset_uuids), + album.visibility.value, + ) + # Update album properties + try: + self.api_client.update_album_properties(album) + except HTTPError as e: + logging.error( + "Error updating properties for album %s: %s", + album.get_final_name(), + e, + ) + + # Update album sharing if needed or newly created + if self.config.update_album_props_mode == 2 or ( + album in created_albums + ): + # Handle album sharing + self.api_client.update_album_shared_state(album, True, users) + + logging.info("%d albums created", len(created_albums)) + + # Perform album cover randomization + if ( + self.config.set_album_thumbnail + == Configuration.ALBUM_THUMBNAIL_RANDOM_ALL + ): + logging.info("Picking a new random thumbnail for all albums") + albums = self.api_client.fetch_albums() + for a in albums: + # Create album model for thumbnail randomization + album_model = AlbumModel(a.album_name) + album_model.id = a.id + # Future: Remove legacy calls when Immich removed the deprecated fields from /search/metadata + try: + album_model.assets = self.api_client.fetch_assets_with_options( + MetadataSearchDto(album_ids=[a.id]) + ) + except BadRequestException: + # filter: { "filter": {"albumIds": { "all": ["9eab1ebe-c998-4bdc-a2cc-1722c719e292"]}}} + search_filter: SearchFilter = SearchFilter( + album_ids=IdsFilter(all=[a.id]) + ) + album_assets = self.api_client.fetch_assets_with_filter( + search_filter + ) + + # Set thumbnail setting to 'random' in model + album_model.thumbnail_setting = "random" + thumbnail_asset = self.choose_thumbnail( + album_model.thumbnail_setting, album_model.assets + ) + if thumbnail_asset: + logging.info( + "Using asset %s as thumbnail for album %s", + thumbnail_asset.original_path, + album_model.get_final_name(), + ) + album_model.thumbnail_asset_uuid = thumbnail_asset.id + else: + logging.warning( + "Unable to determine thumbnail for setting '%s' in album %s", + album_model.thumbnail_setting, + album_model.get_final_name(), + ) + # Update album properties (which will only pick a random thumbnail and set it, no other properties are changed) + self.api_client.update_album_properties(album_model) + + # Perform sync mode action: Trigger offline asset removal + if self.config.sync_mode == 2: + logging.info("Trigger offline asset removal") + self.api_client.trigger_offline_asset_removal() + + # Perform sync mode action: Delete empty albums + # + # For Immich versions prior to v1.116.0: + # Attention: Since Offline Asset Removal is an asynchronous job, + # albums affected by it are most likely not empty yet! So this + # might only be effective in the next script run. + if self.config.sync_mode >= 1: + logging.info("Deleting all empty albums") + albums = self.api_client.fetch_albums() + # pylint: disable=C0103 + empty_album_count = 0 + # pylint: disable=C0103 + cleaned_album_count = 0 + for a in albums: + if a.asset_count == 0: + empty_album_count += 1 + logging.info("Deleting empty album %s", a.album_name) + if self.api_client.delete_album(a.id): + cleaned_album_count += 1 + if empty_album_count > 0: + logging.info( + "Successfully deleted %d/%d empty albums!", + cleaned_album_count, + empty_album_count, + ) + else: + logging.info("No empty albums found!") + + logging.info("Done!") + + +class Utils: + """A collection of helper methods""" + + @staticmethod + def divide_chunks(full_list: list[Any], chunk_size: int): + """ + Yield successive chunk_size-sized chunks from full_list. + + :param full_list: The full list to create chunks from + :param chunk_size: The number of records per chunk + """ + # looping till length l + for j in range(0, len(full_list), chunk_size): + yield full_list[j : j + chunk_size] + + @staticmethod + def assert_not_none_or_empty(key: str, value: Any): + """ + Asserts that the passed value is not None and not empty + + :param value: The value to assert + :raises: ValueError if the passed value is None or empty + """ + if value is None or len(str(value)) == 0: + raise ValueError("Value for " + key + " is None or empty") + + @staticmethod + def get_value_or_config_default( + key: str, args_dict: dict[str, Any], default: Any + ) -> Any: + """ + Returns the value stored in args_dict under the provided key if it is not None or empty, + otherwise returns the value from Configuration.CONFIG_DEAULTS using the same key. + + :param default: The default value to return if value did not pass the check + :param key: The dictionary key to look up the value for + + :returns: The passed value or the configuration default if the value did not pass the checks + :rtype: any + """ + try: + Utils.assert_not_none_or_empty( + key, args_dict[key] if key in args_dict else None + ) + return args_dict[key] + except ValueError: + return default + + @staticmethod + def is_integer(string_to_test: Any) -> bool: + """ + Trying to deal with python's isnumeric() function + not recognizing negative numbers, tests whether the provided + string is an integer or not. + + :param string_to_test: The string to test for integer + + :returns: True if string_to_test is an integer, otherwise False + :rtype: bool + """ + try: + int(string_to_test) + return True + except ValueError: + return False + + @staticmethod + def read_file(file_path: str, encoding: str = "utf-8") -> str: + """ + Reads and returns the contents of the provided file. + Assumes + + :param file_path: Path to the file to read + :param encoding: The encoding to read the file with, defaults to `utf-8` + + :returns: The file's contents + :rtype: str + + :raises: FileNotFoundError if the file does not exist + :raises: Exception on any other error reading the file + """ + with open(file_path, "r", encoding=encoding) as secret_file: + return secret_file.read().strip() + + +class AlbumCreatorLogFormatter(logging.Formatter): + """Log formatter logging as logfmt with seconds-precision timestamps and lower-case log levels to match supercronic's logging""" + + def init_formatter(self, is_debug: bool) -> None: + """ + Initializes the log formatter, respecting the passed is_debug flag. + + :param is_debug: When true, sets the time format timestamp to 'milliseconds', otherwise to 'seconds'. + """ + timespec_setting = "seconds" + if is_debug: + timespec_setting = "milliseconds" + + logging.Formatter.formatTime = lambda self, record, datefmt=None: ( + datetime.datetime.fromtimestamp(record.created, datetime.timezone.utc) + .astimezone() + .replace(microsecond=0) + .isoformat(sep="T", timespec=timespec_setting) + .replace("+00:00", "Z") + ) + + def format(self, record: LogRecord): + record.levelname = record.levelname.lower() + return logging.Formatter.format(self, record) + + +# Set up logging +handler = logging.StreamHandler() +formatter = AlbumCreatorLogFormatter( + 'time="%(asctime)s" level=%(levelname)s msg="%(message)s"' +) +formatter.init_formatter(False) +handler.setFormatter(formatter) +# Initialize logging with default log level, we might have to log something when initializing the global configuration (which includes the log level we should use) +logging.basicConfig( + level=Configuration.CONFIG_DEFAULTS["log_level"], handlers=[handler] +) +# Initialize global config +Configuration.init_global_config() +# Update log level with the level this configuration dictates +print(Configuration.log_level) +logging.getLogger().setLevel(Configuration.log_level) +if "DEBUG" == Configuration.log_level: + formatter.init_formatter(True) + + +async def main() -> None: + """ + Script's main function parsing the configuration and running + the main logic for each configuration set. + """ + _shutdown_requested = threading.Event() + + # pylint: disable=unused-argument + def handle_shutdown(signum: int, frame: Any) -> None: + # This function runs in the main thread. + _shutdown_requested.set() + + # Raising KeyboardInterrupt causes normal context-manager cleanup: + # async with ApiClient(...) as client: + # ... + raise KeyboardInterrupt + + signal.signal(signal.SIGINT, handle_shutdown) + + if hasattr(signal, "SIGTERM"): + signal.signal(signal.SIGTERM, handle_shutdown) + + try: + configs = Configuration.get_configurations() + logging.info("Created %d configurations", len(configs)) + except HTTPError as e: + logging.fatal(e.msg) + sys.exit(1) + except (ValueError, AssertionError) as e: + logging.fatal(str(e)) + sys.exit(1) + + Configuration.log_debug_global() + + for config in configs: + try: + folder_album_creator = FolderAlbumCreator(config) + + processing_api_key = folder_album_creator.api_client.api_key[:5] + "*" * ( + len(folder_album_creator.api_client.api_key) - 5 + ) + # Log the full API key when DEBUG logging is enabled + if "DEBUG" == config.log_level: + processing_api_key = folder_album_creator.api_client.api_key + + logging.info("Processing API Key %s", processing_api_key) + # Log config to DEBUG level + config.log_debug() + await folder_album_creator.run() + except ( + AlbumMergeError, + AlbumModelValidationError, + HTTPError, + ValueError, + AssertionError, + ) as e: + logging.fatal("Fatal error while processing configuration!") + logging.fatal(e) + + +asyncio.run(main()) diff --git a/immich-scripts/requirements.txt b/immich-scripts/requirements.txt new file mode 100755 index 0000000..456a8fa --- /dev/null +++ b/immich-scripts/requirements.txt @@ -0,0 +1,7 @@ +urllib3>=2.8.0 +pyyaml>=6.0.3 +regex>=2026.9.29 +tenacity>=9.2.1,<10.0.0 +# check https://github.com/timonrieger/immichpy/blob/main/COMPATIBILITY.csv +# for the exact version to use that supports the server version you are using +immichpy==9.2.4 \ No newline at end of file diff --git a/immich-scripts/restore_user.py b/immich-scripts/restore_user.py new file mode 100755 index 0000000..ae5f7fe --- /dev/null +++ b/immich-scripts/restore_user.py @@ -0,0 +1,45 @@ +#!/home/lucas/scripts/.venv/bin/python + + +import requests + +IMMICH_URL = "https://fotos.someoneslinux.selfhost.eu/api" +API_KEY = "I0vEVKsx89rlPv50xp1ZvZfP5jgApRSOGC9uR5Ekzc" +USERNAME = "Mimi" + +headers = { + "x-api-key": API_KEY, + "Accept": "application/json", +} + +# Find deleted user +resp = requests.get( + f"{IMMICH_URL}/admin/users", + headers=headers, + params={"withDeleted": "true"}, +) +resp.raise_for_status() + +users = resp.json() + +user = next( + (u for u in users if u.get("name") == USERNAME and u.get("status") == "deleted"), + None, +) + +if not user: + print(f"No deleted user named '{USERNAME}' found") + raise SystemExit(1) + + +user_id = user["id"] + +print(f"Restore user {USERNAME}: {user_id}") +# Restore user +resp = requests.post( + f"{IMMICH_URL}/admin/users/{user_id}/restore", + headers=headers, +) +resp.raise_for_status() + +print(f"Restored user '{USERNAME}' ({user_id})")