From 57d13669ce8d6d0e4f8d2ffc67aed78c094b02d8 Mon Sep 17 00:00:00 2001 From: henrich26 Date: Wed, 16 Oct 2024 23:38:05 +0200 Subject: [PATCH 1/2] Cleaned up docstrings --- ytmusicapi/auth/oauth/credentials.py | 10 +++++----- ytmusicapi/auth/oauth/token.py | 4 ++-- ytmusicapi/mixins/browsing.py | 2 +- ytmusicapi/mixins/explore.py | 2 +- ytmusicapi/mixins/library.py | 24 ++++++++++++------------ ytmusicapi/mixins/playlists.py | 4 ++-- ytmusicapi/mixins/search.py | 14 +++++++------- ytmusicapi/mixins/uploads.py | 4 ++-- 8 files changed, 32 insertions(+), 32 deletions(-) diff --git a/ytmusicapi/auth/oauth/credentials.py b/ytmusicapi/auth/oauth/credentials.py index 17368c48..d38153bb 100644 --- a/ytmusicapi/auth/oauth/credentials.py +++ b/ytmusicapi/auth/oauth/credentials.py @@ -53,9 +53,9 @@ def __init__( proxies: Optional[dict] = None, ): """ - :param client_id: Optional. Set the GoogleAPI client_id used for auth flows. - Requires client_secret also be provided if set. - :param client_secret: Optional. Corresponding secret for provided client_id. + :param client_id: Optional. Set the GoogleAPI `client_id` used for auth flows. + Requires `client_secret` also be provided if set. + :param client_secret: Optional. Corresponding secret for provided `client_id`. :param session: Optional. Connection pooling with an active session. :param proxies: Optional. Modify the session with proxy parameters. """ @@ -114,10 +114,10 @@ def token_from_code(self, device_code: str) -> RefreshableTokenDict: def refresh_token(self, refresh_token: str) -> BaseTokenDict: """ - Method for requesting a new access token for a given refresh_token. + Method for requesting a new access token for a given `refresh_token`. Token must have been created by the same OAuth client. - :param refresh_token: Corresponding refresh_token for a matching access_token. + :param refresh_token: Corresponding `refresh_token` for a matching `access_token`. Obtained via """ response = self._send_request( diff --git a/ytmusicapi/auth/oauth/token.py b/ytmusicapi/auth/oauth/token.py index e1596372..1ad54e81 100644 --- a/ytmusicapi/auth/oauth/token.py +++ b/ytmusicapi/auth/oauth/token.py @@ -117,8 +117,8 @@ def prompt_for_token( Method for CLI token creation via user inputs. :param credentials: Client credentials - :param open_browser: Optional. Open browser to OAuth consent url automatically. (Default = False). - :param to_file: Optional. Path to store/sync json version of resulting token. (Default = None). + :param open_browser: Optional. Open browser to OAuth consent url automatically. (Default: `False`). + :param to_file: Optional. Path to store/sync json version of resulting token. (Default: `None`). """ code = credentials.get_code() diff --git a/ytmusicapi/mixins/browsing.py b/ytmusicapi/mixins/browsing.py index c3467b72..b587beb1 100644 --- a/ytmusicapi/mixins/browsing.py +++ b/ytmusicapi/mixins/browsing.py @@ -285,7 +285,7 @@ def get_artist_albums( :param channelId: browseId of the artist as returned by :py:func:`get_artist` :param params: params obtained by :py:func:`get_artist` :param limit: Number of albums to return. `None` retrieves them all. Default: 100 - :param order: Order of albums to return. Allowed values: 'Recency', 'Popularity', 'Alphabetical order'. Default: Default order. + :param order: Order of albums to return. Allowed values: `Recency`, `Popularity`, `Alphabetical order`. Default: Default order. :return: List of albums in the format of :py:func:`get_library_albums`, except artists key is missing. diff --git a/ytmusicapi/mixins/explore.py b/ytmusicapi/mixins/explore.py index 1b64b668..35d14a0c 100644 --- a/ytmusicapi/mixins/explore.py +++ b/ytmusicapi/mixins/explore.py @@ -93,7 +93,7 @@ def get_charts(self, country: str = "ZZ") -> dict: Get latest charts data from YouTube Music: Top songs, top videos, top artists and top trending videos. Global charts have no Trending section, US charts have an extra Genres section with some Genre charts. - :param country: ISO 3166-1 Alpha-2 country code. Default: ZZ = Global + :param country: ISO 3166-1 Alpha-2 country code. Default: `ZZ` = Global :return: Dictionary containing chart songs (only if authenticated with premium account), chart videos, chart artists and trending videos. diff --git a/ytmusicapi/mixins/library.py b/ytmusicapi/mixins/library.py index 4cdbc5c0..e3765c69 100644 --- a/ytmusicapi/mixins/library.py +++ b/ytmusicapi/mixins/library.py @@ -55,7 +55,7 @@ def get_library_songs( :param limit: Number of songs to retrieve :param validate_responses: Flag indicating if responses from YTM should be validated and retried in case when some songs are missing. Default: False - :param order: Order of songs to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of songs to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of songs. Same format as :py:func:`get_playlist` """ self._check_auth() @@ -121,7 +121,7 @@ def get_library_albums(self, limit: int = 25, order: Optional[str] = None) -> li Gets the albums in the user's library. :param limit: Number of albums to return - :param order: Order of albums to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of albums to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of albums. Each item is in the following format:: @@ -156,7 +156,7 @@ def get_library_artists(self, limit: int = 25, order: Optional[str] = None) -> l Gets the artists of the songs in the user's library. :param limit: Number of artists to return - :param order: Order of artists to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of artists to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of artists. Each item is in the following format:: @@ -184,7 +184,7 @@ def get_library_subscriptions(self, limit: int = 25, order: Optional[str] = None Gets the artists the user has subscribed to. :param limit: Number of artists to return - :param order: Order of artists to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of artists to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of artists. Same format as :py:func:`get_library_artists` """ self._check_auth() @@ -203,7 +203,7 @@ def get_library_podcasts(self, limit: int = 25, order: Optional[str] = None) -> Get podcasts the user has added to the library :param limit: Number of podcasts to return - :param order: Order of podcasts to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of podcasts to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of podcasts. New Episodes playlist is the first podcast returned, but only if subscribed to relevant podcasts. Example:: @@ -249,7 +249,7 @@ def get_library_channels(self, limit: int = 25, order: Optional[str] = None) -> Get channels the user has added to the library :param limit: Number of channels to return - :param order: Order of channels to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of channels to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of channels. Example:: @@ -285,8 +285,8 @@ def get_history(self) -> list[dict]: Gets your play history in reverse chronological order :return: List of playlistItems, see :py:func:`get_playlist` - The additional property ``played`` indicates when the playlistItem was played - The additional property ``feedbackToken`` can be used to remove items with :py:func:`remove_history_items` + The additional property `played` indicates when the playlistItem was played + The additional property `feedbackToken` can be used to remove items with :py:func:`remove_history_items` """ self._check_auth() body = {"browseId": "FEmusic_history"} @@ -340,9 +340,9 @@ def rate_song(self, videoId: str, rating: str = "INDIFFERENT") -> Optional[dict] Rates a song ("thumbs up"/"thumbs down" interactions on YouTube Music) :param videoId: Video id - :param rating: One of 'LIKE', 'DISLIKE', 'INDIFFERENT' + :param rating: One of `LIKE`, `DISLIKE`, `INDIFFERENT` - | 'INDIFFERENT' removes the previous rating and assigns no rating + | `INDIFFERENT` removes the previous rating and assigns no rating :return: Full response """ @@ -373,9 +373,9 @@ def rate_playlist(self, playlistId: str, rating: str = "INDIFFERENT") -> dict: You can also dislike a playlist/album, which has an effect on your recommendations :param playlistId: Playlist id - :param rating: One of 'LIKE', 'DISLIKE', 'INDIFFERENT' + :param rating: One of `LIKE`, `DISLIKE`, `INDIFFERENT` - | 'INDIFFERENT' removes the playlist/album from the library + | `INDIFFERENT` removes the playlist/album from the library :return: Full response """ diff --git a/ytmusicapi/mixins/playlists.py b/ytmusicapi/mixins/playlists.py index 4cab22ad..69c2e2ee 100644 --- a/ytmusicapi/mixins/playlists.py +++ b/ytmusicapi/mixins/playlists.py @@ -24,7 +24,7 @@ def get_playlist( suggested playlist items (videos) contained in a "suggestions" key. 7 items are retrieved in each internal request. Default: 0 :return: Dictionary with information about the playlist. - The key ``tracks`` contains a List of playlistItem dictionaries + The key `tracks` contains a List of playlistItem dictionaries The result is in the following format:: @@ -221,7 +221,7 @@ def create_playlist( :param title: Playlist title :param description: Playlist description - :param privacy_status: Playlists can be 'PUBLIC', 'PRIVATE', or 'UNLISTED'. Default: 'PRIVATE' + :param privacy_status: Playlists can be `PUBLIC`, `PRIVATE`, or `UNLISTED`. Default: `PRIVATE` :param video_ids: IDs of songs to create the playlist with :param source_playlist: Another playlist whose songs should be added to the new playlist :return: ID of the YouTube playlist or full response if there was an error diff --git a/ytmusicapi/mixins/search.py b/ytmusicapi/mixins/search.py index 96074616..b60b353e 100644 --- a/ytmusicapi/mixins/search.py +++ b/ytmusicapi/mixins/search.py @@ -20,9 +20,9 @@ def search( Returns results within the provided category. :param query: Query string, i.e. 'Oasis Wonderwall' - :param filter: Filter for item types. Allowed values: ``songs``, ``videos``, ``albums``, ``artists``, ``playlists``, ``community_playlists``, ``featured_playlists``, ``uploads``. + :param filter: Filter for item types. Allowed values: `songs`, `videos`, `albums`, `artists`, `playlists`, `community_playlists`, `featured_playlists`, `uploads`. Default: Default search, including all types of items. - :param scope: Search scope. Allowed values: ``library``, ``uploads``. + :param scope: Search scope. Allowed values: `library`, `uploads`. Default: Search the public YouTube Music catalogue. Changing scope from the default will reduce the number of settable filters. Setting a filter that is not permitted will throw an exception. For uploads, no filter can be set. @@ -31,15 +31,15 @@ def search( Default: 20 :param ignore_spelling: Whether to ignore YTM spelling suggestions. If True, the exact search term will be searched for, and will not be corrected. - This does not have any effect when the filter is set to ``uploads``. + This does not have any effect when the filter is set to `uploads`. Default: False, will use YTM's default behavior of autocorrecting the search. :return: List of results depending on filter. resultType specifies the type of item (important for default search). albums, artists and playlists additionally contain a browseId, corresponding to - albumId, channelId and playlistId (browseId=``VL``+playlistId) + albumId, channelId and playlistId (browseId=`VL`+playlistId) Example list for default search with one result per resultType for brevity. Normally - there are 3 results per resultType and an additional ``thumbnails`` key:: + there are 3 results per resultType and an additional `thumbnails` key:: [ { @@ -268,9 +268,9 @@ def get_search_suggestions(self, query: str, detailed_runs=False) -> Union[list[ suggestion along with the complete text (like many search services usually bold the text typed by the user). Default: False, returns the list of search suggestions in plain text. - :return: List of search suggestion results depending on ``detailed_runs`` param. + :return: List of search suggestion results depending on `detailed_runs` param. - Example response when ``query`` is 'fade' and ``detailed_runs`` is set to ``False``:: + Example response when `query` is 'fade' and `detailed_runs` is set to `False`:: [ "faded", diff --git a/ytmusicapi/mixins/uploads.py b/ytmusicapi/mixins/uploads.py index a0c6ecb6..1ffe364f 100644 --- a/ytmusicapi/mixins/uploads.py +++ b/ytmusicapi/mixins/uploads.py @@ -75,7 +75,7 @@ def get_library_upload_albums(self, limit: Optional[int] = 25, order: Optional[s Gets the albums of uploaded songs in the user's library. :param limit: Number of albums to return. `None` retrives them all. Default: 25 - :param order: Order of albums to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of albums to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of albums as returned by :py:func:`get_library_albums` """ self._check_auth() @@ -96,7 +96,7 @@ def get_library_upload_artists( Gets the artists of uploaded songs in the user's library. :param limit: Number of artists to return. `None` retrieves them all. Default: 25 - :param order: Order of artists to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of artists to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of artists as returned by :py:func:`get_library_artists` """ self._check_auth() From 1b493b98a8338accd3b07e37e7b4338d57685f10 Mon Sep 17 00:00:00 2001 From: henrich26 Date: Wed, 16 Oct 2024 23:49:01 +0200 Subject: [PATCH 2/2] cleaned up more --- ytmusicapi/mixins/uploads.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ytmusicapi/mixins/uploads.py b/ytmusicapi/mixins/uploads.py index 1ffe364f..91843eb3 100644 --- a/ytmusicapi/mixins/uploads.py +++ b/ytmusicapi/mixins/uploads.py @@ -28,7 +28,7 @@ def get_library_upload_songs(self, limit: Optional[int] = 25, order: Optional[st Returns a list of uploaded songs :param limit: How many songs to return. `None` retrieves them all. Default: 25 - :param order: Order of songs to return. Allowed values: 'a_to_z', 'z_to_a', 'recently_added'. Default: Default order. + :param order: Order of songs to return. Allowed values: `a_to_z`, `z_to_a`, `recently_added`. Default: Default order. :return: List of uploaded songs. Each item is in the following format::