From 742d60d18c0880b3ffa36a74b045de030f23ff19 Mon Sep 17 00:00:00 2001 From: Gleb Liutsko Date: Mon, 14 Nov 2022 07:30:29 +0000 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Добавление документации для Функции: convert_track_id_to_number, get_sign_request Классы: Sign, TrackLyrics, LyricsMajor Методы: Client.tracks_lyrics --- .../yandex_music.track.lyrics_major.rst | 7 +++++++ docs/source/yandex_music.track.rst | 2 ++ .../yandex_music.track.track_lyrics.rst | 7 +++++++ .../yandex_music.utils.convert_track_id.rst | 7 +++++++ docs/source/yandex_music.utils.rst | 2 ++ .../yandex_music.utils.sign_request.rst | 7 +++++++ yandex_music/client.py | 8 ++++++- yandex_music/client_async.py | 8 ++++++- yandex_music/track/lyrics_major.py | 18 +++++++++++++++- yandex_music/track/track_lyrics.py | 21 +++++++++++++++++-- yandex_music/utils/convert_track_id.py | 14 ++++++++++++- yandex_music/utils/sign_request.py | 18 ++++++++++++++-- 12 files changed, 111 insertions(+), 8 deletions(-) create mode 100644 docs/source/yandex_music.track.lyrics_major.rst create mode 100644 docs/source/yandex_music.track.track_lyrics.rst create mode 100644 docs/source/yandex_music.utils.convert_track_id.rst create mode 100644 docs/source/yandex_music.utils.sign_request.rst diff --git a/docs/source/yandex_music.track.lyrics_major.rst b/docs/source/yandex_music.track.lyrics_major.rst new file mode 100644 index 0000000..1c717ab --- /dev/null +++ b/docs/source/yandex_music.track.lyrics_major.rst @@ -0,0 +1,7 @@ +yandex\_music.track.lyrics\_major +================================= + +.. automodule:: yandex_music.track.lyrics_major + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/yandex_music.track.rst b/docs/source/yandex_music.track.rst index b5f395d..019e09f 100644 --- a/docs/source/yandex_music.track.rst +++ b/docs/source/yandex_music.track.rst @@ -13,9 +13,11 @@ Submodules :maxdepth: 4 yandex_music.track.licence_text_part + yandex_music.track.lyrics_major yandex_music.track.major yandex_music.track.meta_data yandex_music.track.normalization yandex_music.track.poetry_lover_match yandex_music.track.track + yandex_music.track.track_lyrics yandex_music.track.tracks_similar diff --git a/docs/source/yandex_music.track.track_lyrics.rst b/docs/source/yandex_music.track.track_lyrics.rst new file mode 100644 index 0000000..49108cd --- /dev/null +++ b/docs/source/yandex_music.track.track_lyrics.rst @@ -0,0 +1,7 @@ +yandex\_music.track.track\_lyrics +================================= + +.. automodule:: yandex_music.track.track_lyrics + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/yandex_music.utils.convert_track_id.rst b/docs/source/yandex_music.utils.convert_track_id.rst new file mode 100644 index 0000000..a3c3e2b --- /dev/null +++ b/docs/source/yandex_music.utils.convert_track_id.rst @@ -0,0 +1,7 @@ +yandex\_music.utils.convert\_track\_id +====================================== + +.. automodule:: yandex_music.utils.convert_track_id + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/yandex_music.utils.rst b/docs/source/yandex_music.utils.rst index 35e7cc1..9a6bdfb 100644 --- a/docs/source/yandex_music.utils.rst +++ b/docs/source/yandex_music.utils.rst @@ -12,7 +12,9 @@ Submodules .. toctree:: :maxdepth: 4 + yandex_music.utils.convert_track_id yandex_music.utils.difference yandex_music.utils.request yandex_music.utils.request_async yandex_music.utils.response + yandex_music.utils.sign_request diff --git a/docs/source/yandex_music.utils.sign_request.rst b/docs/source/yandex_music.utils.sign_request.rst new file mode 100644 index 0000000..2fa57bc --- /dev/null +++ b/docs/source/yandex_music.utils.sign_request.rst @@ -0,0 +1,7 @@ +yandex\_music.utils.sign\_request +================================= + +.. automodule:: yandex_music.utils.sign_request + :members: + :undoc-members: + :show-inheritance: diff --git a/yandex_music/client.py b/yandex_music/client.py index a9c5f8e..8d2d42f 100644 --- a/yandex_music/client.py +++ b/yandex_music/client.py @@ -572,15 +572,21 @@ class Client(YandexMusicObject): ) -> Optional[TrackLyrics]: """Получение текста трека. + Note: + Известные значения для аргумента format: + - `LRC` - формат с временными метками. + - `TEXT` - простой текст. + Args: track_id (:obj:`str` | :obj:`int`): Уникальный идентификатор трека. format (:obj:`str`): Формат текста. **kwargs (:obj:`dict`, optional): Произвольные аргументы (будут переданы в запрос). Returns: - TODO + :obj:`yandex_music.TrackLyrics` | :obj:`None`: Информация о тексте трека. Raises: + :class:`yandex_music.exceptions.NotFoundError`: Текст у трека отсутствует. :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки. """ diff --git a/yandex_music/client_async.py b/yandex_music/client_async.py index 37d48a3..4cfa253 100644 --- a/yandex_music/client_async.py +++ b/yandex_music/client_async.py @@ -578,15 +578,21 @@ class ClientAsync(YandexMusicObject): ) -> Optional[TrackLyrics]: """Получение текста трека. + Note: + Известные значения для аргумента format: + - `LRC` - формат с временными метками. + - `TEXT` - простой текст. + Args: track_id (:obj:`str` | :obj:`int`): Уникальный идентификатор трека. format (:obj:`str`): Формат текста. **kwargs (:obj:`dict`, optional): Произвольные аргументы (будут переданы в запрос). Returns: - TODO + :obj:`yandex_music.TrackLyrics` | :obj:`None`: Информация о тексте трека. Raises: + :class:`yandex_music.exceptions.NotFoundError`: Текст у трека отсутствует. :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки. """ diff --git a/yandex_music/track/lyrics_major.py b/yandex_music/track/lyrics_major.py index 8cafe71..d1445fe 100644 --- a/yandex_music/track/lyrics_major.py +++ b/yandex_music/track/lyrics_major.py @@ -10,7 +10,14 @@ if TYPE_CHECKING: @model class LyricsMajor(YandexMusicObject): - """TODO""" + """Класс, представляющий сервис-источник текстов к трекам. + + Args: + id (:obj:`int`): Уникальный идентификатор сервиса. + name (:obj:`str`): Имя сервиса. + pretty_name (:obj:`str`): Человекочитаемое имя сервиса. + client (:obj:`yandex_music.Client`, optional): Клиент Yandex Music. + """ id: int name: str @@ -22,6 +29,15 @@ class LyricsMajor(YandexMusicObject): @classmethod def de_json(cls, data: dict, client: 'Client') -> Optional['LyricsMajor']: + """Десериализация объекта. + + Args: + data (:obj:`dict`): Поля и значения десериализуемого объекта. + client (:obj:`yandex_music.Client`, optional): Клиент Yandex Music. + + Returns: + :obj:`yandex_music.LyricsMajor`: Сервис-источник текстов к трекам. + """ if not data: return None diff --git a/yandex_music/track/track_lyrics.py b/yandex_music/track/track_lyrics.py index 13882f4..8afb76b 100644 --- a/yandex_music/track/track_lyrics.py +++ b/yandex_music/track/track_lyrics.py @@ -10,7 +10,16 @@ if TYPE_CHECKING: @model class TrackLyrics(YandexMusicObject): - """TODO""" + """Класс, представляющий текст трека. + + Attributes: + download_url (:obj:`str`): Ссылка на скачивание текста. + lyric_id (:obj:`int`): Уникальный идентификатор текста. + external_lyric_id (:obj:`str`): Уникальный идентификатор текста на сервисе предоставляющий текст. + writers (:obj:`list` из :obj:`str`): Авторы текста. + major (:obj:`yandex_music.LyricsMajor`): Сервис, откуда был получен текст. + client (:obj:`yandex_music.Client`, optional): Клиент Yandex Music. + """ download_url: str lyric_id: int @@ -27,7 +36,15 @@ class TrackLyrics(YandexMusicObject): @classmethod def de_json(cls, data: dict, client: 'Client') -> Optional['TrackLyrics']: - """TODO""" + """Десериализация объекта. + + Args: + data (:obj:`dict`): Поля и значения десериализуемого объекта. + client (:obj:`yandex_music.Client`, optional): Клиент Yandex Music. + + Returns: + :obj:`yandex_music.TrackLyrics`: Текст трека. + """ if not data: return None diff --git a/yandex_music/utils/convert_track_id.py b/yandex_music/utils/convert_track_id.py index 113e8b4..70fb403 100644 --- a/yandex_music/utils/convert_track_id.py +++ b/yandex_music/utils/convert_track_id.py @@ -2,7 +2,19 @@ from typing import Union def convert_track_id_to_number(track_id: Union[str, int]) -> int: - """TODO""" + """Переобразование идентификатора трека в номерной формат. + + Note: + Преобразует ID в формате "{track_id}:{album}" в track_id. + + Преобразует ID в формате "{track_id}" в track_id. + + Args: + track_id (:obj:`str` | :obj:`int`): Уникальный идентификатора трека. + + Returns: + :obj:`int`: Уникальный идентификатора трека в номерном формате. + """ if isinstance(track_id, str): track_id = int(track_id.split(':')[0]) diff --git a/yandex_music/utils/sign_request.py b/yandex_music/utils/sign_request.py index 42ab75f..78b5116 100644 --- a/yandex_music/utils/sign_request.py +++ b/yandex_music/utils/sign_request.py @@ -9,18 +9,32 @@ from yandex_music.utils.convert_track_id import convert_track_id_to_number DEFAULT_SIGN_KEY = 'p93jhgh689SBReK6ghtw62' +""":obj:`str`: Ключ для подписи из Android приложения.""" @dataclass class Sign: - """TODO""" + """Подпись запроса. + + Attributes: + timestamp (:obj:`int`): Время создания подписи. + value (:obj:`str`): Подпись. + """ timestamp: int value: str def get_sign_request(track_id: Union[int, str], key: str = DEFAULT_SIGN_KEY) -> Sign: - """TODO""" + """Создает подпись для запроса. + + Args: + track_id (:obj:`str` | :obj:`int`): Уникальный идентификатора трека. + key (:obj:`str`, optional): Ключ для подписи. + + Returns: + :obj:`Sign`: Подпись. + """ track_id = convert_track_id_to_number(track_id) timestamp = int(datetime.datetime.now().timestamp())