Skip to main content

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

Project description

API Yandex Music - неофициальная Python библиотека

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

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

Версия пакета PyPi Поддерживаемые Python версии Покрытие кода тестами Качество кода Статус тестов Статус документации Лицензия LGPLv3 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 import Client

client = Client()

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

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

from yandex_music import Client

client = Client.from_credentials('example@yandex.com', 'password')

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

from yandex_music import Client

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

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

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

from yandex_music import Client

client = Client.from_credentials('example@yandex.com', 'password')
client.users_likes_tracks()[0].fetch_track().download('example.mp3')

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

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

from yandex_music 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 import Client

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

Примеры proxy url:

Больше примеров тут: 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.

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

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

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

C#

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

@Winster332 не сильно проявляет активность, но существует форк, который продолжил начатое. Эндпоинты изменены с фронтовых на мобильные: K1llMan/Yandex.Music.Api.

PHP

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

JavaScript

API wrapper на Node.JS. Не обновлялся больше двух лет: itsmepetrov/yandex-music-api. Продолжение разработки заброшенной библиотеки: kontsevoye/ym-api.

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

Плагин для Kodi

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

Сайт проекта: ymkodi.ml. Исходный код: kodi.plugin.yandex-music. Автор: @Angel777d.

Плагин для Kodi

Telegram бот-клиент

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

Сайт проекта: music-yandex-bot.ru. Бот в Telegram: @music_yandex_bot. Автор: @MarshalX.

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

Telegram бот-клиент

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

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

Внесение своего вклада в проект

Внесение своего вклада максимально приветствуется! Есть перечень пунктов, который стоит соблюдать. Каждый пункт перечня расписан в CONTRIBUTING.

Вы можете помочь и сообщив о баге или о новом поле пришедшем от API.

Лицензия

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

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

Версия 1.0.0

06.02.2021

