emby-cli 0.0.0rc1__py3-none-any.whl

emby_cli/__init__.py

@@ -0,0 +1,14 @@
+"""emby-cli — backup and stream media from an Emby server."""
+
+from __future__ import annotations
+
+import warnings
+
+# macOS system Python uses LibreSSL; urllib3 v2 only warns (TLS still works).
+# Must run before any import that pulls in requests/urllib3 (see client.py).
+warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
+
+from emby_cli.client import EmbyClient
+from emby_cli.version import get_version
+
+__all__ = ["EmbyClient", "get_version"]

emby_cli/__main__.py

@@ -0,0 +1,4 @@
+from emby_cli.cli import main
+
+if __name__ == "__main__":
+    main()

emby_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.0rc1'
+__version_tuple__ = version_tuple = (0, 0, 0, 'rc1')
+
+__commit_id__ = commit_id = None

emby_cli/api/__init__.py

@@ -0,0 +1,7 @@
+"""Entity-oriented services sharing one :class:`EmbyClient` transport."""
+
+from emby_cli.api.collections import CollectionsService
+from emby_cli.api.items import ItemsService
+from emby_cli.api.libraries import LibrariesService
+
+__all__ = ["CollectionsService", "ItemsService", "LibrariesService"]

emby_cli/api/collections.py

