Metadata-Version: 2.5
Name: yandex-music
Version: 3.2.2
Summary: Неофициальная Python библиотека для работы с API сервиса Яндекс.Музыка.
Project-URL: homepage, https://ym.marshal.dev/
Project-URL: repository, https://github.com/MarshalX/yandex-music-api
Project-URL: documentation, https://ym.marshal.dev/
Project-URL: changes, https://github.com/MarshalX/yandex-music-api/blob/main/CHANGES.md
Project-URL: issues, https://github.com/MarshalX/yandex-music-api/issues
Project-URL: sponsoring, https://github.com/sponsors/MarshalX
Project-URL: telegram, https://t.me/yandex_music_api
Project-URL: codecov, https://codecov.io/gh/MarshalX/yandex-music-api
Project-URL: codacy, https://app.codacy.com/gh/MarshalX/yandex-music-api
Author-email: "Ilya (Marshal)" <ilya@marshal.dev>
License-Expression: LGPL-3.0-only
License-File: LICENSE
Keywords: api,client,library,music,python,wrapper,yandex,апи,библиотека,клиент,музыка,обёртка,пайтон,питон,яндекс
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: requests[socks]
Requires-Dist: typing-extensions>=4.4.0
Provides-Extra: async
Requires-Dist: aiofiles; extra == 'async'
Requires-Dist: aiohttp; extra == 'async'
Provides-Extra: crypto
Requires-Dist: cryptography; extra == 'crypto'
Provides-Extra: orjson
Requires-Dist: orjson; extra == 'orjson'
Provides-Extra: pydantic-core
Requires-Dist: pydantic-core; extra == 'pydantic-core'
Provides-Extra: ujson
Requires-Dist: ujson; extra == 'ujson'
Provides-Extra: ynison
Requires-Dist: betterproto<3,>=1.2.5; extra == 'ynison'
Requires-Dist: websockets>=13.0; extra == 'ynison'
Description-Content-Type: text/markdown

## Yandex Music API

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

⚠️ Это неофициальная библиотека.

