yandex-music 0.1.2

Делаю то, что по определённым причинам не сделала компания Yandex.

[Alpha] Неофициальная Python библиотека для API Yandex Music

Делаю то, что по определённым причинам не сделала компания Yandex.

Маленькое сообщество разработчиков общаются и помогают друг другу в Telegram чатике, присоединяйтесь!

Содержание

• Введение

  1. Доступ к вашим данным на Яндексе

• Установка

• Начало работы

  1. Изучение по примерам

  2. Логирование

  3. Документация

• Получение помощи

• Реализации на других языках

  1. C#

  2. PHP

  3. JavaScript

• Разработанные проекты

  1. Плагин для Kodi

  2. Telegram бот-клиент

• Благодарность

• Лицензия

Введение

Эта библиотека предоставляется Python интерфейс для никем незадокументированного и сделанного только для себя API Яндекс Музыки.

Она совместима с версиями Python 3.6+.

В дополнение к реализации чистого API данная библиотека имеет ряд классов-обёрток объектов высокого уровня дабы сделать разработку клиентов и скриптов простой и понятной.

Доступ к вашим данным на Яндексе

Значения констант CLIENT_ID и CLIENT_SECRET позаимствовано у официального приложения-клиента сервиса Яндекс.Музыка из магазина Microsoft Store. Так как API является закрытым и используется только внутри компании Яндекс сейчас невозможно зарегистрировать своё собственное приложение на oauth.yandex.ru, а следовательно, использовать свои значения констант.

Установка

Библиотека находится в стадии разработки

Вы можете установить или обновить yandex-music-api при помощи:

$ pip install yandex-music --upgrade

Или Вы можете установить из исходного кода с помощью:

$ git clone https://github.com/MarshalX/yandex-music-api --recursive
$ cd yandex-music-api
$ python setup.py install

Начало работы

Приступив к работе первым делом необходимо создать экземпляр клиента.

Инициализация клиента:

from yandex_music.client import Client

client = Client()

Для доступа к своим личным данным следует авторизоваться. Это можно осуществить через OAuth токен или логин с паролем.

Авторизация по логину и паролю:

from yandex_music.client import Client

client = Client.from_credentials('[e-mail]', 'password')

Авторизация по токену:

from yandex_music.client import Client

client = Client.from_token('token')
# или
client = Client('token')

После успешного создания клиента Вы вольны в выборе необходимого метода из API. Все они доступны у объекта класса Client. Подробнее в методах клиента в документации.

Пример получения первого трека из плейлиста “Мне нравится” и его загрузка:

from yandex_music.client import Client

client = Client.from_credentials('[e-mail]', 'password')
client.users_likes_tracks()[0].track.download('example.mp3')

В примере выше клиент получает список треков которые были отмечены как понравившиеся. API возвращает объект TracksList в котором содержится список с треками класса TrackShort. Данные класс содержит наиважнейшую информацию о треке и никаких подробностей, поэтому для получения полной версии трека со всей информацией необходимо обратиться к свойству track. Затем можно скачать трек методом download().

Пример получения треков по ID:

from yandex_music.client import Client

client = Client()
client.tracks(['10994777:1193829', '40133452:5206873', '48966383:6693286', '51385674:7163467'])

В качестве ID трека выступает его уникальный номер и номер альбома. Первым треком из примера является следующий трек: music.yandex.ru/album/1193829/track/10994777

Выполнение запросов с использование прокси:

from yandex_music.utils.request import Request
from yandex_music.client import Client

request = Request(proxy_url='socks5://user:password@host:port')
client = Client(request=request)

Примеры proxy url:

• socks5://user:password@host:port

• http://host:port

• https://host:port

• http://user:password@host

Больше примеров тут: proxies - advanced usage - requests

Пример инициализации клиента с обработкой капчи:

def init_client():
    client = captcha_key = captcha_answer = None
    while not client:
        try:
            client = Client.from_credentials('login', 'pass', captcha_answer, captcha_key)
        except Captcha as e:
            e.captcha.download('captcha.png')

            captcha_key = e.captcha.x_captcha_key
            captcha_answer = input('Число с картинки: ')

    return client

Пример инициализации клиента с обработкой капчи при помощи callback-функции:

def proc_captcha(captcha):
    captcha.download('captcha.png')
    return input('Число с картинки: ')

client = Client.from_credentials('login', 'pass', captcha_callback=proc_captcha)

Изучение по примерам

Вот несколько примеров для обзора. Даже если это не Ваш подход к обучению, пожалуйста, возьмите и бегло просмотрите их.

Код примеров опубликован в открытом доступе, поэтому Вы можете взять его и начать писать вокруг своё.

Посетите эту страницу чтобы изучить официальные примеры.

Логирование

Данная библиотека использует logging модуль. Чтобы настроить логирование на стандартный вывод, поместите

import logging
logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

в начало вашего скрипта.

