# Sort YM

Раскладывает лайкнутые треки Яндекс.Музыки по плейлистам вида `Жанр — RU` / `Жанр — INT`.

```
$ python -m sort_ym report

Распределение по плейлистам:
  Рок — INT: 143
  Рок — RU: 287
  Рэп — RU: 512
  ...

Отчёт сохранён: out/report.csv
```

## Установка

Требования: Python 3.11+ (используется `tomllib` из стандартной библиотеки), Windows/Linux/macOS, доступ в интернет.

```
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```

Для разработки (тесты):

```
.venv\Scripts\pip install -r requirements-dev.txt
```

## Что делает

1. **`auth`** — вход в аккаунт Яндекса через OAuth device-flow: покажет код, вы подтверждаете
   вход на странице Яндекса, токен сохраняется в `.token` (локально, в `.gitignore`).
2. **`fetch`** — скачивает список лайкнутых треков и их метаданные (жанр альбома, доступность
   текста) в `cache/tracks.json`. Повторный запуск докачивает только новые треки.
3. **`report`** — определяет жанр (крупная группа) и язык (RU/иностранный) каждого трека,
   считает распределение по будущим плейлистам и сохраняет `out/report.csv` для проверки.
   **Ничего не меняет в аккаунте.**
4. **`apply --yes`** — создаёт недостающие плейлисты и добавляет в них треки. Уже добавленные
   треки не дублируются при повторном запуске. Лайки не трогает, ничего не удаляет.

## Как определяется жанр и язык

- **Жанр**: у трека берётся жанр альбома, затем он сопоставляется с одной из ~11 крупных
  групп (Поп, Рок, Метал, Рэп, Электроника, Джаз и блюз, Классика, Фолк и world, Инди и
  альтернатива, Саундтреки, Разное) через реальное дерево жанров Яндекса
  (`sort_ym/genres.py`, таблица `ROOT_BUCKET` — легко дополняется).
- **Язык** — гибрид:
  1. Если у трека есть текст песни — реальный язык из API (`ru` → RU, иначе → INT).
  2. Иначе — подсказка по жанру (`rusrap`, `shanson`, `bard`, ...).
  3. Иначе — по алфавиту названия/исполнителя (кириллица/латиница).
  4. Если ничего не сработало — трек попадает в `... — Не определено`.

После `report` в консоли также печатается список нераспознанных жанров (попавших в «Разное»),
чтобы можно было дополнить таблицу в `sort_ym/genres.py`.

## Handy things

- Первый прогон `apply` делайте с `--limit 20 --yes` и проверьте результат в приложении, прежде
  чем запускать на все ~2000 треков.
- Все промежуточные данные лежат в `cache/` — их можно удалить, чтобы пересчитать с нуля.
- Настройки задержек между запросами — в `config.toml` (`[throttle]`).

## Риски (неофициальный API)

Официального API для личной библиотеки Яндекс.Музыки нет — инструмент использует
неофициальную библиотеку `yandex-music`. OAuth-токен в `.token` даёт полный доступ к аккаунту
Яндекса — храните его локально и не публикуйте. Инструмент выполняет только безопасные действия
(чтение лайков, создание плейлистов, добавление треков) и ничего не удаляет.

## For developers

Python 3.11+, `yandex-music==3.0.0`, стандартная библиотека (`tomllib`, `csv`, `unicodedata`).

```
.venv\Scripts\python -m pytest tests/ -v
.venv\Scripts\python -m sort_ym auth
.venv\Scripts\python -m sort_ym fetch
.venv\Scripts\python -m sort_ym report
.venv\Scripts\python -m sort_ym apply --limit 20 --yes
```

Структура кода и поток данных — в [ARCHITECTURE.md](ARCHITECTURE.md).