Стабильная версия библиотеки

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

  • Поле error класса Artist теперь называется reason.
  • Метод users_playlists класса Client теперь возвращает один объект плейлиста, когда был передан один kind. При передаче списка в kind вернётся список плейлистов (#318).
  • Поле labels класса Album теперь может содержать список из строк, а не только список объектов класса Label.

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

  • Добавлены примеры в папку examples.
  • Добавлена поддержка рекомендаций для плейлистов (#324):
    • Добавлен класс PlaylistRecommendations.
    • Добавлен метод клиента для получения рекомендаций (users_playlists_recommendations).
    • Добавлен метод get_recommendations классу Playlist для получения рекомендаций.
  • Добавлено получение чартов (#294):
    • Добавлены новые классы: ChartInfo, ChartInfoMenu, ChartInfoMenuItem.
    • Добавлен метод клиента для получения чарта (chart).
  • Добавлена поддержка тегов/подборок (#192):
    • Добавлены новые классы: TagResult, Tag.
    • Добавлен новый метод клиента для получения тегов (tags).
  • Добавлено присоединение к коллективному плейлисту (#317):
    • Добавлен новый метод клиента для присоединения (playlists_collective_join).
  • Добавлена поддержка очередей прослушивания (#246):
    • Добавлены новые классы: Context, Queue, QueueItem.
    • Добавлены новые методы в Client: queues_list, queue, queue_update_position, queue_create.
    • Добавлены поля track_id и from_ в класс TrackId.
    • Добавлена возможность смены языка у клиента для ответов от API.
    • Добавлена десериализация любого объекта в JSON пригодного для отправки в запросе на Яндекс API.
  • Добавлены следующие методы для Client:
    • new_releases – получение полного списка всех новых релизов.
    • new_playlists – получение полного списка всех новый плейлистов.
    • podcasts – получение подкаста с лендинга.
  • Добавлены новые сокращения в модели:
    • download_cover_white, download_cover_uri в MixLink.
    • download_image в Promotion.
    • artists_name в Album и Track.
    • fetch_track, track_full_id в TrackId.
    • fetch_tracks в TracksList.
    • insert_track, delete_tracks, delete в Playlist.
    • playlist_id, fetch_playlist в PlaylistId.
    • get_current_track в Queue.
    • fetch_queue в QueueItem.
    • next_page, get_page, prev_page в Search.
    • и другие…
  • Добавлена поддержка новых типов поиска: подкасты, выпуски, пользователи.
  • Добавлен коллбек для обработки новых полей.
  • Добавлена информацию по поводу запуска потока по треку, плейлисту и др.
  • Добавлена десериализация decomposed у Artist (#10).
  • Добавлен __len__ для TracksList (#380).
  • Добавлены __iter__, __len__ и __getitem__ для классов представляющих список каких-либо объектов.
  • Добавлено сокращение fetch_tracks классу Playlist для получения треков плейлиста.
  • Добавлен метод get_url классу Icon для получения прямой ссылки на изображение.
  • Класс User расширен для поддержки поля user_info из Track (поля full_name, display_name).
  • Добавлены новые классы по отчётам с Telegram бота (#306, #398):
    • LandingList.
    • RenewableRemainder.
    • Alert.
    • AlertButton.
    • StationData.
    • Brand.
    • Contest.
    • OpenGraphData.
    • NonAutoRenewable.
    • Operator.
    • Deactivation.
    • PoetryLoverMatch.
    • Deprecation.
  • Добавлены новые поля классам по отчётам с Telegram бота (#306, #398):
    • plus в Product.
    • non_auto_renewable_remainder в Subscription.
    • og_image в Artist.
    • meta_type в Album.
    • advertisement в Status.
    • best в Track.
    • offer_id и artist_ids в Vinyl.
    • playlists в BriefInfo.
    • is_custom в Cover.
    • play_count, recent, chart, track в TrackShort.
    • url_part, og_title, image, cover_without_text, background_color, text_color, id_for_from, similar_playlists, last_owner_playlists в Playlist.
    • bg_color в Chart.
    • error в Artist.
    • substituted, matched_track, can_publish, state, desired_visibility, filename, user_info, meta_data в Track.
    • copyright_name, copyright_cline в Cover.
    • direct в DownloadInfo.
    • cheapest, title, family_sub, fb_image, fb_name, family, intro_period_duration, intro_price, start_period_duration, start_price, licence_text_parts в Product.
    • storage_dir, duplicates в Album.
    • subscribed в ArtistEvent.
    • description в GeneratedPlaylist.
    • genre в Event.
    • show_in_regions в Genre.
    • cover_uri в MixLink.
    • og_description, top_artist в Playlist.
    • full_image_url, mts_full_image_url в Station.
    • coauthors и recent_tracks в Playlist.
    • regions в User.
    • users, podcasts, podcast_episodes, type_, page, per_page в Search.
    • short_description, description, is_premiere, is_banner в Like.
    • master_info в AutoRenewable.
    • station_data и bar_below в Status.
    • family_auto_renewable в Subscription.
    • misspell_result и misspell_original в Search.
    • experiment в класс Status.
    • operator и non_auto_renewable в Subscription.
    • text_color, short_description, description, is_premiere и is_banner в Album.
    • hand_made_description в Artist.
    • metrika_id в Playlist.
    • og_image в Tag.
    • url в Lyrics.
    • number, genre в MetaData.
    • poetry_lover_matches в Track.
    • contest, dummy_description, dummy_page_description, dummy_cover, dummy_rollover_cover, og_data, branding в Playlist.
    • available_as_rbt, lyrics_available, remember_position, albums, duration_ms, explicit, start_date, likes_count, deprecation в Album.
    • lyricist, version, composer в MetaData.
    • last_releases в BriefInfo.
    • ya_money_id в Artist (#351, #370).
    • playlist_uuid в Playlist.
    • sync_queue_enabled в UserSettings.
    • background_video_uri, short_description, is_suitable_for_children в Track (#376).
    • meta_type, likes_count в Album (#386).
    • deprecation в Album.
    • available_regions в Album.
    • type, ready в Playlist.
    • description в Supplement.

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

  • Добавлена опциональность следующим полям:
    • все поля в MetaData.
    • advertisement в Status.
    • text_language в Lyrics.
    • provider_video_id в VideoSupplement.
    • title в VideoSupplement (#403).
    • instructions в Deactivation (#402).
    • id в Album (#401).
  • Исправлена десериализация подкастов, эпизодов подкастов и пользователей в лучшем результате поиска.
  • Исправлена десериализация альбомов. В зависимости от запроса содержимое лейблов может быть списком объектом или списком строк (в поиске).
  • Исправлен выбор настроек радио.
  • Исправлены ошибки в документации.
  • Протестирована работа на Python 3.9.

Версия 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).
  • Исправлено название поля с ссылкой на источник в классе Descriptionurl на 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).
  • Исправлена загрузка обложки у трека.
  • Исправлены сравнения объектов.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for yandex-music, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size yandex-music-1.0.0.tar.gz (182.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page