Вы также можете использовать логирование в вашем приложении, вызвав logging.getLogger() и установить уровень какой Вы хотите:

logger = logging.getLogger()
logger.setLevel(logging.INFO)

Если Вы хотите DEBUG логирование:

logger.setLevel(logging.DEBUG)

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

Документация yandex-music-api расположена на readthedocs.io. Вашей отправной точкой должен быть класс Client, а точнее его методы. Именно они выполняют все запросы на API и возвращают Вам готовые объекты. Класс Client на readthedocs.io.

Получение помощи

Получить помощь можно несколькими путями:

• Задать вопрос в Telegram чатике, где мы помогаем друг другу, присоединяйтесь!

• Сообщить о баге, предложить новую фичу или задать вопрос можно создав issue.

• Найти ответ на вопрос в документации библиотеки.

Реализации на других языках

C#

Реализация с совершенно другим подходом, так как используется API для frontend’a, а не мобильных и десктопных приложений: Winster332/Yandex.Music.Api.

Автор не сильно проявляет активность, но появился форк, который продолжил начатое. Более того, @K1llMan (автор форка) планирует изменить эндпоинты с фронтовых на те, что используются в данной библиотеке. K1llMan/Yandex.Music.Api

PHP

Частично переписанная текущая библиотека на PHP: LuckyWins/yandex-music-api.

JavaScript

API wrapper на Node.JS. Не обновлялся больше двух лет: itsmepetrov/yandex-music-api.

Разработанные проекты

Плагин для Kodi

Плагин может проигрывать пользовательские плейлисты и плейлисты Яндекса, поиск по Яндекс Музыке, радио.

Сайт проекта: ymkodi.ml.

Исходный код: kodi.plugin.yandex-music

Автор: @Angel777d

Telegram бот-клиент

Неофициальный бот. Умные и ваши плейлисты, понравившиеся треки. Лайки, дизлайки, текста песен, поиск, распознавание песен, похожие треки! Полноценный клиент на базе мессенджера.

Сайт проекта: music-yandex-bot.ru

Username в Telegram: @music_yandex_bot

Статья на habr.com с описанием реализации: Под капотом бота-клиента Яндекс.Музыки

Автор: @MarshalX

Благодарность

Спасибо разработчикам python-telegram-bot. Выбрал Вас в качестве примера.

Лицензия

Вы можете копировать, распространять и модифицировать программное обеспечение при условии, что модификации описаны и лицензированы бесплатно в соответствии с LGPL-3. Произведения производных (включая модификации или что-либо статически связанное с библиотекой) могут распространяться только в соответствии с LGPL-3, но приложения, которые используют библиотеку, необязательно.

Список изменений

Версия 0.1.1

25.03.2020

Закончено документирование всех классов и основных методов!

Переломные изменения

• Классы отметок “мне нравится” для альбомов, плейлистов и исполнителей обобщены. Теперь представлены одним классом.

  • Удаленные классы:

    • ArtistsLikes.

    • AlbumsLikes.

    • PlaylistsLikes.

  • Новый класс: Like (поле type для определения содержимого).