@@ -0,0 +1,110 @@
+"""Emby BoxSet collection operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from emby_cli.data_cache import delete_json
+
+if TYPE_CHECKING:
+    from emby_cli.client import EmbyClient
+
+
+COLLECTION_FIELDS = "ChildCount,ProductionYear,DisplayOrder,SortName"
+COLLECTION_DETAIL_FIELDS = COLLECTION_FIELDS + ",Overview"
+
+
+class CollectionsService:
+    """Entity service for Emby ``BoxSet`` resources."""
+
+    def __init__(self, client: EmbyClient):
+        self.client = client
+
+    def _catalog_key(self) -> str:
+        uid = self.client.resolve_user_id()
+        return f"v2:collections:{self.client.server_url}:{uid}"
+
+    def list(self, *, use_cache: bool = True) -> list[dict]:
+        """Return the complete collection catalog."""
+        key = self._catalog_key()
+        if use_cache:
+            cached = self.client._cache_read(key)
+            if isinstance(cached, list):
+                return cached
+        collections = self.client.items.list_all(
+            item_types="BoxSet",
+            fields=COLLECTION_FIELDS,
+            use_cache=False,
+        )
+        if use_cache:
+            self.client._cache_write(key, collections)
+        return collections
+
+    def search(self, query: str, *, use_cache: bool = True) -> list[dict]:
+        """Search collection names locally over the complete catalog."""
+        needle = query.strip().casefold()
+        collections = self.list(use_cache=use_cache)
+        if not needle:
+            return collections
+        return [
+            item
+            for item in collections
+            if needle in str(item.get("Name") or "").casefold()
+        ]
+
+    def create(
+        self,
+        name: str,
+        *,
+        item_ids: list[str] | None = None,
+        parent_id: str | None = None,
+        is_locked: bool = False,
+    ) -> dict:
+        params: dict = {
+            "Name": name,
+            "IsLocked": str(is_locked).lower(),
+        }
+        if item_ids:
+            params["Ids"] = ",".join(item_ids)
+        if parent_id:
+            params["ParentId"] = parent_id
+        result = self.client._post(
+            "/Collections",
+            params=params,
+            retries=1,
+        ).json()
+        self.invalidate_catalog()
+        return result
+
+    def add_items(self, collection_id: str, item_ids: list[str]) -> None:
+        self.client._post(
+            f"/Collections/{collection_id}/Items",
+            params={"Ids": ",".join(item_ids)},
+        )
+        self.invalidate(collection_id)
+
+    def remove_items(self, collection_id: str, item_ids: list[str]) -> None:
+        self.client._delete(
+            f"/Collections/{collection_id}/Items",
+            params={"Ids": ",".join(item_ids)},
+        )
+        self.invalidate(collection_id)
+
+    def delete(self, collection_id: str) -> None:
+        item = self.client.items.get(collection_id, use_cache=False)
+        if item.get("Type") != "BoxSet":
+            actual = item.get("Type") or "unknown"
+            raise ValueError(
+                f"refusing to delete item {collection_id}: expected BoxSet, got {actual}"
+            )
+        self.client.items.delete(collection_id)
+        self.invalidate(collection_id)
+
+    def invalidate_catalog(self) -> None:
+        delete_json(self._catalog_key())
+
+    def invalidate(self, collection_id: str) -> None:
+        self.invalidate_catalog()
+        self.client.items.invalidate(collection_id)
+        self.client.items.invalidate(collection_id, fields=COLLECTION_DETAIL_FIELDS)
+        self.client.items.invalidate_list(parent_id=collection_id)

emby_cli/api/items.py

@@ -0,0 +1,380 @@
+"""Generic Emby item operations built on the shared client transport."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from emby_cli.constants import ITEM_FIELDS, SEARCH_ITEM_TYPES
+from emby_cli.data_cache import delete_json
+from emby_cli.media_sort import sort_media_items
+
+if TYPE_CHECKING:
+    from emby_cli.client import EmbyClient
+
+ListingDefault = Literal["catalog", "parent"]
+
+
+class ItemsService:
+    """Read and mutate generic ``/Items`` resources."""
+
+    def __init__(self, client: EmbyClient):
+        self.client = client
+
+    def _key(self, item_id: str, fields: str | None) -> str:
+        uid = self.client.resolve_user_id()
+        return (
+            f"v2:item:{self.client.server_url}:{uid}:"
+            f"{item_id}:{fields or 'all'}"
+        )
+
+    def _listing_key(
+        self,
+        *,
+        parent_id: str | None,
+        query: str | None,
+        item_types: str,
+        year: int | None,
+        limit: int | None,
+        emby_sort: str,
+        sort_order: str,
+        fields: str | None,
+        recursive: bool,
+        client_sort: str | None,
+        client_desc: bool,
+    ) -> str:
+        uid = self.client.resolve_user_id()
+        query_part = query if query is not None else ""
+        year_part = str(year) if year is not None else ""
+        limit_part = str(limit) if limit is not None else "all"
+        client_part = f"{client_sort}:{'desc' if client_desc else 'asc'}" if client_sort else ""
+        return (
+            f"v2:item-list:{self.client.server_url}:{uid}:"
+            f"{parent_id or ''}:{query_part}:{item_types}:{year_part}:"
+            f"{limit_part}:{emby_sort}:{sort_order}:{fields or ITEM_FIELDS}:"
+            f"{recursive}:{client_part}"
+        )
+
+    def _list_key(
+        self,
+        *,
+        parent_id: str | None,
+        item_types: str | None,
+        fields: str | None,
+        recursive: bool,
+        sort_by: str,
+        sort_order: str,
+    ) -> str:
+        return self._listing_key(
+            parent_id=parent_id,
+            query=None,
+            item_types=item_types or SEARCH_ITEM_TYPES,
+            year=None,
+            limit=None,
+            emby_sort=sort_by,
+            sort_order=sort_order,
+            fields=fields,
+            recursive=recursive,
+            client_sort=None,
+            client_desc=False,
+        )
+
+    def _search_key(
+        self,
+        query: str,
+        item_types: str,
+        *,
+        year: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        desc: bool = False,
+    ) -> str:
+        emby_sort, sort_order, client_sort = self._resolve_list_sort(
+            sort_by,
+            desc=desc,
+            when_unsorted="catalog",
+        )
+        return self._listing_key(
+            parent_id=None,
+            query=query,
+            item_types=item_types,
+            year=year,
+            limit=limit,
+            emby_sort=emby_sort,
+            sort_order=sort_order,
+            fields=ITEM_FIELDS,
+            recursive=True,
+            client_sort=client_sort,
+            client_desc=desc,
+        )
+
+    @staticmethod
+    def _emby_sort_fields(primary: str) -> str:
+        """Append ``SortName`` as stable tie-breaker unless already sorting by name."""
+        if primary == "SortName" or primary.endswith(",SortName"):
+            return primary
+        return f"{primary},SortName"
+
+    @staticmethod
+    def _emby_sort(
+        sort_by: str | None,
+        *,
+        desc: bool,
+    ) -> tuple[str, str]:
+        if sort_by == "id":
+            return "SortName", "Ascending"
+        mapping = {
+            "name": "SortName",
+            "year": "ProductionYear",
+            "release-date": "PremiereDate",
+            "added-date": "DateCreated",
+            "resolution": "Resolution",
+            "size": "Size",
+        }
+        emby_sort = ItemsService._emby_sort_fields(mapping.get(sort_by or "", "DateCreated"))
+        order = "Descending" if desc else "Ascending"
+        if sort_by is None and not desc:
+            order = "Descending"
+        return emby_sort, order
+
+    @staticmethod
+    def _resolve_list_sort(
+        sort_by: str | None,
+        *,
+        desc: bool,
+        when_unsorted: ListingDefault,
+    ) -> tuple[str, str, str | None]:
+        """Return Emby sort, order, and optional client-side re-sort key."""
+        if sort_by == "id":
+            emby_sort, sort_order = ItemsService._emby_sort("id", desc=desc)
+            return emby_sort, sort_order, "id"
+        if sort_by:
+            emby_sort, sort_order = ItemsService._emby_sort(sort_by, desc=desc)
+            return emby_sort, sort_order, None
+        if when_unsorted == "parent":
+            return "SortName", "Ascending", None
+        emby_sort, sort_order = ItemsService._emby_sort(None, desc=desc)
+        return emby_sort, sort_order, None
+
+    def _list_items_raw(
+        self,
+        *,
+        parent_id: str | None = None,
+        query: str | None = None,
+        item_types: str | None = None,
+        year: int | None = None,
+        limit: int | None = None,
+        emby_sort: str,
+        sort_order: str,
+        fields: str | None = None,
+        recursive: bool = True,
+        client_sort: str | None = None,
+        client_desc: bool = False,
+        use_cache: bool = True,
+    ) -> tuple[list[dict], int]:
+        """Fetch ``/Users/{uid}/Items`` with explicit Emby sort parameters."""
+        types = item_types or SEARCH_ITEM_TYPES
+        fetch_limit = None if client_sort else limit
+        key = self._listing_key(
+            parent_id=parent_id,
+            query=query,
+            item_types=types,
+            year=year,
+            limit=limit,
+            emby_sort=emby_sort,
+            sort_order=sort_order,
+            fields=fields,
+            recursive=recursive,
+            client_sort=client_sort,
+            client_desc=client_desc,
+        )
+        if use_cache:
+            cached = self.client._cache_read(key)
+            if isinstance(cached, dict):
+                items = cached.get("items")
+                total = cached.get("total")
+                if isinstance(items, list) and isinstance(total, int):
+                    return items, total
+
+        uid = self.client.resolve_user_id()
+        params: dict = {
+            "Recursive": str(recursive).lower(),
+            "Fields": fields or ITEM_FIELDS,
+            "SortBy": emby_sort,
+            "SortOrder": sort_order,
+        }
+        if query is not None:
+            params["SearchTerm"] = query
+        if parent_id:
+            params["ParentId"] = parent_id
+        params["IncludeItemTypes"] = types
+        if year is not None:
+            params["Years"] = str(year)
+
+        items, total = self.client._paginate(
+            f"/Users/{uid}/Items",
+            params,
+            limit=fetch_limit,
+        )
+        if client_sort:
+            items = sort_media_items(items, client_sort, desc=client_desc)
+            total = len(items)
+            if limit is not None:
+                items = items[:limit]
+
+        payload = {"items": items, "total": int(total)}
+        if use_cache:
+            self.client._cache_write(key, payload)
+        return items, int(total)
+
+    def list_items(
+        self,
+        *,
+        query: str = "",
+        parent_id: str | None = None,
+        item_types: str | None = None,
+        year: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        desc: bool = False,
+        when_unsorted: ListingDefault = "catalog",
+        fields: str | None = None,
+        recursive: bool = True,
+        use_cache: bool = True,
+    ) -> tuple[list[dict], int]:
+        """List playable media items with CLI sort keys and optional scope filters."""
+        emby_sort, sort_order, client_sort = self._resolve_list_sort(
+            sort_by,
+            desc=desc,
+            when_unsorted=when_unsorted,
+        )
+        search_term = None if parent_id is not None else query
+        return self._list_items_raw(
+            parent_id=parent_id,
+            query=search_term,
+            item_types=item_types,
+            year=year,
+            limit=limit,
+            emby_sort=emby_sort,
+            sort_order=sort_order,
+            fields=fields,
+            recursive=recursive,
+            client_sort=client_sort,
+            client_desc=desc,
+            use_cache=use_cache,
+        )
+
+    def list_all(
+        self,
+        *,
+        parent_id: str | None = None,
+        item_types: str | None = None,
+        fields: str | None = None,
+        recursive: bool = True,
+        sort_by: str = "SortName",
+        sort_order: str = "Ascending",
+        use_cache: bool = True,
+    ) -> list[dict]:
+        """Return every matching item with explicit Emby ``SortBy`` field names."""
+        items, _total = self._list_items_raw(
+            parent_id=parent_id,
+            query=None,
+            item_types=item_types,
+            emby_sort=sort_by,
+            sort_order=sort_order,
+            fields=fields,
+            recursive=recursive,
+            use_cache=use_cache,
+        )
+        return items
+
+    def search(
+        self,
+        query: str = "",
+        *,
+        item_types: str | None = None,
+        year: int | None = None,
+        limit: int | None = None,
+        sort_by: str | None = None,
+        desc: bool = False,
+        use_cache: bool = True,
+    ) -> tuple[list[dict], int]:
+        """Search playable media items via Emby ``SearchTerm`` and filters."""
+        return self.list_items(
+            query=query,
+            item_types=item_types,
+            year=year,
+            limit=limit,
+            sort_by=sort_by,
+            desc=desc,
+            when_unsorted="catalog",
+            use_cache=use_cache,
+        )
+
+    def get(
+        self,
+        item_id: str,
+        *,
+        fields: str | None = None,
+        use_cache: bool = True,
+    ) -> dict:
+        """Get one item for the current user."""
+        uid = self.client.resolve_user_id()
+        key = self._key(item_id, fields)
+        if use_cache:
+            cached = self.client._cache_read(key)
+            if isinstance(cached, dict):
+                return cached
+        params = {"Fields": fields} if fields else None
+        data = self.client._get(
+            f"/Users/{uid}/Items/{item_id}",
+            params=params,
+        ).json()
+        if use_cache:
+            self.client._cache_write(key, data)
+        return data
+
+    def update(self, item_id: str, item: dict) -> None:
+        """Update an item with the complete object returned by Emby."""
+        self.client._post(f"/Items/{item_id}", item)
+        self.invalidate(item_id)
+
+    def merge_and_update(
+        self,
+        item_id: str,
+        updates: dict[str, object],
+        *,
+        fields: str | None = None,
+    ) -> dict:
+        """GET one item uncached, merge *updates*, POST the full object back."""
+        item = self.get(item_id, fields=fields, use_cache=False)
+        for key, value in updates.items():
+            item[key] = value
+        self.update(item_id, item)
+        return item
+
+    def delete(self, item_id: str) -> None:
+        """Delete one item using Emby's generic destructive endpoint."""
+        self.client._delete(f"/Items/{item_id}")
+        self.invalidate(item_id)
+
+    def invalidate(self, item_id: str, *, fields: str | None = None) -> None:
+        delete_json(self._key(item_id, fields))
+
+    def invalidate_list(
+        self,
+        *,
+        parent_id: str | None = None,
+        item_types: str | None = None,
+        fields: str | None = None,
+        recursive: bool = True,
+        sort_by: str = "SortName",
+        sort_order: str = "Ascending",
+    ) -> None:
+        delete_json(self._list_key(
+            parent_id=parent_id,
+            item_types=item_types,
+            fields=fields,
+            recursive=recursive,
+            sort_by=sort_by,
+            sort_order=sort_order,
+        ))

