Skip to content

Commit

Permalink
Docstring cleanup (#665)
Browse files Browse the repository at this point in the history 
* Cleaned up docstrings

* cleaned up more

---------

Co-authored-by: sigma67 <[email protected]>
  • Loading branch information
@heinrich26 @sigma67
heinrich26 and sigma67 authored Dec 17, 2024
1 parent 7441114 commit bb4bf4d
Show file tree
Hide file tree
Showing 12 changed files with 43 additions and 43 deletions.
2 changes: 1 addition & 1 deletion docs/source/faq.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/sigma67/ytmusicapi/tree/master/ytmusicapi/locales>`__.

Expand Down
2 changes: 1 addition & 1 deletion tests/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions ytmusicapi/auth/oauth/credentials.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""
Expand Down Expand Up @@ -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(
Expand Down
4 changes: 2 additions & 2 deletions ytmusicapi/auth/oauth/token.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
14 changes: 7 additions & 7 deletions ytmusicapi/mixins/browsing.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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()
Expand Down
2 changes: 1 addition & 1 deletion ytmusicapi/mixins/explore.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
22 changes: 11 additions & 11 deletions ytmusicapi/mixins/library.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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()
Expand All @@ -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::
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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
"""
Expand Down Expand Up @@ -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
"""
Expand Down
4 changes: 2 additions & 2 deletions ytmusicapi/mixins/playlists.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions ytmusicapi/mixins/podcasts.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion ytmusicapi/mixins/search.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
12 changes: 6 additions & 6 deletions ytmusicapi/mixins/uploads.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down Expand Up @@ -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()
Expand All @@ -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()
Expand Down
4 changes: 2 additions & 2 deletions ytmusicapi/mixins/watch.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit bb4bf4d

Please sign in to comment.