from __future__ import annotations
from typing import TYPE_CHECKING
from ..._shared import TTLCache
from ._shared import DeezerResourceAPI
if TYPE_CHECKING:
from typing import Any
[docs]
class GenresAPI(DeezerResourceAPI):
"""
Genres 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="static")
def get_genre(
self, genre_id: int | str | None = None, /
) -> dict[str, Any]:
"""
`Genre <https://developers.deezer.com/api/genre>`_: Get
Deezer catalog information for a genre or all available genres.
Parameters
----------
genre_id : int, str, or None; positional-only; optional
Deezer ID of the genre. If :code:`None`, all available
genres are returned.
**Examples**: :code:`0`, :code:`"2"`.
Returns
-------
genre : dict[str, Any]
Deezer metadata for the specified genre or all available
genres.
.. admonition:: Sample response
:class: response dropdown
.. tab-set::
.. tab-item:: Single genre
.. code-block::
{
"id": <int>,
"name": <str>,
"picture": <str>,
"picture_big": <str>,
"picture_medium": <str>,
"picture_small": <str>,
"picture_xl": <str>,
"type": "genre"
}
.. tab-item:: Available genres
.. code-block::
{
"data": [
{
"id": <int>,
"name": <str>,
"picture": <str>,
"picture_big": <str>,
"picture_medium": <str>,
"picture_small": <str>,
"picture_xl": <str>,
"type": "genre"
}
]
}
"""
if genre_id is None:
return self._client._request("GET", "genre").json()
return self._request_resource_relationship("GET", "genre", genre_id)
[docs]
@TTLCache.cached_method(ttl="static")
def get_genre_artists(self, genre_id: int | str = 0, /) -> dict[str, Any]:
"""
`Genre > Artists <https://developers.deezer.com/api/genre
/artists>`_: Get Deezer catalog information for artists
primarily associated with a genre.
Parameters
----------
genre_id : int or str; positional-only; default: :code:`0`
Deezer ID of the genre.
**Examples**: :code:`0`, :code:`"2"`.
Returns
-------
artists : dict[str, Any]
Deezer metadata for the artists associated with the genre.
.. admonition:: Sample response
:class: response dropdown
.. code-block::
{
"data": [
{
"id": <int>,
"name": <str>,
"picture": <str>,
"picture_big": <str>,
"picture_medium": <str>,
"picture_small": <str>,
"picture_xl": <str>,
"radio": <bool>,
"tracklist": <str>,
"type": "artist"
}
]
}
"""
return self._request_resource_relationship(
"GET", "genre", genre_id, "artists"
)
[docs]
@TTLCache.cached_method(ttl="static")
def get_genre_podcasts(
self,
genre_id: int | str = 0,
/,
*,
limit: int | None = None,
offset: int | None = None,
) -> dict[str, Any]:
"""
`Genre > Podcasts <https://developers.deezer.com/api/genre
/podcasts>`_: Get Deezer catalog information for podcasts
primarily associated with a genre.
Parameters
----------
genre_id : int or str; positional-only; default: :code:`0`
Deezer ID of the genre.
**Examples**: :code:`0`, :code:`"2"`.
limit : int; keyword-only; optional
Maximum number of podcasts to return.
**Minimum value**: :code:`1`.
offset : int; keyword-only; optional
Index of the first podcast to return. Use with `limit` to
get the next batch of podcasts.
**Minimum value**: :code:`0`.
**API default**: :code:`0`.
Returns
-------
podcasts : dict[str, Any]
Page of Deezer metadata for the podcasts associated with the
genre.
.. admonition:: Sample response
:class: response dropdown
.. code-block::
{
"data": [],
"next": <str>,
"prev": <str>,
"total": <int>
}
"""
return self._request_resource_relationship(
"GET", "genre", genre_id, "podcasts", limit=limit, offset=offset
)
[docs]
@TTLCache.cached_method(ttl="static")
def get_genre_radios(self, genre_id: int | str = 0, /) -> dict[str, Any]:
"""
`Genre > Radios <https://developers.deezer.com/api/genre
/radios>`_: Get Deezer catalog information for radios primarily
associated with a genre.
Parameters
----------
genre_id : int or str; positional-only; default: :code:`0`
Deezer ID of the genre.
**Examples**: :code:`0`, :code:`"2"`.
Returns
-------
radios : dict[str, Any]
Deezer metadata for the radios primarily associated with the
genre.
.. admonition:: Sample response
:class: response dropdown
.. code-block::
{
"data": [
{
"id": <int>,
"md5_image": <str>,
"picture": <str>,
"picture_big": <str>,
"picture_medium": <str>,
"picture_small": <str>,
"picture_xl": <str>,
"title": <str>,
"tracklist": <str>,
"type": "radio"
}
]
}
"""
return self._request_resource_relationship(
"GET", "genre", genre_id, "radios"
)
