Merge pull request #282 from MarshalX/issue-67

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

docs/source/yandex_music.utils.difference.rst

@@ -1,6 +1,11 @@
 yandex_music.utils.difference.Difference
 ========================================
 
+.. autoclass:: yandex_music.utils.difference.Operation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. autoclass:: yandex_music.utils.difference.Difference
     :members:
     :undoc-members:

yandex_music/utils/difference.py

@@ -21,13 +21,41 @@ class Operation(Enum):
 
 
 class Difference:
+    """Класс, представляющий обёртку над созданием данных для запроса изменения плейлиста.
+
+    Note:
+        Результатом является перечень (массив) операций, которые будут применены к плейлисту.
+
+        Конечной разницей (набором операций) является JSON, который будет отправлен в теле запроса.
+
+    Attributes:
+        operations (:obj:`list` из :obj:`dict`): Перечень операция для изменения плейлиста.
+    """
+
     def __init__(self):
         self.operations = []
 
-    def to_json(self):
+    def to_json(self) -> str:
+        """Сериализация всех операций над плейлистом.
+
+        Returns:
+            :obj:`str`: Сформированное тело для запроса.
+        """
         return json.dumps(self.operations, ensure_ascii=not ujson)
 
-    def add_delete(self, from_, to):
+    def add_delete(self, from_: int, to: int) -> 'Difference':
+        """Добавление операции удаления.
+
+        Note:
+            Передаётся диапазон для удаления треков.
+
+        Args:
+            from_ (:obj:`int`): С какого индекса.
+            to (:obj:`int`): По какой индекс.
+
+        Returns:
+            :obj:`yandex_music.utils.difference.Difference`: Набор операций над плейлистом.
+        """
         operation = {
             'op': Operation.DELETE.value,
             'from': from_,
@@ -37,7 +65,20 @@ class Difference:
         self.operations.append(operation)
         return self
 
-    def add_insert(self, at, tracks: Union[dict, List[dict]]):
+    def add_insert(self, at: int, tracks: Union[dict, List[dict]]) -> 'Difference':
+        """Добавление операции вставки.
+
+        Note:
+            В `tracks` передаётся словарь с двумя ключами: `id`, `album_id`. Это нужно для формирования операции.
+
+        Args:
+            at (:obj:`int`): Индекс для вставки.
+            tracks (:obj:`dict` | :obj:`list: из :obj:`dict`): Словарь уникальными идентификаторами треков.
+
+        Returns:
+            :obj:`yandex_music.utils.difference.Difference`: Набор операций над плейлистом.
+        """
+        # TODO принимать TrackId, а так же строку и сплитить её по ":". При отсутствии album_id кидать исключение.
         if not isinstance(tracks, list):
             tracks = [tracks]