immich-export 0.0.2__py3-none-any.whl

immich_export/__init__.py

@@ -0,0 +1,3 @@
+"""immich-export — pull files *and* metadata out of Immich into a plain local tree."""
+
+__version__ = "0.0.2"

immich_export/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m immich_export`."""
+
+from .cli import app
+
+app()

immich_export/api_contract.py

@@ -0,0 +1,72 @@
+"""The exact slice of the Immich API this tool depends on.
+
+`tests/test_contract.py` checks every entry here against the vendored OpenAPI
+spec (`tests/data/immich-openapi.pruned.json`). To check compatibility with a
+new Immich release: `uv run python scripts/refresh_api_spec.py` and re-run the
+tests — a removed endpoint or field fails loudly instead of breaking at runtime.
+"""
+
+from __future__ import annotations
+
+ENDPOINTS: dict[str, frozenset[str]] = {
+    "/albums": frozenset({"get"}),
+    "/assets/{id}/original": frozenset({"get"}),
+    "/people": frozenset({"get"}),
+    "/search/metadata": frozenset({"post"}),
+    "/server/about": frozenset({"get"}),
+    "/server/ping": frozenset({"get"}),
+    "/tags": frozenset({"get"}),
+}
+
+# Response fields read, per OpenAPI schema (camelCase, as on the wire).
+RESPONSE_FIELDS: dict[str, frozenset[str]] = {
+    "AlbumResponseDto": frozenset({"id", "albumName", "assetCount", "description"}),
+    "AssetResponseDto": frozenset(
+        {
+            "id",
+            "originalFileName",
+            "originalPath",
+            "checksum",
+            "fileCreatedAt",
+            "localDateTime",
+            "type",
+            "isFavorite",
+            "exifInfo",
+            "people",
+            "tags",
+        }
+    ),
+    "ExifResponseDto": frozenset(
+        {
+            "dateTimeOriginal",
+            "description",
+            "latitude",
+            "longitude",
+            "city",
+            "state",
+            "country",
+            "make",
+            "model",
+        }
+    ),
+    "PersonResponseDto": frozenset({"id", "name", "isHidden"}),
+    "PeopleResponseDto": frozenset({"people", "hasNextPage", "total"}),
+    "SearchAssetResponseDto": frozenset({"items", "nextPage"}),
+    "ServerAboutResponseDto": frozenset({"version"}),
+    "TagResponseDto": frozenset({"id", "name", "value"}),
+}
+
+# Request fields sent in the POST /search/metadata body.
+SEARCH_REQUEST_FIELDS: frozenset[str] = frozenset(
+    {
+        "page",
+        "size",
+        "order",
+        "withExif",
+        "withPeople",
+        "visibility",
+        "takenAfter",
+        "albumIds",
+        "tagIds",
+    }
+)

immich_export/cli.py

@@ -0,0 +1,149 @@
+"""Typer CLI — thin layer over `exporter.run_export`; owns exit codes and messages."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import logging
+import sys
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from . import __version__
+from .config import ExportConfig, ExportMode, SidecarFormat
+from .errors import EXIT_UNEXPECTED, ImmichExportError
+
+app = typer.Typer(add_completion=False, context_settings={"help_option_names": ["-h", "--help"]})
+
+
+def _version() -> str:
+    try:
+        return importlib.metadata.version("immich-export")
+    except importlib.metadata.PackageNotFoundError:
+        return __version__
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"immich-export {_version()}")
+        raise typer.Exit()
+
+
+@app.command()
+def export(
+    server: Annotated[
+        str,
+        typer.Option("--server", envvar="IMMICH_SERVER", help="Immich base URL."),
+    ],
+    api_key: Annotated[
+        str,
+        typer.Option("--api-key", envvar="IMMICH_API_KEY", help="Immich API key."),
+    ] = "",
+    out: Annotated[Path, typer.Option("--out", help="Export destination directory.")] = Path(
+        "./immich-export"
+    ),
+    mode: Annotated[
+        ExportMode,
+        typer.Option("--mode", help="self-contained copies originals; sidecar only writes XMP."),
+    ] = ExportMode.SELF_CONTAINED,
+    layout: Annotated[
+        str,
+        typer.Option(
+            "--layout",
+            help="Primary tree layout; tokens: {year} {month} {day} {album} {type}.",
+        ),
+    ] = "{year}/{month}",
+    album_view: Annotated[
+        bool, typer.Option("--album-view/--no-album-view", help="Build albums/ symlink view.")
+    ] = True,
+    people_view: Annotated[
+        bool, typer.Option("--people-view/--no-people-view", help="Build people/ symlink view.")
+    ] = True,
+    sidecars: Annotated[
+        SidecarFormat,
+        typer.Option("--sidecars", help="Sidecar format."),
+    ] = SidecarFormat.XMP,
+    since: Annotated[
+        datetime | None,
+        typer.Option("--since", help="Only assets taken on/after this date (incremental)."),
+    ] = None,
+    resume: Annotated[
+        bool,
+        typer.Option(
+            "--resume/--no-resume",
+            help="Skip assets already exported with an unchanged checksum (via manifest.jsonl).",
+        ),
+    ] = True,
+    include_hidden: Annotated[
+        bool,
+        typer.Option("--include-hidden", help="Also export hidden and locked-folder assets."),
+    ] = False,
+    library_root: Annotated[
+        Path | None,
+        typer.Option("--library-root", help="Storage-Template tree (required for --mode sidecar)."),
+    ] = None,
+    concurrency: Annotated[int, typer.Option("--concurrency", help="Parallel downloads.")] = 4,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Debug logging + full tracebacks.")
+    ] = False,
+    _version_flag: Annotated[
+        bool,
+        typer.Option("--version", callback=_version_callback, is_eager=True),
+    ] = False,
+) -> None:
+    """Export all Immich assets + metadata into a plain, human-readable folder tree."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(levelname)s %(name)s: %(message)s" if verbose else "%(message)s",
+        stream=sys.stderr,
+    )
+    cfg = ExportConfig(
+        server=server,
+        api_key=api_key,
+        out=out,
+        mode=mode,
+        layout=layout,
+        album_view=album_view,
+        people_view=people_view,
+        write_sidecars=sidecars is SidecarFormat.XMP,
+        since=since,
+        resume=resume,
+        include_hidden=include_hidden,
+        library_root=library_root,
+        concurrency=concurrency,
+    )
+    try:
+        from .exporter import run_export
+
+        report = asyncio.run(run_export(cfg))
+    except ImmichExportError as exc:
+        if verbose:
+            traceback.print_exc()
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+    except Exception as exc:
+        if verbose:
+            traceback.print_exc()
+        typer.secho(
+            f"Unexpected error: {exc} (re-run with --verbose for the full traceback)",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_UNEXPECTED) from exc
+
+    if report.total == 0:
+        typer.echo("Immich library is empty — nothing to export (manifest written).")
+    else:
+        typer.echo(
+            f"Done: {report.exported} exported, {report.skipped} skipped, "
+            f"{len(report.errors)} errors in {report.duration_seconds:.1f}s "
+            f"→ {cfg.out} (see export-report.txt)"
+        )
+
+
+if __name__ == "__main__":
+    app()

immich_export/client.py

@@ -0,0 +1,189 @@
+"""Thin, typed, read-only client for the Immich v3 REST API.
+
+Endpoint paths and request/response fields are declared centrally (see
+`api_contract.py`) and checked against the vendored OpenAPI spec in CI.
+All network failures are translated into the user-facing error types in
+`errors.py`; no httpx exception escapes this module.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import AsyncIterator, Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from .errors import AuthError, OutputError, ServerUnreachableError
+from .models import Album, Asset, Person, SearchAssetPage, ServerAbout, Tag
+
+PAGE_SIZE = 1000
+"""Maximum page size accepted by /search/metadata (per the OpenAPI spec)."""
+
+DEFAULT_VISIBILITIES: tuple[str, ...] = ("timeline", "archive")
+"""Asset visibilities exported by default; 'hidden' and 'locked' are opt-in."""
+
+
+def _format_taken_after(value: datetime) -> str:
+    """Immich validates takenAfter against a strict ISO-8601-with-Z pattern."""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=UTC)
+    return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+
+
+class ImmichClient:
+    """Async wrapper around the handful of Immich endpoints this tool needs."""
+
+    def __init__(
+        self,
+        server: str,
+        api_key: str,
+        *,
+        timeout: float = 60.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._server = server.rstrip("/")
+        self._http = httpx.AsyncClient(
+            base_url=f"{self._server}/api",
+            headers={"x-api-key": api_key, "Accept": "application/json"},
+            timeout=timeout,
+            follow_redirects=True,
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = await self._http.request(method, path, **kwargs)
+        except httpx.TransportError as exc:
+            raise ServerUnreachableError(
+                f"Cannot reach Immich at {self._server}: {exc}. "
+                "Is the server up and the URL correct?"
+            ) from exc
+        if response.status_code in (401, 403):
+            raise AuthError(
+                "Authentication failed — check your Immich API key (--api-key / $IMMICH_API_KEY)."
+            )
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise ServerUnreachableError(
+                f"Immich at {self._server} answered {response.status_code} for {path}."
+            ) from exc
+        return response
+
+    async def check_connection(self) -> ServerAbout:
+        """Verify the server is reachable and the API key is valid."""
+        await self._request("GET", "/server/ping")
+        about = await self._request("GET", "/server/about")
+        return ServerAbout.model_validate(about.json())
+
+    async def iter_assets(
+        self,
+        *,
+        taken_after: datetime | None = None,
+        visibilities: Sequence[str] = DEFAULT_VISIBILITIES,
+    ) -> AsyncIterator[list[Asset]]:
+        """Yield pages of assets with EXIF and people populated."""
+        for visibility in visibilities:
+            body: dict[str, Any] = {
+                "size": PAGE_SIZE,
+                "withExif": True,
+                "withPeople": True,
+                "order": "asc",
+                "visibility": visibility,
+            }
+            if taken_after is not None:
+                body["takenAfter"] = _format_taken_after(taken_after)
+            async for page in self._paged_search(body):
+                yield page.items
+
+    async def search_asset_ids(
+        self, *, album_id: str | None = None, tag_id: str | None = None
+    ) -> list[str]:
+        """Asset ids matching an album or tag filter (v3 has no GET membership endpoint)."""
+        body: dict[str, Any] = {"size": PAGE_SIZE, "order": "asc"}
+        if album_id is not None:
+            body["albumIds"] = [album_id]
+        if tag_id is not None:
+            body["tagIds"] = [tag_id]
+        ids: list[str] = []
+        async for page in self._paged_search(body):
+            ids.extend(asset.id for asset in page.items)
+        return ids
+
+    async def _paged_search(self, body: dict[str, Any]) -> AsyncIterator[SearchAssetPage]:
+        page_token: str | None = "1"
+        while page_token is not None:
+            response = await self._request(
+                "POST", "/search/metadata", json={**body, "page": int(page_token)}
+            )
+            page = SearchAssetPage.model_validate(response.json()["assets"])
+            yield page
+            page_token = page.next_page
+
+    async def list_albums(self) -> list[Album]:
+        response = await self._request("GET", "/albums")
+        return [Album.model_validate(item) for item in response.json()]
+
+    async def list_people(self) -> list[Person]:
+        people: list[Person] = []
+        page = 1
+        while True:
+            response = await self._request(
+                "GET", "/people", params={"page": page, "withHidden": False}
+            )
+            payload = response.json()
+            people.extend(Person.model_validate(item) for item in payload["people"])
+            if not payload.get("hasNextPage"):
+                return people
+            page += 1
+
+    async def list_tags(self) -> list[Tag]:
+        response = await self._request("GET", "/tags")
+        return [Tag.model_validate(item) for item in response.json()]
+
+    async def download_original(self, asset_id: str, dest: Path) -> str:
+        """Stream an original file to `dest`; returns the hex SHA-1 of the bytes written.
+
+        Writes to a `.part` file first and renames on success, so an interrupted
+        run never leaves a truncated file at the final path.
+        """
+        tmp = dest.with_name(dest.name + ".part")
+        sha1 = hashlib.sha1()
+        try:
+            async with self._http.stream("GET", f"/assets/{asset_id}/original") as response:
+                if response.status_code in (401, 403):
+                    raise AuthError(
+                        "Authentication failed — check your Immich API key "
+                        "(--api-key / $IMMICH_API_KEY)."
+                    )
+                response.raise_for_status()
+                with tmp.open("wb") as fh:
+                    async for chunk in response.aiter_bytes():
+                        sha1.update(chunk)
+                        fh.write(chunk)
+        except httpx.TransportError as exc:
+            tmp.unlink(missing_ok=True)
+            raise ServerUnreachableError(
+                f"Cannot reach Immich at {self._server}: {exc}. "
+                "Is the server up and the URL correct?"
+            ) from exc
+        except OSError as exc:
+            tmp.unlink(missing_ok=True)
+            raise OutputError(f"Cannot write to {dest}: {exc}") from exc
+        tmp.replace(dest)
+        return sha1.hexdigest()

immich_export/config.py

@@ -0,0 +1,61 @@
+"""Validated run configuration, independent of the CLI layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .errors import ConfigError
+from .layout import validate_layout
+
+
+class ExportMode(StrEnum):
+    SELF_CONTAINED = "self-contained"
+    SIDECAR = "sidecar"
+
+
+class SidecarFormat(StrEnum):
+    XMP = "xmp"
+    NONE = "none"
+
+
+@dataclass(frozen=True)
+class ExportConfig:
+    server: str
+    api_key: str
+    out: Path
+    mode: ExportMode = ExportMode.SELF_CONTAINED
+    layout: str = "{year}/{month}"
+    album_view: bool = True
+    people_view: bool = True
+    write_sidecars: bool = True
+    since: datetime | None = None
+    resume: bool = True
+    include_hidden: bool = False
+    library_root: Path | None = None
+    """Where the existing Storage-Template tree lives (sidecar mode only)."""
+    concurrency: int = 4
+
+    def validate(self) -> None:
+        parsed = urlparse(self.server)
+        if parsed.scheme not in ("http", "https") or not parsed.netloc:
+            raise ConfigError(
+                f"--server must be an http(s) URL, got {self.server!r} "
+                "(e.g. https://immich.local:2283)."
+            )
+        if not self.api_key:
+            raise ConfigError(
+                "No API key — pass --api-key or set $IMMICH_API_KEY "
+                "(Immich → Account Settings → API Keys)."
+            )
+        validate_layout(self.layout)
+        if self.mode is ExportMode.SIDECAR:
+            if self.library_root is None:
+                raise ConfigError("--mode sidecar requires --library-root <storage-template dir>.")
+            if not self.library_root.is_dir():
+                raise ConfigError(f"--library-root {self.library_root} is not a directory.")
+        if self.concurrency < 1:
+            raise ConfigError("--concurrency must be at least 1.")

immich_export/errors.py

@@ -0,0 +1,38 @@
+"""User-facing errors with stable exit codes (never a raw traceback by default)."""
+
+from __future__ import annotations
+
+EXIT_UNEXPECTED = 1
+EXIT_CONFIG = 2
+EXIT_UNREACHABLE = 3
+EXIT_OUTPUT = 4
+
+
+class ImmichExportError(Exception):
+    """Base for all errors that should surface as a one-line human message."""
+
+    exit_code: int = EXIT_UNEXPECTED
+
+
+class ConfigError(ImmichExportError):
+    """Invalid flags, malformed URL, missing required options."""
+
+    exit_code = EXIT_CONFIG
+
+
+class AuthError(ImmichExportError):
+    """API key rejected by the server (401/403)."""
+
+    exit_code = EXIT_CONFIG
+
+
+class ServerUnreachableError(ImmichExportError):
+    """Connection refused, DNS failure, timeout."""
+
+    exit_code = EXIT_UNREACHABLE
+
+
+class OutputError(ImmichExportError):
+    """Output directory unwritable or out of space."""
+
+    exit_code = EXIT_OUTPUT