diff --git a/docs/source/yandex_music.utils.difference.rst b/docs/source/yandex_music.utils.difference.rst index ae4fbdf..e1e9af7 100644 --- a/docs/source/yandex_music.utils.difference.rst +++ b/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: diff --git a/yandex_music/utils/difference.py b/yandex_music/utils/difference.py index 462455a..4b5c577 100644 --- a/yandex_music/utils/difference.py +++ b/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]