Сообщество разработчиков общаются и помогают друг другу в [Telegram чате](https://t.me/yandex_music_api), присоединяйтесь!

### Содержание
  - [Введение](#введение)
    1.  [Доступ к вашим данным Яндекс.Музыка](#доступ-к-вашим-данным-яндексмузыка)
  - [Установка](#установка)
  - [Начало работы](#начало-работы)
    1.  [Изучение по примерам](#изучение-по-примерам)
    2.  [Особенности использования асинхронного клиента](#особенности-использования-асинхронного-клиента)
    3.  [Логирование](#логирование)
    4.  [Расхождения с API](#расхождения-с-api)
    5.  [Документация](#документация)
    6.  [Справочник API (OpenAPI)](#справочник-api-openapi)
  - [Получение помощи](#получение-помощи)
  - [Список изменений](#список-изменений)
  - [Реализации на других языках](#реализации-на-других-языках)
  - [Внесение своего вклада в проект](#внесение-своего-вклада-в-проект)
  - [Лицензия](#лицензия)

### Введение

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

Она совместима с версиями Python 3.8+ и поддерживает работу как с синхронным, так и с асинхронным (asyncio) кодом.

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

Помимо HTTP API библиотека поддерживает [Ynison](https://ym.marshal.dev/ynison), протокол синхронизации плеера между устройствами: текущий трек, очередь, список устройств и удалённое управление воспроизведением. Также доступны [сессии радио](https://ym.marshal.dev/radio): «Моя волна», волны по занятиям и генеративные станции с обратной связью о прослушиваниях.

📘 Всё API, которое покрывает библиотека, описано в формате OpenAPI: [интерактивный справочник API Яндекс Музыки](https://ym.marshal.dev/api/) с параметрами, телами запросов, схемами ответов и примерами. Подробнее в разделе [Справочник API (OpenAPI)](#справочник-api-openapi).

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

Для большинства аккаунтов токен можно получить прямо из библиотеки через OAuth Device Flow:

``` python
from yandex_music import Client


def on_code(code):
    print(f'Откройте {code.verification_url} и введите код: {code.user_code}')


client = Client()
token = client.device_auth(on_code=on_code)

# Сохраните токен куда-нибудь (переменная окружения, файл, БД),
# чтобы не проходить авторизацию при каждом запуске.
print(f'access_token:  {token.access_token}')
print(f'refresh_token: {token.refresh_token}')
print(f'expires_in:    {token.expires_in}')

client.init()
```

Метод `device_auth` блокирующий: он ждёт, пока вы подтвердите вход на странице Яндекса, и возвращает объект `OAuthToken` с полями `access_token`, `refresh_token`, `expires_in`, `token_type`. **Хранение токена — ответственность вызывающего кода:** библиотека не сохраняет его на диск и не обновляет по истечении `expires_in`. Если Device Flow для вашего аккаунта не работает — смотрите альтернативные способы в [документации](https://ym.marshal.dev/token).

### Установка

Установить или обновить библиотеку:

``` shell
pip install -U yandex-music
```

Этой команды достаточно для работы с синхронным клиентом. Для асинхронного клиента (`ClientAsync`) нужны дополнительные зависимости `aiohttp` и `aiofiles` — они доступны как опциональный экстра `async`:

``` shell
pip install -U "yandex-music[async]"
```

Для [Ynison](https://ym.marshal.dev/ynison) нужны `websockets` и `betterproto`, они доступны как опциональный экстра `ynison`. Экстры можно комбинировать:

``` shell
pip install -U "yandex-music[ynison]"
pip install -U "yandex-music[async,ynison]"
```

Для расшифровки треков, полученных со способом доставки `encraw` (например, lossless через `tracks_file_info`), нужен `cryptography`, он доступен как опциональный экстра `crypto`:

``` shell
pip install -U "yandex-music[crypto]"
```

JSON обрабатывается самой быстрой из установленных библиотек: `orjson`, `pydantic-core`, `ujson` или стандартный `json`. Ускоренные библиотеки доступны как опциональные экстры `orjson`, `pydantic-core` и `ujson`:

``` shell
pip install -U "yandex-music[orjson]"
```

Библиотеку можно выбрать явно или подключить свою, подробнее в [документации](https://ym.marshal.dev/yandex_music.utils.json_backend).

Установка из исходного кода:

``` shell
git clone https://github.com/MarshalX/yandex-music-api
cd yandex-music-api
pip install .           # синхронный клиент
pip install ".[async]"  # с поддержкой асинхронного клиента
pip install ".[ynison]" # с поддержкой Ynison
pip install ".[crypto]" # с расшифровкой encraw
```

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

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

Инициализация синхронного клиента:

``` python
from yandex_music import Client

client = Client()
client.init()

# или

client = Client().init()
```

Инициализация асинхронного клиента:

``` python
from yandex_music import ClientAsync

client = ClientAsync()
await client.init()

# или

client = await Client().init()
```

Вызов `init()` необходим для получения информации — упрощения будущих запросов.

Работа без авторизации ограничена. Так, например, для загрузки будут доступны только первые 30 секунд аудиофайла. Для понимания всех ограничений зайдите на сайт Яндекс.Музыка в режиме инкогнито и воспользуйтесь сервисом.

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

Авторизация:

``` python
from yandex_music import Client

client = Client('token').init()
```

После успешного создания клиента вы вольны в выборе необходимого метода из API. Все они доступны у объекта класса `Client`. Подробнее в методах клиента в [документации](https://ym.marshal.dev/client).

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

``` python
from yandex_music import Client

client = Client('token').init()
client.users_likes_tracks()[0].fetch_track().download('example.mp3')
```

В примере выше клиент получает список треков, которые были отмечены как понравившиеся. API возвращает объект [TracksList](https://ym.marshal.dev/yandex_music.tracks_list), в котором содержится список с треками класса [TrackShort](https://ym.marshal.dev/yandex_music.track_short). Данный класс содержит наиважнейшую информацию о треке и никаких подробностей, поэтому для получения полной версии трека со всей информацией необходимо обратиться к методу `fetch_track()`. Затем можно скачать трек методом `download()`.

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

``` python
from yandex_music import Client

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

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

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

``` python
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).init()
```

Примеры Proxy URL:
  - socks5://user:<password@host>:port
  - <http://host:port>
  - <https://host:port>
  - <http://user:password@host>

Больше примеров тут: [proxies - advanced usage - requests](https://2.python-requests.org/en/master/user/advanced/#proxies)

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

``` python
from yandex_music.utils.request_async import Request
from yandex_music import ClientAsync

request = Request(proxy_url='http://user:pass@some.proxy.com')
client = await ClientAsync(request=request).init()
```

Socks прокси не поддерживаются в асинхронной версии.

Про поддерживаемые прокси тут: [proxy support - advanced usage - aiohttp](https://docs.aiohttp.org/en/stable/client_advanced.html#proxy-support)

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

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

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

Посетите [эту страницу](https://github.com/MarshalX/yandex-music-api/blob/main/examples/), чтобы изучить официальные примеры.

#### Особенности использования асинхронного клиента

При работе с асинхронной версией библиотеке стоит всегда помнить
следующие особенности:
  - Клиент следует импортировать с названием `ClientAsync`, а не просто `Client`.
  - При использовании методов-сокращений нужно выбирать метод с суффиксом `_async`.

Пояснение ко второму пункту:

``` python
from yandex_music import ClientAsync

client = await ClientAsync('token').init()
liked_short_track = (await client.users_likes_tracks())[0]

# правильно
full_track = await liked_short_track.fetch_track_async()
await full_track.download_async()

# НЕПРАВИЛЬНО
full_track = await liked_short_track.fetch_track()
await full_track.download()
```

#### Логирование

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

``` python
import logging

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

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

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

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

``` python
logger.setLevel(logging.DEBUG)
```

#### Расхождения с API

Ответы API со временем меняются. Если в ответе нет обязательного поля модели или оно равно `null`, библиотека не падает: поле получает значение `None`, а в лог пишется предупреждение. Оно выводится один раз на модель и набор полей и содержит тип модели, поля, запрос без идентификаторов, версию библиотеки и ссылку на заполненный issue. Пожалуйста, отправьте его, это помогает быстрее обновлять модели.

Поведение настраивается параметрами клиента:

- `report_unknown_fields=True` добавляет в отчёт новые поля из ответа, которых нет в моделях, и их структуру без значений, например `list[{id: int, title: str}]`.
- `strict=True` вызывает `SchemaMismatchError` вместо предупреждения. Подходит для тестов.
- `on_schema_mismatch` принимает функцию, которая получает отчёт `SchemaMismatch` вместо записи в лог. Например, для отправки в Sentry.

``` python
from yandex_music import Client
from yandex_music.utils.schema_mismatch import SchemaMismatch


def handle(mismatch: SchemaMismatch) -> None:
    print(mismatch.describe())
    print(mismatch.issue_url())


client = Client(report_unknown_fields=True, on_schema_mismatch=handle)
```

Подробнее в [документации](https://ym.marshal.dev/yandex_music.utils.schema_mismatch).

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

Документация `yandex-music-api` расположена на [ym.marshal.dev](https://ym.marshal.dev/). Вашей отправной точкой должен быть класс `Client`, а точнее его методы. Именно они выполняют все запросы на API и возвращают вам готовые объекты. [Класс Client на ym.marshal.dev](https://ym.marshal.dev/client).

### Справочник API (OpenAPI)

На [ym.marshal.dev/api](https://ym.marshal.dev/api/) опубликован интерактивный справочник API Яндекс Музыки: 150 методов, более 220 схем моделей, параметры, тела запросов, заголовки и примеры вызова через библиотеку и curl. У каждого метода есть ссылка на соответствующий метод `Client` в документации.

Справочник построен на спецификации [openapi.json](https://ym.marshal.dev/api/openapi.json). Её можно импортировать в Postman, Insomnia или Bruno, сгенерировать по ней клиент на другом языке или дать как контекст ИИ-ассистенту. Спецификация собирается автоматически из кода библиотеки и обновляется с каждым релизом.

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

Получить помощь можно несколькими путями:
  - Задать вопрос в [Telegram чате](https://t.me/yandex_music_api), где мы помогаем друг другу, присоединяйтесь\!
  - Сообщить о баге можно [создав Bug Report](https://github.com/MarshalX/yandex-music-api/issues/new?assignees=MarshalX&labels=bug&template=bug-report.md&title=).
  - Предложить новую фичу или задать вопрос можно [создав discussion](https://github.com/MarshalX/yandex-music-api/discussions/new).
  - Найти ответ на вопрос в [документации библиотеки](https://ym.marshal.dev/).

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

Весь список изменений ведётся в файле [CHANGES.md](https://github.com/MarshalX/yandex-music-api/blob/main/CHANGES.md).

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

- [OpenAPI спецификация](https://github.com/acherkashin/yandex-music-open-api/blob/main/src/yandex-music.yaml)
- [C#](https://github.com/K1llMan/Yandex.Music.Api)
- [PHP](https://github.com/LuckyWins/yandex-music-api)
- [TS](https://github.com/acherkashin/yandex-music-open-api)
- [JS](https://github.com/kontsevoye/ym-api)

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

Внесение своего вклада максимально приветствуется! Есть перечень пунктов, который стоит соблюдать. Каждый пункт перечня расписан в [CONTRIBUTING.md](https://github.com/MarshalX/yandex-music-api/blob/main/CONTRIBUTING.md).

Вы можете помочь и сообщив о [баге](https://github.com/MarshalX/yandex-music-api/issues/new?assignees=MarshalX&labels=bug&template=bug-report.md&title=) или о [новом поле пришедшем от API](https://github.com/MarshalX/yandex-music-api/issues/new?assignees=&labels=feature&template=found-unknown-fields.md&title=%D0%9D%D0%BE%D0%B2%D0%BE%D0%B5+%D0%BD%D0%B5%D0%B8%D0%B7%D0%B2%D0%B5%D1%81%D1%82%D0%BD%D0%BE%D0%B5+%D0%BF%D0%BE%D0%BB%D0%B5+%D0%BE%D1%82+API).

### Лицензия

Вы можете копировать, распространять и модифицировать программное обеспечение при условии, что модификации описаны и лицензированы бесплатно в соответствии с [LGPL-3](https://www.gnu.org/licenses/lgpl-3.0.html). Произведения производных (включая модификации или что-либо статически связанное с библиотекой) могут распространяться только в соответствии с LGPL-3, но приложения, которые используют библиотеку, необязательно.
