from __future__ import annotations
from typing import TYPE_CHECKING
from ..._shared import TTLCache, _copy_docstring
from ._shared import DeezerResourceAPI
from .charts import ChartsAPI
from .users import UsersAPI
if TYPE_CHECKING:
from typing import Any
[docs]
class PodcastsAPI(DeezerResourceAPI):
"""
Podcasts API endpoints for the Deezer API.
.. important::
This class is managed by
:class:`~minim.api.deezer.DeezerAPIClient` and should not be
instantiated directly.
"""
__slot__ = ()
[docs]
@TTLCache.cached_method(ttl="popularity")
def get_podcast(self, podcast_id: int | str, /) -> dict[str, Any]:
"""
`Podcast <https://developers.deezer.com/api/podcast>`_: Get
Deezer catalog information for a podcast.
Parameters
----------
podcast_id : int or str; positional-only
Deezer ID of the podcast.
**Examples**: :code:`436862`, :code:`"2740882"`.
Returns
-------
podcast : dict[str, Any]
Deezer metadata for the podcast.
.. admonition:: Sample response
:class: response dropdown
.. code-block::
{
"available": <bool>,
"description": <str>,
"fans": <int>,
"id": <int>,
"link": <str>,
"picture": <str>,
"picture_big": <str>,
"picture_medium": <str>,
"picture_small": <str>,
"picture_xl": <str>,
"share": <str>,
"title": <str>,
"type": "podcast"
}
"""
return self._request_resource_relationship(
"GET", "podcast", podcast_id
)
[docs]
@TTLCache.cached_method(ttl="daily")
def get_podcast_episodes(
self,
podcast_id: int | str,
/,
*,
limit: int | None = None,
offset: int | None = None,
) -> dict[str, Any]:
"""
`Podcast > Episodes <https://developers.deezer.com/api/podcast
/episodes>`_: Get Deezer catalog information for episodes in a
podcast.
Parameters
----------
podcast_id : int or str; positional-only
Deezer ID of the podcast.
**Examples**: :code:`436862`, :code:`"2740882"`.
limit : int; keyword-only; optional
Maximum number of episodes to return.
**Minimum value**: :code:`1`.
**API default**: :code:`25`.
offset : int; keyword-only; optional
Index of the first episode to return. Use with `limit` to
get the next batch of episodes.
**Minimum value**: :code:`0`.
**API default**: :code:`0`.
Returns
-------
episodes : dict[str, Any]
Page of Deezer metadata for the podcast's episodes.
.. admonition:: Sample response
:class: response dropdown
.. code-block::
{
"data": [
{
"duration": <int>,
"id": <int>,
"picture": <str>,
"release_date": <str>,
"title": <str>,
"type": "episode"
}
],
"next": <str>,
"prev": <str>,
"total": <int>
}
"""
return self._request_resource_relationship(
"GET",
"podcast",
podcast_id,
"episodes",
limit=limit,
offset=offset,
)
[docs]
@_copy_docstring(ChartsAPI.get_top_podcasts)
def get_top_podcasts(
self, *, limit: int | None = None, offset: int | None = None
) -> dict[str, Any]:
return self._client.charts.get_top_podcasts(limit=limit, offset=offset)
[docs]
@_copy_docstring(UsersAPI.get_user_followed_podcasts)
def get_user_followed_podcasts(
self,
user_id: int | str = "me",
/,
*,
limit: int | None = None,
offset: int | None = None,
) -> dict[str, Any]:
return self._client.users.get_user_followed_podcasts(
user_id, limit=limit, offset=offset
)
[docs]
@_copy_docstring(UsersAPI.follow_podcast)
def follow_podcast(
self, podcast_id: int | str, /, *, user_id: int | str = "me"
) -> bool:
return self._client.users.follow_podcast(podcast_id, user_id=user_id)
[docs]
@_copy_docstring(UsersAPI.unfollow_podcast)
def unfollow_podcast(
self,
podcast_id: int | str,
/,
*,
user_id: int | str = "me",
) -> bool:
return self._client.users.unfollow_podcast(podcast_id, user_id=user_id)
