aioaudiobookshelf 0.1.0__py3-none-any.whl

aioaudiobookshelf/client/libraries.py

@@ -0,0 +1,173 @@
+"""Calls to /api/libraries."""
+
+from collections.abc import AsyncGenerator
+from typing import TypeVar
+
+from mashumaro.mixins.json import DataClassJSONMixin
+
+from aioaudiobookshelf.client._base import BaseClient
+from aioaudiobookshelf.schema.author import AuthorExpanded, Narrator
+from aioaudiobookshelf.schema.calls_library import (
+    AllLibrariesResponse,
+    LibraryAuthorsResponse,
+    LibraryCollectionsMinifiedResponse,
+    LibraryItemsMinifiedResponse,
+    LibraryNarratorsResponse,
+    LibraryPlaylistsResponse,
+    LibrarySeriesMinifiedResponse,
+    LibraryWithFilterDataResponse,
+)
+from aioaudiobookshelf.schema.library import Library, LibraryFilterData
+
+ResponseMinified = TypeVar("ResponseMinified", bound=DataClassJSONMixin)
+ResponseNormal = TypeVar("ResponseNormal", bound=DataClassJSONMixin)
+
+
+class LibrariesClient(BaseClient):
+    """LibrariesClient."""
+
+    # create library
+
+    async def get_all_libraries(self) -> list[Library]:
+        """Get all user accessible libraries."""
+        response = await self._get("/api/libraries")
+        return AllLibrariesResponse.from_json(response).libraries
+
+    async def get_library(self, *, library_id: str) -> Library:
+        """Get single library."""
+        response = await self._get(f"/api/libraries/{library_id}")
+        return Library.from_json(response)
+
+    async def get_library_with_filterdata(
+        self, *, library_id: str
+    ) -> LibraryWithFilterDataResponse:
+        """Get single library including filterdata."""
+        response = await self._get(f"/api/libraries/{library_id}?include=filterdata")
+        return LibraryWithFilterDataResponse.from_json(response)
+
+    # update library
+    # delete library
+
+    async def _get_library_with_pagination(
+        self,
+        *,
+        endpoint: str,
+        minified: bool = False,
+        response_cls_minified: type[ResponseMinified],
+        response_cls: type[ResponseNormal],
+        filter_str: str | None = None,
+    ) -> AsyncGenerator[ResponseMinified | ResponseNormal]:
+        page_cnt = 0
+        params: dict[str, int | str] = {
+            "minified": int(minified),
+            "limit": self.session_config.pagination_items_per_page,
+        }
+        if filter_str is not None:
+            params["filter"] = filter_str
+        while True:
+            params["page"] = page_cnt
+            response = await self._get(endpoint, params)
+            page_cnt += 1
+            if minified:
+                yield response_cls_minified.from_json(response)
+            else:
+                yield response_cls.from_json(response)
+
+    async def get_library_items(
+        self, *, library_id: str, filter_str: str | None = None
+    ) -> AsyncGenerator[LibraryItemsMinifiedResponse]:
+        """Get library items.
+
+        Returns only minified items at this point.
+        """
+        # only minified response is supported at API
+        minified: bool = True
+        endpoint = f"/api/libraries/{library_id}/items"
+        async for result in self._get_library_with_pagination(
+            endpoint=endpoint,
+            minified=minified,
+            response_cls_minified=LibraryItemsMinifiedResponse,
+            response_cls=LibraryItemsMinifiedResponse,
+            filter_str=filter_str,
+        ):
+            yield result
+
+    # remove item with issues
+    # get lib podcast episode downloads
+
+    async def get_library_series(
+        self, *, library_id: str
+    ) -> AsyncGenerator[LibrarySeriesMinifiedResponse]:
+        """Get series in that library.
+
+        Returns only minified items at this point.
+        """
+        # only minified response is supported
+        minified: bool = True
+        endpoint = f"/api/libraries/{library_id}/series"
+        async for result in self._get_library_with_pagination(
+            endpoint=endpoint,
+            minified=minified,
+            response_cls=LibrarySeriesMinifiedResponse,
+            response_cls_minified=LibrarySeriesMinifiedResponse,
+        ):
+            yield result
+
+    async def get_library_collections(
+        self, *, library_id: str
+    ) -> AsyncGenerator[LibraryCollectionsMinifiedResponse]:
+        """Get collections in that library.
+
+        Returns only minified items at this point.
+        """
+        # only minified response is supported
+        minified: bool = True
+        endpoint = f"/api/libraries/{library_id}/collections"
+        async for result in self._get_library_with_pagination(
+            endpoint=endpoint,
+            minified=minified,
+            response_cls=LibraryCollectionsMinifiedResponse,
+            response_cls_minified=LibraryCollectionsMinifiedResponse,
+        ):
+            yield result
+
+    async def get_library_playlists(
+        self, *, library_id: str
+    ) -> AsyncGenerator[LibraryPlaylistsResponse]:
+        """Get collections in that library.
+
+        Returns only minified items at this point.
+        """
+        endpoint = f"/api/libraries/{library_id}/playlists"
+        async for result in self._get_library_with_pagination(
+            endpoint=endpoint,
+            minified=False,  # there is no minified version
+            response_cls=LibraryPlaylistsResponse,
+            response_cls_minified=LibraryPlaylistsResponse,
+        ):
+            yield result
+
+    # get library's personalized view
+
+    async def get_library_filterdata(self, *, library_id: str) -> LibraryFilterData:
+        """Get filterdata of library."""
+        response = await self._get(endpoint=f"/api/libraries/{library_id}/filterdata")
+        return LibraryFilterData.from_json(response)
+
+    # search library
+    # get lib stats
+
+    async def get_library_authors(self, *, library_id: str) -> list[AuthorExpanded]:
+        """Get authors of library."""
+        response = await self._get(endpoint=f"/api/libraries/{library_id}/authors")
+        return LibraryAuthorsResponse.from_json(response).authors
+
+    async def get_library_narrators(self, *, library_id: str) -> list[Narrator]:
+        """Get narrators of a library."""
+        response = await self._get(endpoint=f"/api/libraries/{library_id}/narrators")
+        return LibraryNarratorsResponse.from_json(response).narrators
+
+    # match lib items
+    # scan lib folders
+    # library recent episodes
+    # reorder list

