Merge pull request #283 from MarshalX/issue-65

Документация класса Request

docs/source/yandex_music.utils.request.rst

@@ -3,4 +3,6 @@ yandex_music.utils.request.Request
 
 .. autoclass:: yandex_music.utils.request.Request
     :members:
+    :undoc-members:
+    :private-members:
     :show-inheritance:

yandex_music/utils/request.py

@@ -2,11 +2,12 @@ import re
 import logging
 import builtins
 
+from typing import TYPE_CHECKING, Optional, Union
+
 # Не используется ujson из-за отсутствия в нём object_hook'a
 # Отправка вообще application/x-www-form-urlencoded, а не JSON'a
 # https://github.com/psf/requests/blob/master/requests/models.py#L508
 import json
-from typing import Optional
 
 import requests
 
@@ -15,6 +16,10 @@ from yandex_music.utils.response import Response
 from yandex_music.exceptions import Unauthorized, BadRequest, NetworkError, YandexMusicError, CaptchaRequired, \
     CaptchaWrong
 
+if TYPE_CHECKING:
+    from yandex_music import Client
+
+
 USER_AGENT = 'Yandex-Music-API'
 HEADERS = {
     'X-Yandex-Music-Client': 'YandexMusicAndroid/23020055',
@@ -26,7 +31,7 @@ logging.getLogger('urllib3').setLevel(logging.WARNING)
 
 
 class Request:
-    """Вспомогателньный класс для yandex_music представляющий методы для выполнения POST и GET запросов, скачивания
+    """Вспомогательный класс для yandex_music, представляющий методы для выполнения POST и GET запросов, скачивания
     файлов.
 
     Args:
@@ -45,10 +50,26 @@ class Request:
 
         self.proxies = {'http': proxy_url, 'https': proxy_url} if proxy_url else None
 
-    def set_authorization(self, token):
+    def set_authorization(self, token: str) -> None:
+        """Добавляет заголовок авторизации для каждого запроса.
+
+        Note:
+            Используется при передаче своего экземпляра Request'a клиенту.
+
+        Args:
+            token (:obj:`str`): OAuth токен.
+        """
         self.headers.update({'Authorization': f'OAuth {token}'})
 
-    def set_and_return_client(self, client):
+    def set_and_return_client(self, client) -> 'Client':
+        """Принимает клиент и присваивает его текущему объекту. При наличии авторизации добавляет заголовок.
+
+        Args:
+            client (:obj:`yandex_music.Client`): Клиент Yandex Music.
+
+        Returns:
+            :obj:`yandex_music.Client`: Клиент Yandex Music.
+        """
         self.client = client
 
         if self.client and self.client.token:
@@ -57,12 +78,33 @@ class Request:
         return self.client
 
     @staticmethod
-    def _convert_camel_to_snake(text):
+    def _convert_camel_to_snake(text: str) -> str:
+        """Конвертация CamelCase в SnakeCase.
+
+        Args:
+            text (:obj:`str`): Название переменной в CamelCase.
+
+        Returns:
+            :obj:`str`: Название переменной в SnakeCase.
+        """
         s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', text)
         return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
 
     @staticmethod
-    def _object_hook(obj):
+    def _object_hook(obj: dict) -> dict:
+        """Нормализация имён переменных пришедших с API.
+
+        Note:
+            В названии переменной заменяет "-" на "_", конвертирует в SnakeCase, если название является
+            зарезервированным именем или "client" - добавляет "_" в конец. Если название переменной начинается с цифры -
+            добавляет в начало "_".
+
+        Args:
+            obj (:obj:`dict`): Словарь, где ключ название переменной, а значение - содержимое.
+
+        Returns:
+            :obj:`dict`: Тот же словарь, что и на входе, но с нормализованными ключами.
+        """
         cleaned_object = {}
         for key, value in obj.items():
             key = Request._convert_camel_to_snake(key.replace('-', '_'))
@@ -76,7 +118,21 @@ class Request:
 
         return cleaned_object
 
-    def _parse(self, json_data) -> Optional[Response]:
+    def _parse(self, json_data: bytes) -> Optional[Response]:
+        """Разбор ответа от API.
+
+        Note:
+            Если данные отсутствуют в `result`, то переформировывает ответ используя данные из корня.
+
+        Args:
+            json_data (:obj:`bytes`): Ответ от API.
+
+        Returns:
+            :obj:`yandex_music.utils.response.Response`: Ответ API.
+
+        Raises:
+            :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки.
+        """
         try:
             decoded_s = json_data.decode('utf-8')
             data = json.loads(decoded_s, object_hook=Request._object_hook)
@@ -94,6 +150,27 @@ class Request:
         return Response.de_json(data, self.client)
 
     def _request_wrapper(self, *args, **kwargs):
+        """Обёртка над запросом библиотеки `requests`.
+
+        Note:
+            Добавляет необходимые заголовки для запроса, обрабатывает статус коды, следит за таймаутом, кидает
+            необходимые исключения, возвращает ответ. Передаёт пользовательские аргументы в запрос.
+
+        Args:
+            *args: Произвольные аргументы для `requests.request`.
+            **kwargs: Произвольные ключевые аргументы для `requests.request`.
+
+        Returns:
+            :obj:`yandex_music.utils.response.Response`: Ответ API.
+
+        Raises:
+            :class:`TimeoutError`: При превышении времени ожидания.
+            :class:`yandex_music.exceptions.Unauthorized`: При невалидном токене, долгом ожидании прямой ссылки на файл.
+            :class:`yandex_music.exceptions.BadRequest`: При неправильном запросе.
+            :class:`yandex_music.exceptions.NetworkError`: При проблемах с сетью.
+            :class:`yandex_music.exceptions.CaptchaWrong`: При неправильной капче.
+            :class:`yandex_music.exceptions.CaptchaRequired`: При необходимости пройти капчу.
+        """
         if 'headers' not in kwargs:
             kwargs['headers'] = {}
 
@@ -127,22 +204,86 @@ class Request:
         else:
             raise NetworkError(f'{message} ({resp.status_code})')
 
-    def get(self, url, params=None, timeout=5, *args, **kwargs):
+    def get(self, url: str, params: dict = None, timeout: Union[int, float] = 5, *args, **kwargs):
+        """Отправка GET запроса.
+
+        Args:
+            url (:obj:`str`): Адрес для запроса.
+            params (:obj:`str`): GET параметры для запроса.
+            timeout (:obj:`int` | :obj:`float`): Используется как время ожидания ответа от сервера вместо указанного
+                при создании пула.
+            *args: Произвольные аргументы для `requests.request`.
+            **kwargs: Произвольные ключевые аргументы для `requests.request`.
+
+        Returns:
+            :obj:`yandex_music.utils.response.Response`: Ответ API.
+
+        Raises:
+            :class:`TimeoutError`: При превышении времени ожидания.
+            :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки.
+        """
         result = self._request_wrapper('GET', url, params=params, headers=self.headers, proxies=self.proxies,
                                        timeout=timeout, *args, **kwargs)
 
         return self._parse(result.content).result
 
     def post(self, url, data=None, timeout=5, *args, **kwargs):
+        """Отправка POST запроса.
+
+        Args:
+            url (:obj:`str`): Адрес для запроса.
+            data (:obj:`str`): POST тело запроса.
+            timeout (:obj:`int` | :obj:`float`): Используется как время ожидания ответа от сервера вместо указанного
+                при создании пула.
+            *args: Произвольные аргументы для `requests.request`.
+            **kwargs: Произвольные ключевые аргументы для `requests.request`.
+
+        Returns:
+            :obj:`yandex_music.utils.response.Response`: Ответ API.
+
+        Raises:
+            :class:`TimeoutError`: При превышении времени ожидания.
+            :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки.
+        """
         result = self._request_wrapper('POST', url, headers=self.headers, proxies=self.proxies, data=data,
                                        timeout=timeout, *args, **kwargs)
 
         return self._parse(result.content).result
 
     def retrieve(self, url, timeout=5, *args, **kwargs):
+        """Отправка GET запроса и получение содержимого без обработки (парсинга).
+
+        Args:
+            url (:obj:`str`): Адрес для запроса.
+            timeout (:obj:`int` | :obj:`float`): Используется как время ожидания ответа от сервера вместо указанного
+                при создании пула.
+            *args: Произвольные аргументы для `requests.request`.
+            **kwargs: Произвольные ключевые аргументы для `requests.request`.
+
+        Returns:
+            :obj:`Response`: Экземляр объекта ответа библиотеки `requests`.
+
+        Raises:
+            :class:`TimeoutError`: При превышении времени ожидания.
+            :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки.
+        """
         return self._request_wrapper('GET', url, proxies=self.proxies, timeout=timeout, *args, **kwargs)
 
     def download(self, url, filename, timeout=5, *args, **kwargs):
+        """Отправка запроса на получение содержимого и его запись в файл.
+
+        Args:
+            url (:obj:`str`): Адрес для запроса.
+            filename (:obj:`str`): Путь и(или) название файла вместе с расширением.
+            timeout (:obj:`int` | :obj:`float`): Используется как время ожидания ответа от сервера вместо указанного
+                при создании пула.
+            *args: Произвольные аргументы для `requests.request`.
+            **kwargs: Произвольные ключевые аргументы для `requests.request`.
+
+        Raises:
+            :class:`TimeoutError`: При превышении времени ожидания.
+            :class:`yandex_music.exceptions.YandexMusicError`: Базовое исключение библиотеки.
+        """
         result = self.retrieve(url, timeout=timeout, *args, *kwargs)
         with open(filename, 'wb') as f:
             f.write(result.content)