aioaudiobookshelf 0.1.2__tar.gz → 0.1.3__tar.gz

aioaudiobookshelf-0.1.3/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.2
+Name: aioaudiobookshelf
+Version: 0.1.3
+Summary: Async library for Audiobookshelf
+Author-email: Fabian Munkes <105975993+fmunkes@users.noreply.github.com>
+License: Apache-2.0
+Platform: any
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp
+Requires-Dist: mashumaro
+Requires-Dist: python-socketio>=5.12
+Provides-Extra: test
+Requires-Dist: codespell==2.3.0; extra == "test"
+Requires-Dist: isort==5.13.2; extra == "test"
+Requires-Dist: mypy==1.13.0; extra == "test"
+Requires-Dist: pre-commit==4.0.1; extra == "test"
+Requires-Dist: pre-commit-hooks==5.0.0; extra == "test"
+Requires-Dist: pytest==8.3.4; extra == "test"
+Requires-Dist: pytest-aiohttp==1.0.5; extra == "test"
+Requires-Dist: pytest-cov==5.0.0; extra == "test"
+Requires-Dist: syrupy==4.8.1; extra == "test"
+Requires-Dist: tomli==2.2.1; extra == "test"
+Requires-Dist: ruff==0.9.2; extra == "test"
+Requires-Dist: bumpver; extra == "test"
+
+# aioaudiobookshelf
+Async python library to interact with
+[Audiobookshelf](https://github.com/advplyr/audiobookshelf) (ABS).
+
+This lib's primary goal is to be used within the Audiobookshelf music provider
+in Music Assistant, but it can be used independently. Calls to endpoints not
+needed for the provider will be added over time.
+
+Not all endpoints are yet implemented.
+
+## Releases
+Releases can be found on [pypi](https://pypi.org/project/aioaudiobookshelf/),
+and are tagged.
+
+## Basic usage
+ABS has a rest api, documented
+[here](https://api.audiobookshelf.org) and additionally uses socket.io, see
+[here](https://api.audiobookshelf.org/#socket) for some event driven
+functionality.
+Accessibility to the endpoints is determined by the [user
+types](https://api.audiobookshelf.org/#user), which may be `root, admin, user, guest`.
+This lib is not tested with a `guest` user.
+
+As of `0.1.2` this lib has two different clients, the `UserClient` and the
+`SocketClient`. Admin endpoints are not yet implemented. The user client
+handles calls to the Rest API, the socket client allows to subscribe to certain
+events.
+
+To authenticate the socket client, you always need the user's token, username
+and password are not enough. The user client can be authenticated by username
+and password, which yields the token.
+
+Usage example:
+```python
+import asyncio
+import logging
+import os
+
+import aiohttp
+
+from aioaudiobookshelf import SessionConfiguration, get_user_client
+from aioaudiobookshelf.schema.library import LibraryItemMinifiedBook, LibraryItemMinifiedPodcast
+
+ABS_HOST = os.environ.get("ABS_HOST")
+ABS_USER = os.environ.get("ABS_USER")
+ABS_PASSWORD = os.environ.get("ABS_PASSWORD")
+
+
+async def abs_basics():
+    assert ABS_HOST is not None
+    assert ABS_USER is not None
+    assert ABS_PASSWORD is not None
+
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+    async with aiohttp.ClientSession() as session:
+        client = await get_user_client(
+            session_config=SessionConfiguration(
+                session=session, url=ABS_HOST, logger=logger, pagination_items_per_page=30
+            ),
+            username=ABS_USER,
+            password=ABS_PASSWORD,
+        )
+
+        # get libraries
+        libraries = await client.get_all_libraries()
+
+        # get library items
+        for library in libraries:
+            async for response in client.get_library_items(library_id=library.id_):
+                if not response.results:
+                    break
+                for lib_item_minified in response.results:
+                    if isinstance(lib_item_minified, LibraryItemMinifiedPodcast):
+                        ...
+                    if isinstance(lib_item_minified, LibraryItemMinifiedBook):
+                        ...
+
+        # get a single podcast
+        podcast_id = "dda96167-eaad-4012-83e1-149c6700d3e8"
+        podcast_expanded = client.get_library_item_podcast(podcast_id=podcast_id, expanded=True)
+
+
+asyncio.run(abs_basics())
+```
+
+Have a look into `aioaudiobookshelf/client/*.py` to see which endpoints are
+currently implemented. And the [provider
+implementation](https://github.com/music-assistant/server/blob/dev/music_assistant/providers/audiobookshelf/__init__.py) shows, how the lib can potentially be used.

aioaudiobookshelf-0.1.3/README.md

@@ -0,0 +1,90 @@
+# aioaudiobookshelf
+Async python library to interact with
+[Audiobookshelf](https://github.com/advplyr/audiobookshelf) (ABS).
+
+This lib's primary goal is to be used within the Audiobookshelf music provider
+in Music Assistant, but it can be used independently. Calls to endpoints not
+needed for the provider will be added over time.
+
+Not all endpoints are yet implemented.
+
+## Releases
+Releases can be found on [pypi](https://pypi.org/project/aioaudiobookshelf/),
+and are tagged.
+
+## Basic usage
+ABS has a rest api, documented
+[here](https://api.audiobookshelf.org) and additionally uses socket.io, see
+[here](https://api.audiobookshelf.org/#socket) for some event driven
+functionality.
+Accessibility to the endpoints is determined by the [user
+types](https://api.audiobookshelf.org/#user), which may be `root, admin, user, guest`.
+This lib is not tested with a `guest` user.
+
+As of `0.1.2` this lib has two different clients, the `UserClient` and the
+`SocketClient`. Admin endpoints are not yet implemented. The user client
+handles calls to the Rest API, the socket client allows to subscribe to certain
+events.
+
+To authenticate the socket client, you always need the user's token, username
+and password are not enough. The user client can be authenticated by username
+and password, which yields the token.
+
+Usage example:
+```python
+import asyncio
+import logging
+import os
+
+import aiohttp
+
+from aioaudiobookshelf import SessionConfiguration, get_user_client
+from aioaudiobookshelf.schema.library import LibraryItemMinifiedBook, LibraryItemMinifiedPodcast
+
+ABS_HOST = os.environ.get("ABS_HOST")
+ABS_USER = os.environ.get("ABS_USER")
+ABS_PASSWORD = os.environ.get("ABS_PASSWORD")
+
+
+async def abs_basics():
+    assert ABS_HOST is not None
+    assert ABS_USER is not None
+    assert ABS_PASSWORD is not None
+
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+    async with aiohttp.ClientSession() as session:
+        client = await get_user_client(
+            session_config=SessionConfiguration(
+                session=session, url=ABS_HOST, logger=logger, pagination_items_per_page=30
+            ),
+            username=ABS_USER,
+            password=ABS_PASSWORD,
+        )
+
+        # get libraries
+        libraries = await client.get_all_libraries()
+
+        # get library items
+        for library in libraries:
+            async for response in client.get_library_items(library_id=library.id_):
+                if not response.results:
+                    break
+                for lib_item_minified in response.results:
+                    if isinstance(lib_item_minified, LibraryItemMinifiedPodcast):
+                        ...
+                    if isinstance(lib_item_minified, LibraryItemMinifiedBook):
+                        ...
+
+        # get a single podcast
+        podcast_id = "dda96167-eaad-4012-83e1-149c6700d3e8"
+        podcast_expanded = client.get_library_item_podcast(podcast_id=podcast_id, expanded=True)
+
+
+asyncio.run(abs_basics())
+```
+
+Have a look into `aioaudiobookshelf/client/*.py` to see which endpoints are
+currently implemented. And the [provider
+implementation](https://github.com/music-assistant/server/blob/dev/music_assistant/providers/audiobookshelf/__init__.py) shows, how the lib can potentially be used.

{aioaudiobookshelf-0.1.2 → aioaudiobookshelf-0.1.3}/aioaudiobookshelf/__init__.py

@@ -3,15 +3,16 @@
 from aiohttp.client_exceptions import ClientResponseError, InvalidUrlClientError
 
 from aioaudiobookshelf.client import AdminClient, SessionConfiguration, SocketClient, UserClient
-from aioaudiobookshelf.exceptions import LoginError
-from aioaudiobookshelf.schema.calls_login import LoginParameters, LoginResponse
+from aioaudiobookshelf.exceptions import LoginError, TokenIsMissingError
+from aioaudiobookshelf.schema.calls_login import AuthorizeResponse, LoginParameters, LoginResponse
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 
 async def _get_login_response(
     *, session_config: SessionConfiguration, username: str, password: str
 ) -> LoginResponse:
+    """Login via username and password."""
     login_request = LoginParameters(username=username, password=password).to_dict()
 
     try:
@@ -26,6 +27,42 @@ async def _get_login_response(
     return LoginResponse.from_json(await resp.read())
 
 
+async def _get_authorize_response(*, session_config: SessionConfiguration) -> AuthorizeResponse:
+    """Login via token."""
+    try:
+        resp = await session_config.session.post(
+            f"{session_config.url}/api/authorize",
+            ssl=session_config.verify_ssl,
+            raise_for_status=True,
+            headers=session_config.headers,
+        )
+    except (ClientResponseError, InvalidUrlClientError, TokenIsMissingError) as exc:
+        raise LoginError from exc
+    return AuthorizeResponse.from_json(await resp.read())
+
+
+async def get_user_client_by_token(*, session_config: SessionConfiguration) -> UserClient:
+    """Get user client by token. Token must be set in session_config."""
+    authorize_response = await _get_authorize_response(session_config=session_config)
+    return UserClient(session_config=session_config, login_response=authorize_response)
+
+
+async def get_user_and_socket_client_by_token(
+    *, session_config: SessionConfiguration
+) -> tuple[UserClient, SocketClient]:
+    """Get user and socket client by token. Token must be set in session_config."""
+    authorize_response = await _get_authorize_response(session_config=session_config)
+    user_client = UserClient(session_config=session_config, login_response=authorize_response)
+    socket_client = SocketClient(session_config=session_config)
+    return user_client, socket_client
+
+
+async def get_admin_client_by_token(*, session_config: SessionConfiguration) -> AdminClient:
+    """Get admin client by token. Token must be set in session_config."""
+    authorize_response = await _get_authorize_response(session_config=session_config)
+    return AdminClient(session_config=session_config, login_response=authorize_response)
+
+
 async def get_user_client(
     *,
     session_config: SessionConfiguration,

{aioaudiobookshelf-0.1.2 → aioaudiobookshelf-0.1.3}/aioaudiobookshelf/client/__init__.py

@@ -9,7 +9,7 @@ import socketio
 import socketio.exceptions
 from aiohttp import ClientSession
 
-from aioaudiobookshelf.exceptions import BadUserError
+from aioaudiobookshelf.exceptions import BadUserError, TokenIsMissingError
 from aioaudiobookshelf.schema.events_socket import (
     LibraryItemRemoved,
     PodcastEpisodeDownload,
@@ -37,7 +37,7 @@ class SessionConfiguration:
     session: ClientSession
     url: str
     verify_ssl: bool = True
-    token: str = ""
+    token: str | None = None
     pagination_items_per_page: int = 10
     logger: logging.Logger | None = None
 
@@ -45,7 +45,7 @@ class SessionConfiguration:
     def headers(self) -> dict[str, str]:
         """Session headers."""
         if self.token is None:
-            raise RuntimeError("Token not set.")
+            raise TokenIsMissingError("Token not set.")
         return {"Authorization": f"Bearer {self.token}"}
 
     def __post_init__(self) -> None:

{aioaudiobookshelf-0.1.2 → aioaudiobookshelf-0.1.3}/aioaudiobookshelf/exceptions.py

@@ -11,3 +11,7 @@ class LoginError(Exception):
 
 class ApiError(Exception):
     """Exception raised if call to api failed."""
+
+
+class TokenIsMissingError(Exception):
+    """Exception raised if token is missing."""

{aioaudiobookshelf-0.1.2 → aioaudiobookshelf-0.1.3}/aioaudiobookshelf/schema/calls_login.py

@@ -26,3 +26,7 @@ class LoginResponse(DataClassJSONMixin):
     user_default_library_id: Annotated[str, Alias("userDefaultLibraryId")]
     server_settings: Annotated[ServerSettings, Alias("serverSettings")]
     source: Annotated[str, Alias("Source")]
+
+
+# api/authorize, if token is used for authorization
+AuthorizeResponse = LoginResponse

aioaudiobookshelf-0.1.3/aioaudiobookshelf.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.2
+Name: aioaudiobookshelf
+Version: 0.1.3
+Summary: Async library for Audiobookshelf
+Author-email: Fabian Munkes <105975993+fmunkes@users.noreply.github.com>
+License: Apache-2.0
+Platform: any
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp
+Requires-Dist: mashumaro
+Requires-Dist: python-socketio>=5.12
+Provides-Extra: test
+Requires-Dist: codespell==2.3.0; extra == "test"
+Requires-Dist: isort==5.13.2; extra == "test"
+Requires-Dist: mypy==1.13.0; extra == "test"
+Requires-Dist: pre-commit==4.0.1; extra == "test"
+Requires-Dist: pre-commit-hooks==5.0.0; extra == "test"
+Requires-Dist: pytest==8.3.4; extra == "test"
+Requires-Dist: pytest-aiohttp==1.0.5; extra == "test"
+Requires-Dist: pytest-cov==5.0.0; extra == "test"
+Requires-Dist: syrupy==4.8.1; extra == "test"
+Requires-Dist: tomli==2.2.1; extra == "test"
+Requires-Dist: ruff==0.9.2; extra == "test"
+Requires-Dist: bumpver; extra == "test"
+
+# aioaudiobookshelf
+Async python library to interact with
+[Audiobookshelf](https://github.com/advplyr/audiobookshelf) (ABS).
+
+This lib's primary goal is to be used within the Audiobookshelf music provider
+in Music Assistant, but it can be used independently. Calls to endpoints not
+needed for the provider will be added over time.
+
+Not all endpoints are yet implemented.
+
+## Releases
+Releases can be found on [pypi](https://pypi.org/project/aioaudiobookshelf/),
+and are tagged.
+
+## Basic usage
+ABS has a rest api, documented
+[here](https://api.audiobookshelf.org) and additionally uses socket.io, see
+[here](https://api.audiobookshelf.org/#socket) for some event driven
+functionality.
+Accessibility to the endpoints is determined by the [user
+types](https://api.audiobookshelf.org/#user), which may be `root, admin, user, guest`.
+This lib is not tested with a `guest` user.
+
+As of `0.1.2` this lib has two different clients, the `UserClient` and the
+`SocketClient`. Admin endpoints are not yet implemented. The user client
+handles calls to the Rest API, the socket client allows to subscribe to certain
+events.
+
+To authenticate the socket client, you always need the user's token, username
+and password are not enough. The user client can be authenticated by username
+and password, which yields the token.
+
+Usage example:
+```python
+import asyncio
+import logging
+import os
+
+import aiohttp
+
+from aioaudiobookshelf import SessionConfiguration, get_user_client
+from aioaudiobookshelf.schema.library import LibraryItemMinifiedBook, LibraryItemMinifiedPodcast
+
+ABS_HOST = os.environ.get("ABS_HOST")
+ABS_USER = os.environ.get("ABS_USER")
+ABS_PASSWORD = os.environ.get("ABS_PASSWORD")
+
+
+async def abs_basics():
+    assert ABS_HOST is not None
+    assert ABS_USER is not None
+    assert ABS_PASSWORD is not None
+
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+    async with aiohttp.ClientSession() as session:
+        client = await get_user_client(
+            session_config=SessionConfiguration(
+                session=session, url=ABS_HOST, logger=logger, pagination_items_per_page=30
+            ),
+            username=ABS_USER,
+            password=ABS_PASSWORD,
+        )
+
+        # get libraries
+        libraries = await client.get_all_libraries()
+
+        # get library items
+        for library in libraries:
+            async for response in client.get_library_items(library_id=library.id_):
+                if not response.results:
+                    break
+                for lib_item_minified in response.results:
+                    if isinstance(lib_item_minified, LibraryItemMinifiedPodcast):
+                        ...
+                    if isinstance(lib_item_minified, LibraryItemMinifiedBook):
+                        ...
+
+        # get a single podcast
+        podcast_id = "dda96167-eaad-4012-83e1-149c6700d3e8"
+        podcast_expanded = client.get_library_item_podcast(podcast_id=podcast_id, expanded=True)
+
+
+asyncio.run(abs_basics())
+```
+
+Have a look into `aioaudiobookshelf/client/*.py` to see which endpoints are
+currently implemented. And the [provider
+implementation](https://github.com/music-assistant/server/blob/dev/music_assistant/providers/audiobookshelf/__init__.py) shows, how the lib can potentially be used.

{aioaudiobookshelf-0.1.2 → aioaudiobookshelf-0.1.3}/pyproject.toml

@@ -18,7 +18,7 @@ description = "Async library for Audiobookshelf"
 license = {text = "Apache-2.0"}
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.1.2"
+version = "0.1.3"
 
 [project.optional-dependencies]
 test = [
@@ -133,13 +133,13 @@ known-first-party = ["music_assistant"]
 max-complexity = 25
 
 [tool.bumpver]
-current_version = "0.1.2"
+current_version = "0.1.3"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "bump version {old_version} -> {new_version}"
 tag_message = "{new_version}"
 commit = true
 tag = true
-push = false
+push = true
 
 [tool.bumpver.file_patterns]
 "pyproject.toml" = [

aioaudiobookshelf-0.1.2/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.2
-Name: aioaudiobookshelf
-Version: 0.1.2
-Summary: Async library for Audiobookshelf
-Author-email: Fabian Munkes <105975993+fmunkes@users.noreply.github.com>
-License: Apache-2.0
-Platform: any
-Classifier: Environment :: Console
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp
-Requires-Dist: mashumaro
-Requires-Dist: python-socketio>=5.12
-Provides-Extra: test
-Requires-Dist: codespell==2.3.0; extra == "test"
-Requires-Dist: isort==5.13.2; extra == "test"
-Requires-Dist: mypy==1.13.0; extra == "test"
-Requires-Dist: pre-commit==4.0.1; extra == "test"
-Requires-Dist: pre-commit-hooks==5.0.0; extra == "test"
-Requires-Dist: pytest==8.3.4; extra == "test"
-Requires-Dist: pytest-aiohttp==1.0.5; extra == "test"
-Requires-Dist: pytest-cov==5.0.0; extra == "test"
-Requires-Dist: syrupy==4.8.1; extra == "test"
-Requires-Dist: tomli==2.2.1; extra == "test"
-Requires-Dist: ruff==0.9.2; extra == "test"
-Requires-Dist: bumpver; extra == "test"
-
-# aioaudiobookshelf
-Async python library to interact with Audiobookshelf

aioaudiobookshelf-0.1.2/README.md

@@ -1,2 +0,0 @@
-# aioaudiobookshelf
-Async python library to interact with Audiobookshelf

aioaudiobookshelf-0.1.2/aioaudiobookshelf.egg-info/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.2
-Name: aioaudiobookshelf
-Version: 0.1.2
-Summary: Async library for Audiobookshelf
-Author-email: Fabian Munkes <105975993+fmunkes@users.noreply.github.com>
-License: Apache-2.0
-Platform: any
-Classifier: Environment :: Console
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp
-Requires-Dist: mashumaro
-Requires-Dist: python-socketio>=5.12
-Provides-Extra: test
-Requires-Dist: codespell==2.3.0; extra == "test"
-Requires-Dist: isort==5.13.2; extra == "test"
-Requires-Dist: mypy==1.13.0; extra == "test"
-Requires-Dist: pre-commit==4.0.1; extra == "test"
-Requires-Dist: pre-commit-hooks==5.0.0; extra == "test"
-Requires-Dist: pytest==8.3.4; extra == "test"
-Requires-Dist: pytest-aiohttp==1.0.5; extra == "test"
-Requires-Dist: pytest-cov==5.0.0; extra == "test"
-Requires-Dist: syrupy==4.8.1; extra == "test"
-Requires-Dist: tomli==2.2.1; extra == "test"
-Requires-Dist: ruff==0.9.2; extra == "test"
-Requires-Dist: bumpver; extra == "test"
-
-# aioaudiobookshelf
-Async python library to interact with Audiobookshelf