• Изменено название пакета с status на account (#195).

• Исправлено выбрасываемое исключение при таймауте:

  • Прошлое исключение: TimeoutError (built-in).

  • Новое исключение: TimedOut (yandex_music.exceptions).

• Удалены следующие файлы: requirements.txt, requirements-dev.txt, requirements-docs.txt.

Крупные изменения

• Добавлено обнаружение новых полей с просьбой сообщить о них (#216).

  • Добавлена проверка на неизвестные поля.

  • Добавлен вывод отладочной информации в виде warning’a.

  • Добавлен шаблон issue для отправки логов.

• Добавлено поле type для класса SearchResult для определения типа результата поиска по объекту.

• Добавлены настройки пользователя (#195):

  • Добавлен класс UserSettings.

  • Добавлен метод для получения своих настроек (account_settings).

  • Добавлен метод для получения настроек другого пользователя (users_settings).

  • Добавлен метод для изменения настроек (account_settings_set).

• Добавлен возможность получить похожие треки (#197):

  • Добавлен класс TracksSimilar с полями трека и списка похожих треков.

  • Добавлен метод для получения похожих треков (tracks_similar).

• Добавлены шоты от Алисы (#185):

  • Добавлен метод after_track в класс Client для получения контента для воспоризведения после трека (реклама, шот).

  • Добавлены методы для загрузки обложки и аудиоверсии шота.

  • Добавлены новые классы:

    • Shot

    • ShotData

    • ShotEvent

    • ShotType

• Добавлен метод для изменения видимости плейлиста (#179).

• Добавлена поддержка Яндекс.Радио (#20):

  • Исправлена отправка фидбека.

  • Написана инструкция по использованию (в доке к методу).

  • Добавлен аругмент для перехода по цепочке треков.

  • Добавлен метод для изменения настроек станции.

Незначительные изменения и/или исправления

• Убрано дублирование информации в документации (#247).

• Добавленые новые поля в класс Track: version, remember_position (#238).

• Добавлено исключение InvalidBitrate при попытке загрузить недопустимый трек по критериям (кодек, битрейт).

• Исправлено получение прямой ссылки на файл с кодеком AAC (#237, #25).

• Исправлено получение плейлиста с Алисой в лендинге (#185).

• Исправлено название поля с ссылкой на источник в классе Description (с url на uri).

• Исправлена десериализация несуществующего исполнителя.

• Добавлено поле version в класс Album (#178).

• Поле picture класса Vinyl теперь опциональное.

• Поле week класса Ratings теперь опциональное.

• Поле product_id класса AutoRenewable теперь опциональное (#182).

• Правки замечаний по codacy.

Версия 0.0.16

29.12.2019

Переломные изменения

• Поле account переименовано в me и теперь содержит объект Status, вместо Account (#162).

• Убрано использование зарезервированных имён в аргументах конструкторов (теперь они с _ на конце). Имена с нижними подчёркиваниями есть как при сериализации так и при десериализации (#168).

Крупные изменения

• Добавлены аннотации типов во всей библиотеке!

Незначительные изменения и/или исправления

• Добавлен аргумент fetch_account_status для опциональности получения информации об аккаунте при инициализации клиента (#162).

• Добавлены тесты c передачей пустого словаря в de_json и de_list (#174).

• Использование ujson при наличии, обновлены зависимости (#161).

• Добавлен в зависимости для разработки importlib_metadata для поддержки старых версий (в новой версии pytest его больше не используют, в угоду importlib.metadata #pytest-5537)) (#161).

• Добавлен в зависимости для разработки atomicwrites, который используется pytest теперь только на Windows - #pytest-6148 (#161).

• Исправлен баг с передачей timeout аргумента в аргумент params в следующих методах: artists, albums, playlists_list (#120).

• Исправлена иницилазиация клиента при помощи логина и пароля с использованием прокси (#159).

• Исправлен баг в загрузке обложки альбома.

Версия 0.0.15

01.12.2019

Переломные изменения

• У классов Artist, Track и Playlist изменился перечень полей для генерации хеша.

Крупные изменения

• Добавлена возможность выполнять запросы через прокси-сервер для использовании библиотеки на зарубежных серверах (#139).

  • Добавлен пример использования в README.

• Добавлена обработка капчи при авторизации с возможностью использования callback-функции для её обработки (#140):

  • Новые исключения:

    • Captcha:

      • CaptchaRequired.

      • CaptchaWrong.

  • Новые классы:

    • CaptchaResponse.

  • Новые примеры в README:

    • Пример обработки с использованием callback-функции.

    • Пример полностью своей обработки капчи.

• Добавлена документация для класса Search (#83).

• Добавлена возможность получения всех альбомов исполнителя (#141):

  • Новые классы:

    • ArtistAlbums.

  • Новые методы:

    • artists_direct_albums у Client.

    • get_albums у Artist.

• Добавлена обработка несуществующего плейлиста (#147):

  • Новые классы:

    • PlaylistAbsence.

Незначительные изменения и/или исправления

• Исправлен баг с загрузкой файлов (#149).

• Исправлен баг некорректной десериализации плейлиста при отсутствии прав на него (#147).

• Исправлен баг неправильной десериализации треков и артистов у собственных загруженных файлов (#154).

Версия 0.0.14

10.11.2019

Переломные изменения

• Практически у всех классов был обновлён список полей участвующих при сравнении объектов.

• Если в атрибутах для стравнения объектов присутствуют списки, то они будут преобразованы к frozenset.

• Убрано конвертирование даты из строки в объект. Теперь все даты представляны строками в ISO формате.

• Классы AlbumSearchResult, ArtistSearchResult, PlaylistSearchResult, TrackSearchResult, VideoSearchResult были объединены в один - SearchResult.

Крупные изменения

• Добавлен метод получения треков исполнителя (#123).

• Добавлены классы-обёртки над пагинацией (Pager) и списка треков артиста (ArtistsTracks).

• Добавлено 554 unit-теста для всех классов-обёрток над объектами API.

• Добавлен codecov и workflows для GitHub Actions.

Незначительные изменения и/или исправления

• Поле cover_uri класса Album теперь опциональное.

• Поле region у класса Account теперь не обязательное.

• Исправлен баг в .to_dict() методе, связанный с десериализцией объектов списков и словарей.

• Исправлен баг в .to_dict() методе, связанный с не рекурсивной десериализацией.

• Исправлена десериализация similar_artists в BriefInfo.

• Исправлен баг с десериализацией artist в классе ArtistEvent.

• Исправлен баг десериализации списка альбомов и артистов у класса Track (#122).

• Исправлена загрузка обложки у трека.

• Исправлены сравнения объектов.