Skip to content

Commit

Permalink
docs: fix links to resources and pagination classes (#567)
Browse files Browse the repository at this point in the history
  • Loading branch information
@browniebroke
browniebroke committed Sep 6, 2022
1 parent d5c2e84 commit 1adce18
Show file tree
Hide file tree
Showing 13 changed files with 80 additions and 80 deletions.
2 changes: 1 addition & 1 deletion docs/source/pagination.md
View file
@@ -1,6 +1,6 @@
# Pagination

For endpoints returning a paginated response, the list of items are wrapped in a {class}`PaginatedList <deezer.pagination.PaginatedList>` class which makes working with pagination more Pythonic while doing the necessary API calls transparently.
For endpoints returning a paginated response, the list of items are wrapped in a {class}`PaginatedList <deezer.PaginatedList>` class which makes working with pagination more Pythonic while doing the necessary API calls transparently.

## Iterating over elements

Expand Down
6 changes: 3 additions & 3 deletions docs/source/usage.md
View file
Expand Up @@ -64,7 +64,7 @@ You may have noticed from the above examples, but depending on the endpoint that

### Getting a field about a resource

When you ge a resource, you have access to all the fields that are in the REST API response. For example, all the fields presented in the documentation for [the track object](https://developers.deezer.com/api/track) are accessible as attribute on the {class}`Track <deezer.resources.Track>` resource:
When you ge a resource, you have access to all the fields that are in the REST API response. For example, all the fields presented in the documentation for [the track object](https://developers.deezer.com/api/track) are accessible as attribute on the {class}`Track <deezer.Track>` resource:

```python
>>> instant_crush
Expand All @@ -81,7 +81,7 @@ True

As well as giving access to its own attributes, a resource also gives access to other related resources.

For example, when you get an {class}`Artist <deezer.resources.Artist>`, you may call one of the methods documented to get the artist's albums, then from an {class}`Album <deezer.resources.Album>` get its tracks, and from a {class}`Track <deezer.resources.Track>` you may go back to the {class}`Album <deezer.resources.Album>` or the {class}`Artist <deezer.resources.Artist>`.
For example, when you get an {class}`Artist <deezer.Artist>`, you may call one of the methods documented to get the artist's albums, then from an {class}`Album <deezer.Album>` get its tracks, and from a {class}`Track <deezer.Track>` you may go back to the {class}`Album <deezer.Album>` or the {class}`Artist <deezer.Artist>`.

Let's try from the initial example:

Expand Down Expand Up @@ -162,7 +162,7 @@ Deezer Python itself doesn't handle the authentication & authorization, but it a

To integrate the OAuth flow in your application, we recommend looking at other libraries like [Python Social Auth](https://github.com/python-social-auth), which supports Deezer authentication.

Once the OAuth2 flow is complete, Deezer should give you a token which can be passed to the {class}`Client <deezer.client.Client>` class:
Once the OAuth2 flow is complete, Deezer should give you a token which can be passed to the {class}`Client <deezer.Client>` class:

```python
client = deezer.Client(access_token='your-super-secret-token')
Expand Down
58 changes: 29 additions & 29 deletions src/deezer/client.py
View file
Expand Up @@ -89,14 +89,14 @@ def _process_json(
):
"""
Recursively convert dictionary
to :class:`~deezer.resources.Resource` object
to :class:`~deezer.Resource` object
:param item: the JSON response as dict.
:param parent: A reference to the parent resource, to avoid fetching again.
:param resource_type: The resource class to use as top level.
:param resource_id: The resource id to use as top level.
:param paginate_list: Whether to wrap list into a pagination object.
:returns: instance of :class:`~deezer.resources.Resource`
:returns: instance of :class:`~deezer.Resource`
"""
if "data" in item:
parsed_data = [
Expand Down Expand Up @@ -182,15 +182,15 @@ def get_album(self, album_id: int) -> Album:
"""
Get the album with the given ID.
:returns: an :class:`~deezer.resources.Album` object
:returns: an :class:`~deezer.Album` object
"""
return self.request("GET", f"album/{album_id}")

def get_artist(self, artist_id: int) -> Artist:
"""
Get the artist with the given ID.
:returns: an :class:`~deezer.resources.Artist` object
:returns: an :class:`~deezer.Artist` object
"""
return self.request("GET", f"artist/{artist_id}")

Expand All @@ -201,7 +201,7 @@ def get_chart(self, genre_id: int = 0) -> Chart:
Combine charts of several resources in one endpoint.
:param genre_id: the genre ID, default to `All` genre (genre_id = 0).
:returns: a :class:`~deezer.resources.Chart` instance.
:returns: a :class:`~deezer.Chart` instance.
"""
return self.request(
"GET", f"chart/{genre_id}", resource_type=Chart, resource_id=genre_id
Expand All @@ -212,7 +212,7 @@ def get_tracks_chart(self, genre_id: int = 0) -> list[Track]:
Get top tracks for the given genre ID.
:param genre_id: the genre ID, default to `All` genre (genre_id = 0).
:return: a list of :class:`~deezer.resources.Track` instances.
:return: a list of :class:`~deezer.Track` instances.
"""
return self.request("GET", f"chart/{genre_id}/tracks")

Expand All @@ -221,7 +221,7 @@ def get_albums_chart(self, genre_id: int = 0) -> list[Album]:
Get top albums for the given genre ID.
:param genre_id: the genre ID, default to `All` genre (genre_id = 0).
:return: a list of :class:`~deezer.resources.Album` instances.
:return: a list of :class:`~deezer.Album` instances.
"""
return self.request("GET", f"chart/{genre_id}/albums")

Expand All @@ -230,7 +230,7 @@ def get_artists_chart(self, genre_id: int = 0) -> list[Artist]:
Get top artists for the given genre ID.
:param genre_id: the genre ID, default to `All` genre (genre_id = 0).
:return: a list of :class:`~deezer.resources.Artist` instances.
:return: a list of :class:`~deezer.Artist` instances.
"""
return self.request("GET", f"chart/{genre_id}/artists")

Expand All @@ -239,7 +239,7 @@ def get_playlists_chart(self, genre_id: int = 0) -> list[Playlist]:
Get top playlists for the given genre ID.
:param genre_id: the genre ID, default to `All` genre (genre_id = 0).
:return: a list of :class:`~deezer.resources.Playlist` instances.
:return: a list of :class:`~deezer.Playlist` instances.
"""
return self.request("GET", f"chart/{genre_id}/playlists")

Expand All @@ -248,15 +248,15 @@ def get_podcasts_chart(self, genre_id: int = 0) -> list[Podcast]:
Get top podcasts for the given genre ID.
:param genre_id: the genre ID, default to `All` genre (genre_id = 0).
:return: a list of :class:`~deezer.resources.Podcast` instances.
:return: a list of :class:`~deezer.Podcast` instances.
"""
return self.request("GET", f"chart/{genre_id}/podcasts")

def get_editorial(self, editorial_id: int) -> Editorial:
"""
Get the editorial with the given ID.
:returns: a :class:`~deezer.resources.Editorial` object.
:returns: a :class:`~deezer.Editorial` object.
"""
return self.request("GET", f"editorial/{editorial_id}")

Expand All @@ -265,63 +265,63 @@ def list_editorials(self) -> PaginatedList[Editorial]:
List editorials.
:returns: a :class:`~deezer.pagination.PaginatedList`
of :class:`~deezer.resources.Editorial` objects.
of :class:`~deezer.Editorial` objects.
"""
return self._get_paginated_list("editorial")

def get_episode(self, episode_id: int) -> Episode:
"""
Get the episode with the given ID.
:returns: a :class:`~deezer.resources.Episode` object
:returns: a :class:`~deezer.Episode` object
"""
return self.request("GET", f"episode/{episode_id}")

def get_genre(self, genre_id: int) -> Genre:
"""
Get the genre with the given ID
:returns: a :class:`~deezer.resources.Genre` object
:returns: a :class:`~deezer.Genre` object
"""
return self.request("GET", f"genre/{genre_id}")

def list_genres(self) -> list[Genre]:
"""
List musical genres.
:return: a list of :class:`~deezer.resources.Genre` instances
:return: a list of :class:`~deezer.Genre` instances
"""
return self.request("GET", "genre")

def get_playlist(self, playlist_id: int) -> Playlist:
"""
Get the playlist with the given ID.
:returns: a :class:`~deezer.resources.Playlist` object
:returns: a :class:`~deezer.Playlist` object
"""
return self.request("GET", f"playlist/{playlist_id}")

def get_podcast(self, podcast_id: int) -> Podcast:
"""
Get the podcast with the given ID.
:returns: a :class:`~deezer.resources.Podcast` object
:returns: a :class:`~deezer.Podcast` object
"""
return self.request("GET", f"podcast/{podcast_id}")

def get_radio(self, radio_id: int) -> Radio:
"""
Get the radio with the given ID.
:returns: a :class:`~deezer.resources.Radio` object
:returns: a :class:`~deezer.Radio` object
"""
return self.request("GET", f"radio/{radio_id}")

def list_radios(self) -> list[Radio]:
"""
List radios.
:return: a list of :class:`~deezer.resources.Radio` instances
:return: a list of :class:`~deezer.Radio` instances
"""
return self.request("GET", "radio")

Expand All @@ -330,23 +330,23 @@ def get_radios_top(self) -> PaginatedList[Radio]:
Get the top radios.
:returns: a :class:`~deezer.pagination.PaginatedList`
of :class:`~deezer.resources.Radio` objects.
of :class:`~deezer.Radio` objects.
"""
return self._get_paginated_list("radio/top")

def get_track(self, track_id: int) -> Track:
"""
Get the track with the given ID.
:returns: a :class:`~deezer.resources.Track` object
:returns: a :class:`~deezer.Track` object
"""
return self.request("GET", f"track/{track_id}")

def get_user(self, user_id: int | None = None) -> User:
"""
Get the user with the given ID.
:returns: a :class:`~deezer.resources.User` object
:returns: a :class:`~deezer.User` object
"""
user_id_str = str(user_id) if user_id else "me"
return self.request("GET", f"user/{user_id_str}")
Expand All @@ -356,7 +356,7 @@ def get_user_albums(self, user_id: int | None = None) -> PaginatedList[Album]:
Get the favourites albums for the given user_id if provided or current user if not.
:param user_id: the user ID to get favourites albums.
:return: a list of :class:`~deezer.resources.Album` instances.
:return: a list of :class:`~deezer.Album` instances.
"""
user_id_str = str(user_id) if user_id else "me"
return self._get_paginated_list(f"user/{user_id_str}/albums")
Expand Down Expand Up @@ -385,7 +385,7 @@ def get_user_artists(self, user_id: int | None = None) -> PaginatedList[Artist]:
:param user_id: the user ID to get favourites artists.
:return: a :class:`~deezer.pagination.PaginatedList`
of :class:`~deezer.resources.Artist` instances.
of :class:`~deezer.Artist` instances.
"""
user_id_str = str(user_id) if user_id else "me"
return self._get_paginated_list(f"user/{user_id_str}/artists")
Expand Down Expand Up @@ -413,7 +413,7 @@ def get_user_history(self) -> PaginatedList[Track]:
Returns a list of the recently played tracks for the current user.
:return: a :class:`~deezer.pagination.PaginatedList`
of :class:`~deezer.resources.Track` instances.
of :class:`~deezer.Track` instances.
"""
return self._get_paginated_list("user/me/history")

Expand All @@ -423,7 +423,7 @@ def get_user_tracks(self, user_id: int | None = None) -> PaginatedList[Track]:
:param user_id: the user ID to get favourites tracks.
:return: a :class:`~deezer.pagination.PaginatedList`
of :class:`~deezer.resources.Track` instances.
of :class:`~deezer.Track` instances.
"""
user_id_str = str(user_id) if user_id else "me"
return self._get_paginated_list(f"user/{user_id_str}/tracks")
Expand Down Expand Up @@ -505,7 +505,7 @@ def search(
:param dur_max: parameter for the advanced search feature.
:param bpm_min: parameter for the advanced search feature.
:param bpm_max: parameter for the advanced search feature.
:returns: a list of :class:`~deezer.resources.Track` instances.
:returns: a list of :class:`~deezer.Track` instances.
"""
return self._search(
"",
Expand Down Expand Up @@ -534,7 +534,7 @@ def search_albums(
:param query: the query to search for, this is directly passed as q query.
:param strict: whether to disable fuzzy search and enable strict mode.
:param ordering: see Deezer API docs for possible values.
:return: list of :class:`~deezer.resources.Album` instances.
:return: list of :class:`~deezer.Album` instances.
"""
return self._search(
path="album",
Expand All @@ -555,7 +555,7 @@ def search_artists(
:param query: the query to search for, this is directly passed as q query.
:param strict: whether to disable fuzzy search and enable strict mode.
:param ordering: see Deezer API docs for possible values.
:return: list of :class:`~deezer.resources.Album` instances.
:return: list of :class:`~deezer.Album` instances.
"""
return self._search(
path="artist",
Expand Down
6 changes: 3 additions & 3 deletions src/deezer/resources/album.py
View file
Expand Up @@ -63,15 +63,15 @@ def get_artist(self) -> Artist:
"""
Get the artist of the Album.
:returns: the :class:`Artist <deezer.resources.Artist>` of the Album
:returns: the :class:`Artist <deezer.Artist>` of the Album
"""
return self.client.get_artist(self.artist.id)

def get_tracks(self, **kwargs) -> PaginatedList[Track]:
"""
Get a list of album's tracks.
:returns: a :class:`PaginatedList <deezer.pagination.PaginatedList>`
of :class:`Track <deezer.resources.Track>`.
:returns: a :class:`PaginatedList <deezer.PaginatedList>`
of :class:`Track <deezer.Track>`.
"""
return self.get_paginated_list("tracks", **kwargs)
18 changes: 9 additions & 9 deletions src/deezer/resources/artist.py
View file
Expand Up @@ -37,42 +37,42 @@ def get_top(self, **kwargs) -> PaginatedList[Track]:
"""
Get the top tracks of an artist.
:returns: a :class:`PaginatedList <deezer.pagination.PaginatedList>`
of :class:`Track <deezer.resources.Track>` instances.
:returns: a :class:`PaginatedList <deezer.PaginatedList>`
of :class:`Track <deezer.Track>` instances.
"""
return self.get_paginated_list("top", **kwargs)

def get_related(self, **kwargs) -> PaginatedList[Artist]:
"""
Get a list of related artists.
:returns: a :class:`PaginatedList <deezer.pagination.PaginatedList>`
of :class:`Artist <deezer.resources.Artist>` instances
:returns: a :class:`PaginatedList <deezer.PaginatedList>`
of :class:`Artist <deezer.Artist>` instances
"""
return self.get_paginated_list("related", **kwargs)

def get_radio(self, **kwargs) -> list[Track]:
"""
Get a list of tracks.
:returns: list of :class:`Track <deezer.resources.Track>` instances
:returns: list of :class:`Track <deezer.Track>` instances
"""
return self.get_relation("radio", **kwargs)

def get_albums(self, **kwargs) -> PaginatedList[Album]:
"""
Get a list of artist's albums.
:returns: a :class:`PaginatedList <deezer.pagination.PaginatedList>`
of :class:`Album <deezer.resources.Album>` instances
:returns: a :class:`PaginatedList <deezer.PaginatedList>`
of :class:`Album <deezer.Album>` instances
"""
return self.get_paginated_list("albums", **kwargs)

def get_playlists(self, **kwargs) -> PaginatedList[Playlist]:
"""
Get a list of artist's playlists.
:returns: a :class:`PaginatedList <deezer.pagination.PaginatedList>`
of :class:`Playlist <deezer.resources.Playlist>` instances
:returns: a :class:`PaginatedList <deezer.PaginatedList>`
of :class:`Playlist <deezer.Playlist>` instances
"""
return self.get_paginated_list("playlists", **kwargs)

0 comments on commit 1adce18

Please sign in to comment.