aioaudiobookshelf/client/me.py

@@ -0,0 +1,103 @@
+"""Calls to /api/me."""
+
+from collections.abc import AsyncGenerator
+
+from aioaudiobookshelf.client._base import BaseClient
+from aioaudiobookshelf.schema.calls_me import (
+    MeListeningSessionsParameters,
+    MeListeningSessionsResponse,
+)
+from aioaudiobookshelf.schema.media_progress import MediaProgress
+from aioaudiobookshelf.schema.user import User
+
+
+class MeClient(BaseClient):
+    """MeClient."""
+
+    async def get_my_user(self) -> User:
+        """Get this client's user."""
+        data = await self._get("/api/me")
+        return User.from_json(data)
+
+    async def get_my_listening_sessions(self) -> AsyncGenerator[MeListeningSessionsResponse]:
+        """Get this user's listening sessions."""
+        raise NotImplementedError("PodcastMetadata not fully returned.")
+        page_cnt = 0
+        params = MeListeningSessionsParameters(
+            items_per_page=self.session_config.pagination_items_per_page, page=page_cnt
+        )
+        while True:
+            params.page = page_cnt
+            response = await self._get("/api/me/listening-sessions", params.to_dict())
+            page_cnt += 1
+            yield MeListeningSessionsResponse.from_json(response)
+
+    # listening stats
+    # remove item from continue listening
+
+    async def get_my_media_progress(
+        self, *, item_id: str, episode_id: str | None = None
+    ) -> MediaProgress | None:
+        """Get a MediaProgress, returns None if none found."""
+        endpoint = f"/api/me/progress/{item_id}"
+        if episode_id is not None:
+            endpoint += f"/{episode_id}"
+        response = await self._get(endpoint=endpoint)
+        if not response:
+            return None
+        return MediaProgress.from_json(response)
+
+    # batch create/ update media progress
+
+    async def update_my_media_progress(
+        self,
+        *,
+        item_id: str,
+        episode_id: str | None = None,
+        duration_seconds: float,
+        progress_seconds: float,
+        is_finished: bool,
+    ) -> None:
+        """Update progress of media item.
+
+        0 <= progress_percent <= 1
+
+        Notes:
+            - progress in abs is percentage
+            - multiple parameters in one call don't work in all combinations
+            - currentTime is current position in s
+            - currentTime works only if duration is sent as well, but then don't
+              send progress at the same time.
+        """
+        logger_item = "audiobook" if not episode_id else "podcast"
+        endpoint = f"/api/me/progress/{item_id}"
+        if episode_id is not None:
+            endpoint += f"/{episode_id}"
+        await self._patch(
+            endpoint,
+            data={"isFinished": is_finished},
+        )
+        if is_finished:
+            self.logger.debug("Marked %s, id %s finished.", logger_item, item_id)
+            return
+        percentage = progress_seconds / duration_seconds
+        await self._patch(
+            endpoint,
+            data={"progress": percentage},
+        )
+        await self._patch(
+            endpoint,
+            data={"duration": duration_seconds, "currentTime": progress_seconds},
+        )
+        self.logger.debug(
+            "Updated progress of %s, id %s to %.2f%%.", logger_item, item_id, percentage * 100
+        )
+
+    async def remove_my_media_progress(self, *, media_progress_id: str) -> None:
+        """Remove a single media progress."""
+        await self._delete(f"/api/me/progress/{media_progress_id}")
+
+    # create, update, remove bookmark
+    # change password
+    # get lib items in progress
+    # remove series from continue listening

