gukebox 1.10.0.dev1__tar.gz → 1.10.0.dev2__tar.gz

{gukebox-1.10.0.dev1 → gukebox-1.10.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gukebox
-Version: 1.10.0.dev1
+Version: 1.10.0.dev2
 Summary: A Jukebox to play music on speakers using 'CD' with NFC tag
 Keywords: jukebox,music,nfc
 Author: Gudsfile
@@ -59,7 +59,7 @@ Pick an album, place it on the reader, and the music starts playing. Remove it,
 
 [![gukebox last version](https://img.shields.io/pypi/v/gukebox.svg?logo=pypi)](https://pypi.python.org/pypi/gukebox)
 [![license](https://img.shields.io/pypi/l/gukebox.svg)](https://pypi.python.org/pypi/gukebox)
-[![actions status](https://github.com/gudsfile/jukebox/actions/workflows/python.yml/badge.svg)](https://github.com/gudsfile/jukebox/actions)
+[![actions status](https://github.com/gudsfile/jukebox/actions/workflows/ci.yml/badge.svg)](https://github.com/gudsfile/jukebox/actions)
 
 ![rpi](https://img.shields.io/badge/-Zero%202W%20%7C%203%20%7C%205-C51A4A?logo=raspberry-pi&label=RPi&logoColor=C51A4A&labcolor=C51A4A)
 [![python versions](https://img.shields.io/pypi/pyversions/gukebox.svg?logo=python)](https://pypi.python.org/pypi/gukebox) [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

{gukebox-1.10.0.dev1 → gukebox-1.10.0.dev2}/README.md

@@ -8,7 +8,7 @@ Pick an album, place it on the reader, and the music starts playing. Remove it,
 
 [![gukebox last version](https://img.shields.io/pypi/v/gukebox.svg?logo=pypi)](https://pypi.python.org/pypi/gukebox)
 [![license](https://img.shields.io/pypi/l/gukebox.svg)](https://pypi.python.org/pypi/gukebox)
-[![actions status](https://github.com/gudsfile/jukebox/actions/workflows/python.yml/badge.svg)](https://github.com/gudsfile/jukebox/actions)
+[![actions status](https://github.com/gudsfile/jukebox/actions/workflows/ci.yml/badge.svg)](https://github.com/gudsfile/jukebox/actions)
 
 ![rpi](https://img.shields.io/badge/-Zero%202W%20%7C%203%20%7C%205-C51A4A?logo=raspberry-pi&label=RPi&logoColor=C51A4A&labcolor=C51A4A)
 [![python versions](https://img.shields.io/pypi/pyversions/gukebox.svg?logo=python)](https://pypi.python.org/pypi/gukebox) [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

gukebox-1.10.0.dev2/jukebox/adapters/inbound/admin/api/backup_archive.py

@@ -0,0 +1,53 @@
+import io
+import zipfile
+
+LIBRARY_ENTRY = "library.json"
+SETTINGS_ENTRY = "settings.json"
+EXPECTED_ENTRIES = (LIBRARY_ENTRY, SETTINGS_ENTRY)
+# Both files are small JSON documents: refuse anything bigger before decompressing it.
+MAX_ENTRY_SIZE_BYTES = 10 * 1024 * 1024
+
+
+class InvalidBackupArchiveError(ValueError):
+    """Raised when an uploaded backup archive does not hold exactly the expected files."""
+
+
+def build_backup_archive(library: bytes, settings: bytes) -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr(LIBRARY_ENTRY, library)
+        archive.writestr(SETTINGS_ENTRY, settings)
+    return buffer.getvalue()
+
+
+def read_backup_archive(content: bytes) -> tuple[bytes, bytes]:
+    """Return the library and settings files of a backup archive, as stored in it."""
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(content))
+    except zipfile.BadZipFile as err:
+        raise InvalidBackupArchiveError("The file is not a zip archive.") from err
+
+    with archive:
+        names = archive.namelist()
+        missing = [name for name in EXPECTED_ENTRIES if name not in names]
+        extra = sorted({name for name in names if name not in EXPECTED_ENTRIES})
+        if missing or extra or len(names) != len(EXPECTED_ENTRIES):
+            problems = []
+            if missing:
+                problems.append(f"missing {', '.join(missing)}")
+            if extra:
+                problems.append(f"unexpected {', '.join(extra)}")
+            if not problems:
+                problems.append("duplicated entries")
+            raise InvalidBackupArchiveError(
+                f"The archive must hold exactly {LIBRARY_ENTRY} and {SETTINGS_ENTRY}: {'; '.join(problems)}."
+            )
+
+        for name in EXPECTED_ENTRIES:
+            if archive.getinfo(name).file_size > MAX_ENTRY_SIZE_BYTES:
+                raise InvalidBackupArchiveError(f"{name} is too large.")
+
+        try:
+            return archive.read(LIBRARY_ENTRY), archive.read(SETTINGS_ENTRY)
+        except (zipfile.BadZipFile, OSError) as err:
+            raise InvalidBackupArchiveError(f"The archive is corrupted: {err}") from err

gukebox-1.10.0.dev2/jukebox/adapters/inbound/admin/api/export_router.py

@@ -0,0 +1,57 @@
+import json
+import os
+from collections.abc import Callable
+from datetime import date
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse, Response
+
+from jukebox.adapters.inbound.admin.api.backup_archive import build_backup_archive
+from jukebox.domain.entities import Library
+from jukebox.settings.migration import CURRENT_SETTINGS_SCHEMA_VERSION
+
+# A missing file is a normal state (settings never changed, no disc yet): the archive holds what the app reads then.
+DEFAULT_LIBRARY = json.dumps(Library().model_dump(), indent=2).encode()
+DEFAULT_SETTINGS = json.dumps({"schema_version": CURRENT_SETTINGS_SCHEMA_VERSION}, indent=2).encode()
+
+
+def _file_download(path: str, filename: str, missing_detail: str) -> FileResponse:
+    # Serve the bytes as stored on disk: a backup must not be rebuilt from parsed (or migrated) data.
+    if not os.path.isfile(path):
+        raise HTTPException(status_code=404, detail=missing_detail)
+    return FileResponse(path, media_type="application/json", filename=filename)
+
+
+def _read_file(path: str, default: bytes) -> bytes:
+    try:
+        with open(path, "rb") as file_obj:
+            return file_obj.read()
+    except FileNotFoundError:
+        return default
+
+
+def build_export_router(library_path: str, settings_path: str, today: Callable[[], date] = date.today) -> APIRouter:
+    router = APIRouter(prefix="/api/v1/export", tags=["export"])
+
+    @router.get("/library", summary="Download the library file")
+    def export_library() -> FileResponse:
+        return _file_download(library_path, f"library-{today().isoformat()}.json", "No library file to export.")
+
+    @router.get("/settings", summary="Download the persisted settings file")
+    def export_settings() -> FileResponse:
+        return _file_download(
+            settings_path, f"settings-{today().isoformat()}.json", "No persisted settings file to export."
+        )
+
+    @router.get("/all", summary="Download the library and the persisted settings files as one zip archive")
+    def export_all() -> Response:
+        archive = build_backup_archive(
+            _read_file(library_path, DEFAULT_LIBRARY),
+            _read_file(settings_path, DEFAULT_SETTINGS),
+        )
+        filename = f"jukebox-backup-{today().isoformat()}.zip"
+        return Response(
+            archive, media_type="application/zip", headers={"Content-Disposition": f'attachment; filename="{filename}"'}
+        )
+
+    return router

gukebox-1.10.0.dev2/jukebox/adapters/inbound/admin/api/import_router.py

@@ -0,0 +1,200 @@
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from jukebox.adapters.inbound.admin.api.backup_archive import (
+    LIBRARY_ENTRY,
+    SETTINGS_ENTRY,
+    InvalidBackupArchiveError,
+    read_backup_archive,
+)
+from jukebox.domain.entities import Disc, Library, LibraryImportSummary
+from jukebox.domain.repositories import LibraryRepository
+from jukebox.domain.use_cases import ImportLibrary, PreviewLibraryImport
+from jukebox.settings.errors import SettingsError
+from jukebox.settings.service_protocols import SettingsService
+from jukebox.settings.types import JsonObject, JsonValue
+
+LOGGER = logging.getLogger("jukebox")
+
+# The body is the uploaded file itself, read raw so that a file that is not JSON gets a clear 400.
+_FILE_BODY: dict[str, Any] = {
+    "requestBody": {"required": True, "content": {"application/json": {"schema": {"type": "object"}}}}
+}
+_ARCHIVE_BODY: dict[str, Any] = {
+    "requestBody": {
+        "required": True,
+        "content": {"application/zip": {"schema": {"type": "string", "format": "binary"}}},
+    }
+}
+
+
+class _LibraryFile(BaseModel):
+    """An uploaded library file: unlike a stored library, it must hold `discs` and nothing else.
+
+    This keeps a settings file, picked by mistake, from replacing the library with an empty one.
+    """
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+    discs: dict[str, Disc]
+
+
+def _parse_json(content: bytes, source: str = "") -> JsonValue:
+    try:
+        return json.loads(content)
+    except (UnicodeDecodeError, json.JSONDecodeError) as err:
+        raise HTTPException(status_code=400, detail=f"{source}The file is not valid JSON: {err}")
+
+
+def _parse_library(content: bytes, source: str = "") -> Library:
+    try:
+        return Library(discs=_LibraryFile.model_validate(_parse_json(content, source)).discs)
+    except ValidationError as err:
+        raise HTTPException(status_code=400, detail=f"{source}Invalid library file: {err}")
+
+
+async def _read_library_file(request: Request) -> Library:
+    return _parse_library(await request.body())
+
+
+def build_import_router(
+    library_repository: LibraryRepository,
+    preview_library_import: PreviewLibraryImport,
+    import_library: ImportLibrary,
+    settings_service: SettingsService,
+) -> APIRouter:
+    router = APIRouter(prefix="/api/v1/import", tags=["import"])
+
+    @router.post(
+        "/library/preview",
+        response_model=LibraryImportSummary,
+        summary="Validate a library file and summarize what importing it would change",
+        openapi_extra=_FILE_BODY,
+    )
+    async def preview_library(request: Request) -> LibraryImportSummary:
+        library = await _read_library_file(request)
+        try:
+            return preview_library_import.execute(library)
+        except Exception as err:
+            raise HTTPException(status_code=500, detail=f"Server error: {err!s}")
+
+    @router.post(
+        "/library",
+        response_model=LibraryImportSummary,
+        summary="Replace the library with a library file",
+        openapi_extra=_FILE_BODY,
+    )
+    async def import_library_file(request: Request) -> LibraryImportSummary:
+        library = await _read_library_file(request)
+        try:
+            summary = preview_library_import.execute(library)
+            import_library.execute(library)
+            return summary
+        except Exception as err:
+            raise HTTPException(status_code=500, detail=f"Server error: {err!s}")
+
+    @router.post(
+        "/settings/preview",
+        response_model=dict[str, Any],
+        summary="Validate a settings file and list the settings importing it would change",
+        openapi_extra=_FILE_BODY,
+    )
+    async def preview_settings(request: Request) -> JsonObject:
+        raw_data = _parse_json(await request.body())
+        try:
+            return settings_service.preview_settings_import(raw_data)
+        except SettingsError as err:
+            raise HTTPException(status_code=400, detail=str(err))
+        except Exception as err:
+            raise HTTPException(status_code=500, detail=f"Server error: {err!s}")
+
+    @router.post(
+        "/settings",
+        response_model=dict[str, Any],
+        summary="Replace the persisted settings with a settings file",
+        openapi_extra=_FILE_BODY,
+    )
+    async def import_settings(request: Request) -> JsonObject:
+        raw_data = _parse_json(await request.body())
+        try:
+            return settings_service.import_persisted_settings(raw_data)
+        except SettingsError as err:
+            raise HTTPException(status_code=400, detail=str(err))
+        except Exception as err:
+            raise HTTPException(status_code=500, detail=f"Server error: {err!s}")
+
+    async def read_archive(request: Request) -> tuple[Library, JsonValue]:
+        try:
+            library_content, settings_content = read_backup_archive(await request.body())
+        except InvalidBackupArchiveError as err:
+            raise HTTPException(status_code=400, detail=str(err))
+        library = _parse_library(library_content, f"{LIBRARY_ENTRY}: ")
+        settings_data = _parse_json(settings_content, f"{SETTINGS_ENTRY}: ")
+        return library, settings_data
+
+    def preview_archive(library: Library, settings_data: JsonValue) -> JsonObject:
+        try:
+            settings_summary = settings_service.preview_settings_import(settings_data)
+        except SettingsError as err:
+            raise HTTPException(status_code=400, detail=f"{SETTINGS_ENTRY}: {err}")
+        return {
+            "library": preview_library_import.execute(library).model_dump(mode="json"),
+            "settings": settings_summary,
+        }
+
+    @router.post(
+        "/all/preview",
+        response_model=dict[str, Any],
+        summary="Validate a backup archive and summarize what importing it would change",
+        openapi_extra=_ARCHIVE_BODY,
+    )
+    async def preview_all(request: Request) -> JsonObject:
+        library, settings_data = await read_archive(request)
+        try:
+            return preview_archive(library, settings_data)
+        except HTTPException:
+            raise
+        except Exception as err:
+            raise HTTPException(status_code=500, detail=f"Server error: {err!s}")
+
+    @router.post(
+        "/all",
+        response_model=dict[str, Any],
+        summary="Replace the library and the persisted settings with a backup archive",
+        openapi_extra=_ARCHIVE_BODY,
+    )
+    async def import_all(request: Request) -> JsonObject:
+        library, settings_data = await read_archive(request)
+        try:
+            # Validate both files before writing any of them.
+            summary = preview_archive(library, settings_data)
+            # Write both files or none: keep the library file as is, even corrupted, to put it back.
+            previous_library = library_repository.snapshot()
+            import_library.execute(library)
+            try:
+                summary["settings"] = settings_service.import_persisted_settings(settings_data)
+            except Exception as err:
+                try:
+                    library_repository.restore(previous_library)
+                except Exception as rollback_err:
+                    LOGGER.exception("Could not put the previous library back")
+                    raise HTTPException(
+                        status_code=500,
+                        detail=(
+                            f"The library was replaced but the settings were not: {err!s}. "
+                            f"Putting the previous library back failed: {rollback_err!s}"
+                        ),
+                    )
+                raise
+            return summary
+        except HTTPException:
+            raise
+        except SettingsError as err:
+            raise HTTPException(status_code=400, detail=f"{SETTINGS_ENTRY}: {err}")
+        except Exception as err:
+            raise HTTPException(status_code=500, detail=f"Server error: {err!s}")
+
+    return router

{gukebox-1.10.0.dev1 → gukebox-1.10.0.dev2}/jukebox/adapters/inbound/admin/api_controller.py

@@ -6,6 +6,7 @@ try:
     from jukebox.adapters.inbound.admin.api.current_tag_router import build_current_tag_router
     from jukebox.adapters.inbound.admin.api.discs_router import build_discs_router
     from jukebox.adapters.inbound.admin.api.export_router import build_export_router
+    from jukebox.adapters.inbound.admin.api.import_router import build_import_router
     from jukebox.adapters.inbound.admin.api.models import (
         CurrentTagDiscOutput,
         CurrentTagStatusOutput,
@@ -23,7 +24,17 @@ except ModuleNotFoundError as e:
     if e.name != "fastapi":
         raise
     raise MissingOptionalDependencyError("The `api_controller` module", "api", "jukebox-admin api") from e
-from jukebox.domain.use_cases import AddDisc, EditDisc, GetCurrentTagStatus, GetDisc, ListDiscs, RemoveDisc
+from jukebox.domain.repositories import LibraryRepository
+from jukebox.domain.use_cases import (
+    AddDisc,
+    EditDisc,
+    GetCurrentTagStatus,
+    GetDisc,
+    ImportLibrary,
+    ListDiscs,
+    PreviewLibraryImport,
+    RemoveDisc,
+)
 from jukebox.settings.service_protocols import SettingsService
 from jukebox.sonos.service import SonosService
 
@@ -53,6 +64,9 @@ class APIController:
         sonos_service: SonosService,
         library_path: str,
         settings_path: str,
+        preview_library_import: PreviewLibraryImport,
+        import_library: ImportLibrary,
+        library_repository: LibraryRepository,
     ):
         self.add_disc = add_disc
         self.list_discs = list_discs
@@ -64,6 +78,9 @@ class APIController:
         self.sonos_service = sonos_service
         self.library_path = library_path
         self.settings_path = settings_path
+        self.preview_library_import = preview_library_import
+        self.import_library = import_library
+        self.library_repository = library_repository
         self.app = FastAPI(
             title="Jukebox Admin API",
             description="API for managing Jukebox disc library and settings",
@@ -97,3 +114,8 @@ class APIController:
         )
         self.app.include_router(build_pn532_router(self.settings_service))
         self.app.include_router(build_export_router(self.library_path, self.settings_path))
+        self.app.include_router(
+            build_import_router(
+                self.library_repository, self.preview_library_import, self.import_library, self.settings_service
+            )
+        )

{gukebox-1.10.0.dev1 → gukebox-1.10.0.dev2}/jukebox/adapters/inbound/admin/interactive_cli_controller.py

@@ -1,4 +1,4 @@
-from typing import Literal, overload
+from typing import Literal
 
 import typer
 
@@ -69,7 +69,9 @@ class InteractiveCLIController:
         current_tag_status = self.get_current_tag_status.execute()
         tag = self._prompt_for_tag(current_tag_status, action="add")
         uri = self._prompt_for_uri()
-        disc = Disc(uri=uri, metadata=DiscMetadata(), option=DiscOption())
+        metadata = self._prompt_for_metadata()
+        option = self._prompt_for_option()
+        disc = Disc(uri=uri, metadata=metadata, option=option)
         self.add_disc.execute(tag, disc)
         print("✅ Disc successfully added")
 
@@ -105,8 +107,11 @@ class InteractiveCLIController:
         print("\n-- Edit a disc --")
         current_tag_status = self.get_current_tag_status.execute()
         tag = self._prompt_for_tag(current_tag_status, action="edit")
-        uri = self._prompt_for_uri(required=False)
-        self.edit_disc.execute(tag, uri, DiscMetadata(), DiscOption())
+        current_disc = self.get_disc.execute(tag)
+        uri = self._prompt_for_uri(current_disc.uri)
+        metadata = self._prompt_for_metadata(current_disc.metadata)
+        option = self._prompt_for_option(current_disc.option)
+        self.edit_disc.execute(tag, uri, metadata, option)
         print("✅ Disc successfully edited")
 
     def get_disc_flow(self) -> None:
@@ -164,20 +169,32 @@ class InteractiveCLIController:
             raise ValueError("A tag ID is required.")
         return tag
 
-    @overload
-    def _prompt_for_uri(self, required: Literal[True] = True) -> str: ...
+    def _prompt_for_uri(self, current: str | None = None) -> str:
+        import questionary
 
-    @overload
-    def _prompt_for_uri(self, required: Literal[False]) -> str | None: ...
+        entered_uri = questionary.text("URI:", default=current or "").unsafe_ask()
+        uri = (entered_uri or "").strip() or current
+        if not uri:
+            raise ValueError("A URI is required.")
+        return uri
 
-    def _prompt_for_uri(self, required: bool = True) -> str | None:
+    def _prompt_for_metadata(self, current: DiscMetadata | None = None) -> DiscMetadata:
+        """Ask for each metadata field, prefilled with the current value; an empty answer means no value."""
         import questionary
 
-        label = "URI:" if required else "URI (leave empty to keep the current one):"
-        entered_uri = questionary.text(label).unsafe_ask()
-        uri = (entered_uri or "").strip()
-        if uri:
-            return uri
-        if required:
-            raise ValueError("A URI is required.")
-        return None
+        hint = " (optional)" if current is None else " (empty to clear)"
+        current = current or DiscMetadata()
+        values = {}
+        for field in ("artist", "album", "track", "playlist"):
+            entered = questionary.text(
+                f"{field.capitalize()}{hint}:", default=getattr(current, field) or ""
+            ).unsafe_ask()
+            values[field] = (entered or "").strip() or None
+        return DiscMetadata(**values)
+
+    def _prompt_for_option(self, current: DiscOption | None = None) -> DiscOption:
+        import questionary
+
+        current = current or DiscOption()
+        shuffle = questionary.confirm("Shuffle?", default=current.shuffle).unsafe_ask()
+        return DiscOption(shuffle=shuffle)