From bb4bf4d3e1f86cdb3d8469af8a458b2cd02966b9 Mon Sep 17 00:00:00 2001 From: Hendrik Horstmann <65970327+heinrich26@users.noreply.github.com> Date: Tue, 17 Dec 2024 21:35:44 +0100 Subject: [PATCH] Docstring cleanup (#665) * Cleaned up docstrings * cleaned up more --------- Co-authored-by: sigma67 --- docs/source/faq.rst | 2 +- tests/README.rst | 2 +- ytmusicapi/auth/oauth/credentials.py | 10 +++++----- ytmusicapi/auth/oauth/token.py | 4 ++-- ytmusicapi/mixins/browsing.py | 14 +++++++------- ytmusicapi/mixins/explore.py | 2 +- ytmusicapi/mixins/library.py | 22 +++++++++++----------- ytmusicapi/mixins/playlists.py | 4 ++-- ytmusicapi/mixins/podcasts.py | 8 ++++---- ytmusicapi/mixins/search.py | 2 +- ytmusicapi/mixins/uploads.py | 12 ++++++------ ytmusicapi/mixins/watch.py | 4 ++-- 12 files changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/source/faq.rst b/docs/source/faq.rst index f674d509..239f7c8e 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -127,7 +127,7 @@ reached at least the ``limit`` parameter, and return all of these results. Which values can I use for languages? ************************************* -The `language` parameter determines the language of the returned results. +The ``language`` parameter determines the language of the returned results. ``ytmusicapi`` only supports a subset of the languages supported by YouTube Music, as translations need to be done manually. Contributions are welcome, see `here for instructions `__. diff --git a/tests/README.rst b/tests/README.rst index e4a1a8c4..703f7e4d 100644 --- a/tests/README.rst +++ b/tests/README.rst @@ -4,7 +4,7 @@ Tests use the ``unittest`` framework. Each function has a corresponding unittest Sometimes there is a single unittest for multiple functions to ensure there are no permanent changes in the user's YouTube account (i.e. subscribe and unsubscribe). -Note that there must be a ``browser.json`` and ``oauth.json`` in the `tests` folder to run all authenticated tests. +Note that there must be a ``browser.json`` and ``oauth.json`` in the ``tests`` folder to run all authenticated tests. These two files can be easily obtained as the default outputs of running the following commands respectively: .. code-block:: bash diff --git a/ytmusicapi/auth/oauth/credentials.py b/ytmusicapi/auth/oauth/credentials.py index 3ae21126..da08caa9 100644 --- a/ytmusicapi/auth/oauth/credentials.py +++ b/ytmusicapi/auth/oauth/credentials.py @@ -51,9 +51,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. """ @@ -112,10 +112,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..e1761297 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..477c1ec7 100644 --- a/ytmusicapi/mixins/browsing.py +++ b/ytmusicapi/mixins/browsing.py @@ -284,8 +284,8 @@ 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 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. :return: List of albums in the format of :py:func:`get_library_albums`, except artists key is missing. @@ -469,7 +469,7 @@ def get_album_browse_id(self, audioPlaylistId: str) -> Optional[str]: Get an album's browseId based on its audioPlaylistId :param audioPlaylistId: id of the audio playlist (starting with `OLAK5uy_`) - :return: browseId (starting with `MPREb_`) + :return: browseId (starting with ``MPREb_``) """ params = {"list": audioPlaylistId} response = self._send_get_request(YTM_DOMAIN + "/playlist", params) @@ -760,7 +760,7 @@ def get_song_related(self, browseId: str): Gets related content for a song. Equivalent to the content shown in the "Related" tab of the watch panel. - :param browseId: The `related` key in the `get_watch_playlist` response. + :param browseId: The ``related`` key in the ``get_watch_playlist`` response. Example:: @@ -840,7 +840,7 @@ def get_lyrics(self, browseId: str) -> dict: """ Returns lyrics of a song or video. - :param browseId: Lyrics browse id obtained from `get_watch_playlist` + :param browseId: Lyrics browse id obtained from ``get_watch_playlist`` :return: Dictionary with song lyrics. Example:: @@ -881,11 +881,11 @@ def get_basejs_url(self): def get_signatureTimestamp(self, url: Optional[str] = None) -> int: """ Fetch the `base.js` script from YouTube Music and parse out the - `signatureTimestamp` for use with :py:func:`get_song`. + ``signatureTimestamp`` for use with :py:func:`get_song`. :param url: Optional. Provide the URL of the `base.js` script. If this isn't specified a call will be made to :py:func:`get_basejs_url`. - :return: `signatureTimestamp` string + :return: ``signatureTimestamp`` string """ if url is None: url = self.get_basejs_url() diff --git a/ytmusicapi/mixins/explore.py b/ytmusicapi/mixins/explore.py index 1b64b668..5b337176 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 99443326..c82cde26 100644 --- a/ytmusicapi/mixins/library.py +++ b/ytmusicapi/mixins/library.py @@ -15,7 +15,7 @@ def get_library_playlists(self, limit: Optional[int] = 25) -> list[dict]: """ Retrieves the playlists in the user's library. - :param limit: Number of playlists to retrieve. `None` retrieves them all. + :param limit: Number of playlists to retrieve. ``None`` retrieves them all. :return: List of owned playlists. Each item is in the following format:: @@ -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:: @@ -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..b4dde402 100644 --- a/ytmusicapi/mixins/playlists.py +++ b/ytmusicapi/mixins/playlists.py @@ -18,7 +18,7 @@ def get_playlist( Returns a list of playlist items :param playlistId: Playlist id - :param limit: How many songs to return. `None` retrieves them all. Default: 100 + :param limit: How many songs to return. ``None`` retrieves them all. Default: 100 :param related: Whether to fetch 10 related playlists or not. Default: False :param suggestions_limit: How many suggestions to return. The result is a list of suggested playlist items (videos) contained in a "suggestions" key. @@ -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/podcasts.py b/ytmusicapi/mixins/podcasts.py index 7ca02309..ceac29a6 100644 --- a/ytmusicapi/mixins/podcasts.py +++ b/ytmusicapi/mixins/podcasts.py @@ -99,10 +99,10 @@ def get_podcast(self, playlistId: str, limit: Optional[int] = 100) -> dict: .. note:: - To add a podcast to your library, you need to call `rate_playlist` on it + To add a podcast to your library, you need to call ``rate_playlist`` on it :param playlistId: Playlist id - :param limit: How many songs to return. `None` retrieves them all. Default: 100 + :param limit: How many songs to return. ``None`` retrieves them all. Default: 100 :return: Dict with podcast information Example:: @@ -163,8 +163,8 @@ def get_episode(self, videoId: str) -> dict: .. note:: - To save an episode, you need to call `add_playlist_items` to add - it to the `SE` (saved episodes) playlist. + To save an episode, you need to call ``add_playlist_items`` to add + it to the ``SE`` (saved episodes) playlist. :param videoId: browseId (MPED..) or videoId for a single episode :return: Dict containing information about the episode diff --git a/ytmusicapi/mixins/search.py b/ytmusicapi/mixins/search.py index 08399e12..0c831b80 100644 --- a/ytmusicapi/mixins/search.py +++ b/ytmusicapi/mixins/search.py @@ -36,7 +36,7 @@ def 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:: diff --git a/ytmusicapi/mixins/uploads.py b/ytmusicapi/mixins/uploads.py index a0c6ecb6..feafbbd8 100644 --- a/ytmusicapi/mixins/uploads.py +++ b/ytmusicapi/mixins/uploads.py @@ -27,8 +27,8 @@ 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 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. :return: List of uploaded songs. Each item is in the following format:: @@ -74,8 +74,8 @@ 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 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. :return: List of albums as returned by :py:func:`get_library_albums` """ self._check_auth() @@ -95,8 +95,8 @@ 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 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. :return: List of artists as returned by :py:func:`get_library_artists` """ self._check_auth() diff --git a/ytmusicapi/mixins/watch.py b/ytmusicapi/mixins/watch.py index 6a43f885..6b7770d4 100644 --- a/ytmusicapi/mixins/watch.py +++ b/ytmusicapi/mixins/watch.py @@ -20,8 +20,8 @@ def get_watch_playlist( Get a watch list of tracks. This watch playlist appears when you press play on a track in YouTube Music. - Please note that the `INDIFFERENT` likeStatus of tracks returned by this - endpoint may be either `INDIFFERENT` or `DISLIKE`, due to ambiguous data + Please note that the ``INDIFFERENT`` likeStatus of tracks returned by this + endpoint may be either ``INDIFFERENT`` or ``DISLIKE``, due to ambiguous data returned by YouTube Music. :param videoId: videoId of the played video