aioaudiobookshelf/client/playlists.py

@@ -0,0 +1,29 @@
+"""Calls to /api/playlists."""
+
+from aioaudiobookshelf.schema.calls_playlists import AllPlaylistsResponse
+from aioaudiobookshelf.schema.playlist import PlaylistExpanded
+
+from ._base import BaseClient
+
+
+class PlaylistsClient(BaseClient):
+    """PlaylistsClient."""
+
+    # create playlist
+
+    async def get_all_playlists(self) -> list[PlaylistExpanded]:
+        """Get all playlists accessible to user."""
+        data = await self._get(endpoint="/api/playlists")
+        return AllPlaylistsResponse.from_json(data).playlists
+
+    async def get_playlist(self, *, playlist_id: str) -> PlaylistExpanded:
+        """Get a playlist."""
+        data = await self._get(endpoint=f"/api/playlists/{playlist_id}")
+        return PlaylistExpanded.from_json(data)
+
+    # update
+    # delete
+    # add item
+    # remove item
+    # batch add + remove
+    # create playlist from collection

aioaudiobookshelf/client/podcasts.py

@@ -0,0 +1,22 @@
+"""Calls to /api/podcasts."""
+
+from aioaudiobookshelf.client._base import BaseClient
+from aioaudiobookshelf.schema.podcast import PodcastEpisode
+
+
+class PodcastsClient(BaseClient):
+    """PodcastClient."""
+
+    # create podcast
+    # get podcast feed
+    # feed from opml
+    # check for new episodes
+    # get podcast episode downloads
+    # search podcast feed
+    # download podcast episodes
+    # match podcast episode
+
+    async def get_podcast_episode(self, *, podcast_id: str, episode_id: str) -> PodcastEpisode:
+        """Get podcast episode."""
+        data = await self._get(f"/api/podcasts/{podcast_id}/episode/{episode_id}")
+        return PodcastEpisode.from_json(data)

aioaudiobookshelf/client/series.py

@@ -0,0 +1,27 @@
+"""Calls to /api/series."""
+
+from aioaudiobookshelf.client._base import BaseClient
+from aioaudiobookshelf.schema.calls_series import SeriesWithProgress
+from aioaudiobookshelf.schema.series import Series
+
+
+class SeriesClient(BaseClient):
+    """SeriesClient."""
+
+    async def get_series(
+        self, *, series_id: str, include_progress: bool = False
+    ) -> Series | SeriesWithProgress:
+        """Get an author.
+
+        Include series always includes items.
+        """
+        response_cls: type[Series | SeriesWithProgress] = Series
+        endpoint = f"/api/series/{series_id}"
+        if include_progress:
+            endpoint += "?include=progress"
+            response_cls = SeriesWithProgress
+
+        response = await self._get(endpoint)
+        return response_cls.from_json(response)
+
+    # update series

