from __future__ import annotations
from typing import TYPE_CHECKING
from ..._shared import TTLCache
from ._shared import TIDALResourceAPI
if TYPE_CHECKING:
from typing import Any
from ...._types import Collection
[docs]
class ArtworksAPI(TIDALResourceAPI):
"""
Artworks API endpoints for the TIDAL API.
.. important::
This class is managed by :class:`~minim.api.tidal.TIDALAPIClient`
and should not be instantiated directly.
"""
_RELATIONSHIPS = {"owners"}
__slots__ = ()
[docs]
@TTLCache.cached_method(ttl="static")
def get_artworks(
self,
artwork_ids: str | Collection[str],
/,
country_code: str | None = None,
*,
expand: str | Collection[str] | None = None,
) -> dict[str, Any]:
"""
`Artworks > Get Single Artwork <https://tidal-music.github.io
/tidal-api-reference/#/artworks/get_artworks__id_>`_: Get TIDAL
catalog information for an artwork․
`Artworks > Get Multiple Artworks <https://tidal-music.github.io
/tidal-api-reference/#/artworks/get_artworks>`_: Get TIDAL
catalog information for multiple artworks.
.. admonition:: User authentication
:class: entitlement dropdown
.. tab-set::
.. tab-item:: Optional
User authentication
Access information for a resource's owners.
Parameters
----------
artwork_ids : str or Collection[str]; positional-only
TIDAL IDs of the artworks.
**Examples**: :code:`"2xpmpI1s9DzeAPMlmNh9kM"`,
:code:`["2xpmpI1s9DzeAPMlmNh9kM", "iWOu0yW0IPH0H5O42lAP"]`.
country_code : str; keyword-only; optional
ISO 3166-1 alpha-2 country code.
**Example**: :code:`"US"`.
expand : str or Collection[str]; keyword-only; optional
Related resources to include metadata for in the response.
**Valid value**: :code:`"owners"`.
**Examples**: :code:`"owners"`, :code:`["owners"]`.
Returns
-------
artworks : dict[str, Any]
TIDAL metadata for the artworks.
.. admonition:: Sample responses
:class: response dropdown
.. tab-set::
.. tab-item:: Single artwork
.. code-block::
{
"data": {
"attributes": {
"files": [
{
"href": <str>,
"meta": {
"height": <int>,
"width": <int>
}
}
],
"mediaType": "IMAGE"
},
"id": <str>,
"relationships": {
"owners": {
"data": [],
"links": {
"self": <str>
}
}
},
"type": "artworks"
},
"included": [],
"links": {
"self": <str>
}
}
.. tab-item:: Multiple artworks
.. code-block::
{
"data": [
{
"attributes": {
"files": [
{
"href": <str>,
"meta": {
"height": <int>,
"width": <int>
}
}
],
"mediaType": "IMAGE"
},
"id": <str>,
"relationships": {
"owners": {
"data": [],
"links": {
"self": <str>
}
}
},
"type": "artworks"
}
],
"included": [],
"links": {
"self": <str>
}
}
"""
return self._get_resources(
"artworks", artwork_ids, country_code=country_code, expand=expand
)
[docs]
@TTLCache.cached_method(ttl="static")
def get_artwork_owners(
self,
artwork_id: str,
/,
*,
include_metadata: bool = False,
cursor: str | None = None,
) -> dict[str, Any]:
"""
`Artworks > Get Artwork's Owners <https://tidal-music.github.io
/tidal-api-reference/#/artworks
/get_artworks__id__relationships_owners>`_: Get TIDAL profile
information for owners of an artwork resource.
.. admonition:: User authentication
:class: entitlement dropdown
.. tab-set::
.. tab-item:: Optional
User authentication
Access information for a resource's owners.
Parameters
----------
artwork_id : str; positional-only
TIDAL ID of the artwork.
**Example**: :code:`"2xpmpI1s9DzeAPMlmNh9kM"`.
include_metadata : bool; keyword-only; default: :code:`False`
Whether to include metadata for the owners.
cursor : str; keyword-only; optional
Cursor for fetching the next page of results.
**Example**: :code:`"3nI1Esi"`.
Returns
-------
owners : dict[str, Any]
Page of TIDAL profile information for the artwork resource's
owners.
.. admonition:: Sample response
:class: response dropdown
.. code-block::
{
"data": [],
"included": [],
"links": {
"self": <str>
}
}
"""
return self._get_resource_relationship(
"artworks",
artwork_id,
"owners",
include_metadata=include_metadata,
cursor=cursor,
)
