Files
Server-scripts/immich-scripts/immich_auto_album.py
T

3636 lines
153 KiB
Python
Executable File

#!/home/lucas/scripts/immich-scripts/.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 '<startLevel>,<endLevel>'. "
"If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>."
)
)
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 `**/*<expr>*/**`
: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 '<startLevel>,<endLevel>'.
If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>.""",
)
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 <userName>=<shareRole> must be used, where <shareRole> 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 <name>=<role>
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())