aioaudiobookshelf/client/session.py

@@ -0,0 +1,35 @@
+"""Calls to /api/session."""
+
+from aioaudiobookshelf.client._base import BaseClient
+from aioaudiobookshelf.schema.calls_session import CloseOpenSessionsParameters
+from aioaudiobookshelf.schema.session import PlaybackSessionExpanded
+
+
+class SessionClient(BaseClient):
+    """SessionClient."""
+
+    # get_all_session # admin
+    # delete session
+    # sync local session(s)
+
+    async def get_open_session(self, *, session_id: str) -> PlaybackSessionExpanded:
+        """Get open session."""
+        response = await self._get(f"/api/session/{session_id}")
+        psession = PlaybackSessionExpanded.from_json(response)
+        self.logger.debug(
+            "Got playback session %s for %s named %s.",
+            psession.id_,
+            psession.media_type,
+            psession.display_title,
+        )
+        return psession
+
+    # sync open session
+
+    async def close_open_session(
+        self, *, session_id: str, parameters: CloseOpenSessionsParameters | None = None
+    ) -> None:
+        """Close open session."""
+        _parameters = {} if parameters is None else parameters.to_dict()
+        self.logger.debug("Closing playback session %s.", session_id)
+        await self._post(f"/api/session/{session_id}/close", data=_parameters)

