immichpy 1.6.5__py3-none-any.whl

immichpy/cli/main.py

@@ -0,0 +1,248 @@
+"""Main CLI entrypoint."""
+
+from __future__ import annotations
+
+import sys
+import typer
+import click
+from typing import Optional
+from importlib.metadata import version
+
+from rich.console import Console
+
+from immichpy.cli.consts import (
+    API_KEY_URL,
+    DEFAULT_FORMAT,
+    DEFAULT_PROFILE,
+    IMMICH_API_KEY,
+    IMMICH_ACCESS_TOKEN,
+    IMMICH_API_URL,
+    IMMICH_FORMAT,
+    IMMICH_PROFILE,
+)
+from immichpy.cli.utils import resolve_client_config, mask, print_
+
+from immichpy import AsyncClient
+from immichpy.cli.types import FormatMode, ClientConfig
+
+# Import command modules
+from immichpy.cli.commands import api_keys as api_keys_commands
+from immichpy.cli.commands import activities as activities_commands
+from immichpy.cli.commands import albums as albums_commands
+from immichpy.cli.wrapper import assets as assets_wrapper
+from immichpy.cli.commands import authentication as authentication_commands
+from immichpy.cli.commands import authentication_admin as authentication_admin_commands
+from immichpy.cli.wrapper import download as download_wrapper
+from immichpy.cli.wrapper import config as config_commands
+from immichpy.cli.wrapper import setup as setup_commands
+from immichpy.cli.commands import duplicates as duplicates_commands
+from immichpy.cli.commands import faces as faces_commands
+from immichpy.cli.commands import jobs as jobs_commands
+from immichpy.cli.commands import libraries as libraries_commands
+from immichpy.cli.commands import maintenance_admin as maintenance_admin_commands
+from immichpy.cli.commands import map as map_commands
+from immichpy.cli.commands import memories as memories_commands
+from immichpy.cli.commands import notifications as notifications_commands
+from immichpy.cli.commands import notifications_admin as notifications_admin_commands
+from immichpy.cli.commands import partners as partners_commands
+from immichpy.cli.commands import people as people_commands
+from immichpy.cli.commands import plugins as plugins_commands
+from immichpy.cli.commands import queues as queues_commands
+from immichpy.cli.commands import search as search_commands
+from immichpy.cli.commands import server as server_commands
+from immichpy.cli.commands import sessions as sessions_commands
+from immichpy.cli.commands import shared_links as shared_links_commands
+from immichpy.cli.commands import stacks as stacks_commands
+from immichpy.cli.commands import sync as sync_commands
+from immichpy.cli.commands import system_config as system_config_commands
+from immichpy.cli.commands import system_metadata as system_metadata_commands
+from immichpy.cli.commands import tags as tags_commands
+from immichpy.cli.commands import timeline as timeline_commands
+from immichpy.cli.commands import trash as trash_commands
+from immichpy.cli.wrapper import users as users_wrapper
+from immichpy.cli.commands import users_admin as users_admin_commands
+from immichpy.cli.commands import views as views_commands
+from immichpy.cli.commands import workflows as workflows_commands
+
+# Global state
+app = typer.Typer(
+    context_settings={"help_option_names": ["-h", "--help"]}, no_args_is_help=True
+)
+console = Console()
+stderr_console = Console(file=sys.stderr)
+
+# Add command modules to the main app
+app.add_typer(api_keys_commands.app, name="api-keys", rich_help_panel="API commands")
+app.add_typer(
+    activities_commands.app, name="activities", rich_help_panel="API commands"
+)
+app.add_typer(albums_commands.app, name="albums", rich_help_panel="API commands")
+app.add_typer(assets_wrapper.app, name="assets", rich_help_panel="API commands")
+app.add_typer(authentication_commands.app, name="auth", rich_help_panel="API commands")
+app.add_typer(
+    authentication_admin_commands.app,
+    name="auth-admin",
+    rich_help_panel="API commands",
+)
+app.add_typer(download_wrapper.app, name="download", rich_help_panel="API commands")
+app.add_typer(config_commands.app, name="config", rich_help_panel="Custom commands")
+app.command(rich_help_panel="Custom commands")(setup_commands.setup)
+app.add_typer(
+    duplicates_commands.app, name="duplicates", rich_help_panel="API commands"
+)
+app.add_typer(faces_commands.app, name="faces", rich_help_panel="API commands")
+app.add_typer(jobs_commands.app, name="jobs", rich_help_panel="API commands")
+app.add_typer(libraries_commands.app, name="libraries", rich_help_panel="API commands")
+app.add_typer(
+    maintenance_admin_commands.app,
+    name="maintenance-admin",
+    rich_help_panel="API commands",
+)
+app.add_typer(map_commands.app, name="map", rich_help_panel="API commands")
+app.add_typer(memories_commands.app, name="memories", rich_help_panel="API commands")
+app.add_typer(
+    notifications_commands.app, name="notifications", rich_help_panel="API commands"
+)
+app.add_typer(
+    notifications_admin_commands.app,
+    name="notifications-admin",
+    rich_help_panel="API commands",
+)
+app.add_typer(partners_commands.app, name="partners", rich_help_panel="API commands")
+app.add_typer(people_commands.app, name="people", rich_help_panel="API commands")
+app.add_typer(plugins_commands.app, name="plugins", rich_help_panel="API commands")
+app.add_typer(queues_commands.app, name="queues", rich_help_panel="API commands")
+app.add_typer(search_commands.app, name="search", rich_help_panel="API commands")
+app.add_typer(server_commands.app, name="server", rich_help_panel="API commands")
+app.add_typer(sessions_commands.app, name="sessions", rich_help_panel="API commands")
+app.add_typer(
+    shared_links_commands.app, name="shared-links", rich_help_panel="API commands"
+)
+app.add_typer(stacks_commands.app, name="stacks", rich_help_panel="API commands")
+app.add_typer(sync_commands.app, name="sync", rich_help_panel="API commands")
+app.add_typer(
+    system_config_commands.app, name="system-config", rich_help_panel="API commands"
+)
+app.add_typer(
+    system_metadata_commands.app, name="system-metadata", rich_help_panel="API commands"
+)
+app.add_typer(tags_commands.app, name="tags", rich_help_panel="API commands")
+app.add_typer(timeline_commands.app, name="timeline", rich_help_panel="API commands")
+app.add_typer(trash_commands.app, name="trash", rich_help_panel="API commands")
+app.add_typer(users_wrapper.app, name="users", rich_help_panel="API commands")
+app.add_typer(
+    users_admin_commands.app, name="users-admin", rich_help_panel="API commands"
+)
+app.add_typer(views_commands.app, name="views", rich_help_panel="API commands")
+app.add_typer(workflows_commands.app, name="workflows", rich_help_panel="API commands")
+
+
+def version_callback(value: bool) -> None:  # pragma: no cover
+    if value:
+        print_(f"immich CLI (unofficial) {version('immich')}", type="text")
+        raise typer.Exit(0)
+
+
+@app.callback(invoke_without_command=False)
+def callback(
+    ctx: typer.Context,
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show verbose output.",
+    ),
+    format_mode: FormatMode = typer.Option(
+        DEFAULT_FORMAT,
+        "--format",
+        help="Output format of the CLI.",
+        envvar=IMMICH_FORMAT,
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        help=f"Authorize via API key (get one [link={API_KEY_URL}]here[/link]).",
+        envvar=IMMICH_API_KEY,
+    ),
+    access_token: Optional[str] = typer.Option(
+        None,
+        "--access-token",
+        help="Authorize via access token.",
+        envvar=IMMICH_ACCESS_TOKEN,
+    ),
+    base_url: Optional[str] = typer.Option(
+        None,
+        "--base-url",
+        help="The server to connect to.",
+        envvar=IMMICH_API_URL,
+    ),
+    profile: str = typer.Option(
+        DEFAULT_PROFILE,
+        "--profile",
+        "-p",
+        envvar=IMMICH_PROFILE,
+        help="The profile to use.",
+    ),
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:  # pragma: no cover
+    ctx.ensure_object(dict)
+    ctx.obj["format"] = format_mode
+    ctx.obj["verbose"] = verbose
+    if ctx.invoked_subcommand is not None and ctx.invoked_subcommand not in [
+        "setup",
+        "config",
+    ]:
+        config = resolve_client_config(
+            ClientConfig(
+                api_key=api_key,
+                access_token=access_token,
+                base_url=base_url,
+            ),
+            profile=profile,
+            # we only consider the profile explicit if it was set via the command line
+            # environment variables are not considered explicit
+            profile_explicit=ctx.get_parameter_source("profile")
+            == click.core.ParameterSource.COMMANDLINE,
+        )
+        if not config.base_url:
+            print_(
+                "No base URL provided. Run 'immich setup' to set up a profile or use '--base-url' to specify a base URL.",
+                type="error",
+            )
+            raise typer.Exit(code=1)
+        if ctx.obj["verbose"]:
+            cli_vars = {
+                k: v
+                for k, v in ctx.params.items()
+                if k in ClientConfig.model_fields.keys() and v is not None
+            }
+            print_("Configuration used:", type="debug", ctx=ctx)
+            for field in ClientConfig.model_fields.keys():
+                value = getattr(config, field)
+                if field in ("api_key", "access_token") and value:
+                    value = mask(value)
+                elif value is None:
+                    value = "None"
+                source = "cli/env" if field in cli_vars else f"profile '{profile}'"
+                print_(f"- {field}: {value} (from {source})", type="debug", ctx=ctx)
+        if omit_access_token := (config.api_key is not None):
+            print_(
+                "Omitting access token because API key is provided.",
+                type="debug",
+                ctx=ctx,
+            )
+        ctx.obj["client"] = AsyncClient(
+            api_key=config.api_key,
+            access_token=None if omit_access_token else config.access_token,
+            base_url=config.base_url,
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

immichpy/cli/runtime.py

@@ -0,0 +1,97 @@
+"""Runtime helpers for executing async client calls and handling output."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import traceback
+from typing import Any, Awaitable, Callable
+
+from immichpy.cli.utils import print_
+from pydantic import BaseModel
+from typer import Context, Exit
+
+from immichpy.cli.types import MaybeBaseModel
+
+from immichpy import AsyncClient
+from immichpy.client.generated.exceptions import ApiException
+
+
+def set_nested(d: dict[str, Any], path: list[str], value: Any) -> None:
+    """Set a nested dictionary value using a path list.
+
+    Example: set_nested({}, ['user', 'name'], 'John') -> {'user': {'name': 'John'}}
+    """
+    current = d
+    for part in path[:-1]:
+        if part not in current:
+            current[part] = {}
+        elif not isinstance(current[part], dict):
+            current[part] = {}
+        current = current[part]
+    current[path[-1]] = value
+
+
+def print_response(data: MaybeBaseModel, ctx: Context) -> None:
+    """Print response data."""
+
+    def convert_to_dict(obj: MaybeBaseModel) -> Any:
+        """Recursively convert Pydantic models to dicts."""
+        if isinstance(obj, list):
+            return [convert_to_dict(item) for item in obj]
+        elif isinstance(obj, BaseModel):
+            return obj.model_dump()
+        else:
+            return obj
+
+    json_str = json.dumps(convert_to_dict(data), default=str)
+
+    print_(message=json_str, type="json", ctx=ctx)
+
+
+def format_api_error(e: ApiException) -> tuple[str, int]:
+    """Return (message, exit_code) for an ApiException."""
+    exit_code = 1 if e.status is None else e.status // 100
+
+    if not e.body:
+        return ("API error", exit_code)
+
+    if isinstance(e.body, str):
+        return (e.body, exit_code)
+
+    return (json.dumps(e.body, default=str), exit_code)
+
+
+async def run_async(coro: Awaitable[Any]) -> Any:
+    return await coro
+
+
+def run_command(
+    client: AsyncClient,
+    api_group: Any,
+    method_name: str,
+    ctx: Context | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Run a client API method and handle the result."""
+    method: Callable[..., Awaitable[Any]] = getattr(api_group, method_name)
+
+    async def _call_and_close() -> Any:
+        try:
+            return await method(**kwargs)
+        finally:
+            await client.close()
+
+    try:
+        return asyncio.run(_call_and_close())
+
+    except ApiException as e:
+        message, code = format_api_error(e)
+        print_(message, type="error", ctx=ctx)
+        print_(traceback.format_exc(), type="debug", ctx=ctx)
+        raise Exit(code=code)
+
+    except Exception as e:
+        print_(f"Unexpected error: {str(e).strip()}", type="error", ctx=ctx)
+        print_(traceback.format_exc(), type="debug", ctx=ctx)
+        raise Exit(code=1)

immichpy/cli/types.py

@@ -0,0 +1,17 @@
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel
+
+MaybeBaseModel = Optional[Union[BaseModel, list[BaseModel], str]]
+FormatMode = Literal["pretty", "json", "table"]
+PrintType = Literal["info", "warning", "error", "debug", "success", "json", "text"]
+
+
+class ClientConfig(BaseModel):
+    """
+    A configuration for a client to connect to an Immich server.
+    """
+
+    base_url: Optional[str]
+    api_key: Optional[str]
+    access_token: Optional[str]

immichpy/cli/utils.py

@@ -0,0 +1,227 @@
+from typing import Any, Optional, cast, overload
+import json
+
+from rich import print as print_rich, print_json
+from rich.table import Table
+import rtoml
+import typer
+
+from immichpy.cli.consts import CONFIG_FILE, DEFAULT_FORMAT, SECRET_KEYS
+from immichpy.cli.types import ClientConfig, FormatMode, PrintType
+
+
+def set_path(data: dict[str, Any], path: str, value: Any) -> None:
+    """
+    Set a nested dictionary value using a path list.
+
+    Example: set_path({}, 'user.name', 'John') -> {'user': {'name': 'John'}}
+    """
+    parts = path.split(".")
+    cur = data
+    for p in parts[:-1]:
+        cur = cur.setdefault(p, {})
+    cur[parts[-1]] = value
+
+
+def get_path(data: dict[str, Any], path: str) -> Any:
+    """
+    Get a nested dictionary value using a path list.
+    """
+    parts = path.split(".")
+    cur = data
+    for p in parts:
+        cur = cur[p]
+    return cur
+
+
+def load_config() -> dict[str, Any]:
+    """
+    Load the config file. Returns an empty dict if the file does not exist.
+    """
+    if not CONFIG_FILE.exists():
+        return {}
+    return rtoml.load(CONFIG_FILE, none_value="")
+
+
+def write_config(data: dict[str, Any]) -> None:
+    """
+    Write the config data to the config file and set permissions.
+    """
+    CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with CONFIG_FILE.open("w") as f:
+        rtoml.dump(data, f, none_value="")
+    CONFIG_FILE.chmod(0o600)
+
+
+def check_config() -> None:
+    """
+    Check if the config file exists.
+    """
+    if not CONFIG_FILE.exists():
+        print_(
+            "Config file does not exist. Run [bold]immich config set[/bold] to create it.",
+            type="error",
+        )
+        raise typer.Exit(code=1)
+
+
+def resolve_client_config(
+    config: ClientConfig, profile: str, profile_explicit: bool = False
+) -> ClientConfig:
+    """
+    Resolve the client config from the config file.
+
+    :param config: The config to resolve
+    :param profile: The profile to use
+    :param profile_explicit: Whether the profile was explicitly set by the user
+    :raises typer.Exit: If the profile is not found in the config
+    :return: The resolved config
+    """
+    data = load_config()
+    profiles: dict[str, Any] = data.get("profiles", {})
+
+    if profile_explicit and profile not in profiles:
+        print_(
+            f"Profile '{profile}' not found. Run immich config set --profile {profile}.",
+            type="error",
+        )
+        raise typer.Exit(code=1)
+
+    profile_data = profiles.get(profile, {})
+
+    return ClientConfig(
+        api_key=config.api_key or profile_data.get("api_key"),
+        access_token=config.access_token or profile_data.get("access_token"),
+        base_url=config.base_url or profile_data.get("base_url"),
+    )
+
+
+def _is_secret_key(key: str) -> bool:
+    """Check if a key indicates a secret value."""
+    return any(secret in key.lower() for secret in SECRET_KEYS)
+
+
+def _redact_secret(secret: str, start: int = 3, end: int = 3) -> str:
+    """
+    Redact a secret by showing only the first `start` and last `end` characters.
+
+    :param secret: The secret string to redact
+    :param start: Number of characters to show at the start (default: 3)
+    :param end: Number of characters to show at the end (default: 3)
+    :return: The redacted secret string
+    """
+    if not secret:
+        return ""
+
+    length = len(secret)
+    if length <= start + end:
+        return "*" * length
+
+    return secret[:start] + "*" * (length - start - end) + secret[-end:]
+
+
+@overload
+def mask(secret: str, start: int = 3, end: int = 3) -> str: ...
+
+
+@overload
+def mask(obj: Any, start: int = 3, end: int = 3, key: Optional[str] = None) -> Any: ...
+
+
+def mask(obj: Any, start: int = 3, end: int = 3, key: Optional[str] = None) -> Any:
+    """
+    Recursively mask secret values in nested dictionaries and lists.
+
+    :param obj: The object to mask (dict, list, or any other type)
+    :param start: Number of characters to show at the start (default: 3)
+    :param end: Number of characters to show at the end (default: 3)
+    :param key: Optional key path for top-level values to check if they're secrets
+    :return: The masked object with secrets redacted using _redact_secret
+    """
+    if isinstance(obj, dict):
+        return {
+            k: (
+                _redact_secret(v, start, end)
+                if _is_secret_key(k) and isinstance(v, str)
+                else mask(v, start, end, k)
+            )
+            for k, v in obj.items()
+        }
+    if isinstance(obj, list):
+        return [mask(v, start, end) for v in obj]
+    if isinstance(obj, str):
+        if key is None or _is_secret_key(key):
+            return _redact_secret(obj, start, end)
+    return obj
+
+
+def _print_table(data: Any) -> None:  # pragma: no cover
+    """
+    Print data as a table using rich.
+    For dicts: creates a table with key/value columns.
+    For lists: prints multiple tables.
+    """
+    if isinstance(data, list):
+        for item in data:
+            _print_table(item)
+    elif isinstance(data, dict):
+        _print_dict_table(data)
+    else:
+        print_rich(str(data))
+
+
+def _print_dict_table(data: dict[str, Any]) -> None:  # pragma: no cover
+    """Print a dictionary as a table with key and value columns."""
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Key", style="cyan")
+    table.add_column("Value", style="green")
+
+    for key, value in data.items():
+        table.add_row(key, str(value))
+
+    print_rich(table)
+
+
+def print_(
+    message: str,
+    *,
+    type: PrintType,
+    ctx: Optional[typer.Context] = None,
+) -> None:
+    """
+    Print a message in the given format as a rich print or a plain print.
+    :param message: The message to print
+    :param type: The type of the message
+    :param ctx: The context to use
+    """
+    match type:
+        case "json":
+            try:
+                format_mode = cast(FormatMode, ctx.obj.get("format", DEFAULT_FORMAT))  # type: ignore[possibly-missing-attribute]
+            except (AttributeError, KeyError):
+                format_mode = DEFAULT_FORMAT
+            match format_mode:
+                case "pretty":
+                    print_json(message)
+                case "json":
+                    print(message)
+                case "table":  # pragma: no cover
+                    try:
+                        data = json.loads(message)
+                        _print_table(data)
+                    except json.JSONDecodeError:
+                        print(message)
+                    print_("The 'table' format is experimental.", type="warning")
+        case "text":
+            print(message)
+        case "info":
+            print_rich(message)
+        case "warning":
+            print_rich(f"[yellow][bold][Warning][/bold] {message}[/yellow]")
+        case "error":
+            print_rich(f"[red][bold][Error][/bold] {message}[/red]")
+        case "success":
+            print_rich(f"[green][bold][Success][/bold][/green] {message}")
+        case "debug":
+            if ctx is not None and ctx.obj["verbose"]:
+                print_rich(f"[blue][bold][Debug][/bold] {message}[/blue]")