emby_cli/api/libraries.py

@@ -0,0 +1,49 @@
+"""Emby library view operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from emby_cli.data_cache import delete_json
+
+if TYPE_CHECKING:
+    from emby_cli.client import EmbyClient
+
+
+class LibrariesService:
+    """Entity service for Emby library views (``/Users/{uid}/Views``)."""
+
+    def __init__(self, client: EmbyClient):
+        self.client = client
+
+    def _catalog_key(self) -> str:
+        uid = self.client.resolve_user_id()
+        return f"v2:libraries:{self.client.server_url}:{uid}"
+
+    def list(self, *, use_cache: bool = True) -> list[dict]:
+        """Return every library view for the current user."""
+        key = self._catalog_key()
+        if use_cache:
+            cached = self.client._cache_read(key)
+            if isinstance(cached, list):
+                return cached
+        uid = self.client.resolve_user_id()
+        libraries = self.client._get(f"/Users/{uid}/Views").json().get("Items", [])
+        if use_cache:
+            self.client._cache_write(key, libraries)
+        return libraries
+
+    def search(self, query: str, *, use_cache: bool = True) -> list[dict]:
+        """Search library names locally over the complete catalog."""
+        needle = query.strip().casefold()
+        libraries = self.list(use_cache=use_cache)
+        if not needle:
+            return libraries
+        return [
+            lib
+            for lib in libraries
+            if needle in str(lib.get("Name") or "").casefold()
+        ]
+
+    def invalidate_catalog(self) -> None:
+        delete_json(self._catalog_key())