aioaudiobookshelf/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions for aioaudiobookshelf."""
+
+
+class BadUserError(Exception):
+    """Raised if this user is not suitable for the client."""
+
+
+class LoginError(Exception):
+    """Exception raised if login failed."""
+
+
+class ApiError(Exception):
+    """Exception raised if call to api failed."""

aioaudiobookshelf/helpers.py

@@ -0,0 +1,56 @@
+"""Helpers for aioaudiobookshelf."""
+
+import base64
+import urllib.parse
+from enum import StrEnum
+
+
+class FilterGroup(StrEnum):
+    """FilterGroup."""
+
+    GENRES = "genres"
+    TAGS = "tags"
+    SERIES = "series"
+    AUTHORS = "authors"
+    PROGRESS = "progress"
+    NARRATORS = "narrators"
+    MISSING = "missing"
+    LANGUAGES = "languages"
+    TRACKS = "tracks"
+
+
+class FilterProgressType(StrEnum):
+    """FilterProgressType."""
+
+    FINISHED = "finished"
+    NOTSTARTED = "not-started"
+    NOTFINISHED = "not-finished"
+    INPROGRESS = "in-progress"
+
+
+def get_library_filter_string(
+    *, filter_group: FilterGroup, filter_value: str | FilterProgressType
+) -> str:
+    """Obtain a string usable as filter_str.
+
+    Currently only narrators, genre, tags, languages and progress.
+    """
+    if filter_group in [
+        FilterGroup.NARRATORS,
+        FilterGroup.GENRES,
+        FilterGroup.TAGS,
+        FilterGroup.LANGUAGES,
+    ]:
+        _encoded = urllib.parse.quote(base64.b64encode(filter_value.encode()))
+        return f"{filter_group.value}.{_encoded}"
+
+    if filter_group == FilterGroup.PROGRESS:
+        if filter_value not in FilterProgressType:
+            raise RuntimeError("Filter value not acceptable for progress.")
+        filter_value = (
+            filter_value.value if isinstance(filter_value, FilterProgressType) else filter_value
+        )
+        _encoded = urllib.parse.quote(base64.b64encode(filter_value.encode()))
+        return f"{filter_group.value}.{_encoded}"
+
+    raise NotImplementedError(f"The {filter_group=} is not yet implemented.")

aioaudiobookshelf/schema/__init__.py

@@ -0,0 +1,14 @@
+"""Schema for Audiobookshelf (abs)."""
+
+from mashumaro.config import BaseConfig
+from mashumaro.mixins.json import DataClassJSONMixin
+
+
+class _BaseModel(DataClassJSONMixin):
+    """Model shared between schema definitions."""
+
+    class Config(BaseConfig):
+        """Base configuration."""
+
+        forbid_extra_keys = False
+        serialize_by_alias = True

aioaudiobookshelf/schema/audio.py

@@ -0,0 +1,71 @@
+"""Schema for audio."""
+
+from dataclasses import dataclass
+from typing import Annotated
+
+from mashumaro.types import Alias
+
+from . import _BaseModel
+from .file import FileMetadata
+
+
+@dataclass(kw_only=True)
+class AudioBookmark(_BaseModel):
+    """AudioBookmark. No variants.
+
+    https://api.audiobookshelf.org/#audio-bookmark
+    """
+
+    library_item_id: Annotated[str, Alias("libraryItemId")]
+    title: str
+    time: int  # seconds
+    created_at: Annotated[int, Alias("createdAt")]  # unix epoch ms
+
+
+@dataclass(kw_only=True)
+class AudioTrack(_BaseModel):
+    """ABS audioTrack. No variants.
+
+    https://api.audiobookshelf.org/#audio-track
+    """
+
+    index: int | None
+    start_offset: Annotated[float, Alias("startOffset")]
+    duration: float
+    title: str
+    content_url: Annotated[str, Alias("contentUrl")]
+    metadata: FileMetadata | None
+    # is missing if part of library...
+    mime_type: str | None = None
+
+
+@dataclass(kw_only=True)
+class AudioFile(_BaseModel):
+    """Audiofile."""
+
+    index: int
+    ino: str
+    metadata: FileMetadata
+    added_at: Annotated[int, Alias("addedAt")]
+    updated_at: Annotated[int, Alias("updatedAt")]
+    track_num_from_meta: Annotated[int | None, Alias("trackNumFromMeta")] = None
+    disc_num_from_meta: Annotated[int | None, Alias("discNumFromMeta")] = None
+    track_num_from_filename: Annotated[int | None, Alias("trackNumFromFilename")] = None
+    disc_num_from_filename: Annotated[int | None, Alias("discNumFromFilename")] = None
+    manually_verified: Annotated[bool, Alias("manuallyVerified")]
+    exclude: bool
+    error: str | None = None
+    format: str
+    duration: float
+    bit_rate: Annotated[int, Alias("bitRate")]
+    language: str | None = None
+    codec: str
+    time_base: Annotated[str, Alias("timeBase")]
+    channels: int
+    channel_layout: Annotated[str, Alias("channelLayout")]
+    embedded_cover_art: Annotated[str | None, Alias("embeddedCoverArt")] = None
+    mime_type: Annotated[str, Alias("mimeType")]
+    # if part of a book
+    # chapters: list[BookChapter]
+    # id3 tags:
+    # meta_tags: AudioMetaTags

aioaudiobookshelf/schema/author.py

@@ -0,0 +1,46 @@
+"""Schema for Author."""
+
+from dataclasses import dataclass
+from typing import Annotated
+
+from mashumaro.types import Alias
+
+from . import _BaseModel
+
+
+@dataclass(kw_only=True)
+class AuthorMinified(_BaseModel):
+    """AuthorMinified.
+
+    https://api.audiobookshelf.org/#author
+    """
+
+    id_: Annotated[str, Alias("id")]
+    name: str
+
+
+@dataclass(kw_only=True)
+class Author(AuthorMinified):
+    """Author."""
+
+    asin: str | None = None
+    description: str | None = None
+    image_path: Annotated[str | None, Alias("imagePath")] = None
+    added_at: Annotated[int, Alias("addedAt")]  # ms epoch
+    updated_at: Annotated[int, Alias("updatedAt")]  # ms epoch
+
+
+@dataclass(kw_only=True)
+class AuthorExpanded(Author):
+    """ABSAuthorExpanded."""
+
+    num_books: Annotated[int, Alias("numBooks")]
+
+
+@dataclass(kw_only=True)
+class Narrator(_BaseModel):
+    """Narrator."""
+
+    id_: Annotated[str, Alias("id")]
+    name: str
+    num_books: Annotated[int, Alias("numBooks")]