📚 Yandex Bookmate API v2.0

Неофициальный Python API для Яндекс.Книг с нативной аутентификацией Bookmate

⚠️ Версия 2.0 — несовместима с v0.1.x

Это полностью переписанная версия библиотеки. Если вы использовали версию 0.1.2 и ниже, ознакомьтесь с руководством по миграции.

Что нового в v2.0

• Клиент-серверная архитектура — единый YandexBookClient вместо статических методов на моделях
• OAuth-авторизация — приватные методы (библиотека, полки, профиль) через Яндекс OAuth-токен
• 20+ приватных методов — управление библиотекой, полками, достижениями, уведомлениями и др.
• GraphQL-поддержка — поиск, подписки, статистика чтения через GraphQL endpoint
• Async-версия — полноценный асинхронный клиент на aiohttp (pip install yandex-book-api[async])
• Dataclass-модели вместо Pydantic — легковеснее, без внешних зависимостей для моделей
• Кастомные исключения — UnauthorizedError, NotFoundError, BadRequestError и др.
• Тесты — pytest-покрытие основных моделей

Миграция с v0.1.x на v2.0

Ключевые отличия

Примеры миграции

Было (v0.1.x):

from yandex_book import User, Book

user = User.get("b1234567890")
books = User.list_books(user.id)
book = Book.get("mqK3FFjg")
book.download_cover(size="small", dest="cover.jpg")

Стало (v2.0):

from yandex_book import YandexBookClient

# Без токена — только публичные методы
client = YandexBookClient()
user = client.get_user("b1234567890")
books = client.get_user_books(user.id_)

# С токеном — все методы
client = YandexBookClient('y0_AgAAAA...')
book = client.get_book("mqK3FFjg")
client.download_file(book.cover.small, "cover.jpg")

# Приватные методы (требуют токен)
my_library = client.get_my_library()
client.add_book("mqK3FFjg")

Содержание

• Установка
• Получение токена
• Публичные методы
• Приватные методы
• Модели данных
• Примеры

Установка

Установите библиотеку через pip:

pip install yandex-book-api

Если вы хотите использовать асинхронный клиент (на базе aiohttp), установите его с дополнительными зависимостями:

pip install yandex-book-api[async]

Для локальной разработки (в режиме редактирования):

pip install -e .

Получение токена

Нужен токен Яндекса формат: y0_AgAAAA...

Через OAuth:

Запустите из корня проекта:

python3 get_token.py

Скрипт откроет страницу входа в обычном браузере. На macOS он будет ждать завершения входа и автоматически прочитает URL возврата из активной вкладки Safari. Если система запросит доступ, разрешите Terminal управлять Safari. Если автоматическое чтение не сработает или используется Windows/Linux, скрипт попросит вставить полную ссылку из адресной строки браузера.

Вручную через браузер:

Откройте эту ссылку в браузере и войдите в аккаунт:

https://oauth.yandex.ru/authorize?response_type=token&client_id=4483e97bab6e486a9822973109a14d05

После входа скопируйте access_token из URL возврата. Он находится после # и начинается с y0_. Если в адресной строке нет access_token и отображается только ошибка открытия Букмейта, используйте скрипт выше.

Токен используйте как аргумент YandexBookClient(token). Не публикуйте и не сохраняйте его в Git.

Публичные методы (без авторизации)

User.get()

Получить информацию о пользователе.

Возвращает: User объект с полями:

User.list_books()

Получить публичные книги пользователя.

Возвращает: List[Book] с полями:

User.list_audiobooks()

Получить публичные аудиокниги пользователя.

Возвращает: List[Audiobook] (наследует Book + дополнительные поля):

User.list_quotes()

Получить цитаты пользователя (публично).

Возвращает: List[Quote] с полями:

User.list_bookshelves()

Получить полки пользователя.

Возвращает: List[Bookshelf]

User.list_impressions()

Получить рецензии пользователя.

Возвращает: List[Impression]

Book.get()

Получить информацию о книге.

Возвращает: Book объект

Book.impressions()

Получить рецензии на книгу.

Возвращает: List[Impression]

Приватные методы (с авторизацией)

Client(auth_token)

Инициализировать авторизованный клиент.

client.test_token()

Проверить валидность токена.

client.get_profile()

Получить свой профиль.

Поля user:

client.get_my_library()

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

Возвращает: Dict с ключом data содержащим список карточек:

client.add_book()

Добавить книгу в мою библиотеку.

Возвращает: Dict с полями:

client.remove_book()

Удалить книгу из моей библиотеки.

Возвращает: Dict с полями:

client.get_my_bookshelves()

Получить мои книжные полки.

Возвращает: Dict с ключом data содержащим список полок:

client.get_notifications_status()

Получить статус уведомлений.

client.get_reading_achievements()

Получить достижения за год.

Возвращает: Dict с полями:

client.get_popular_searches()

Получить популярные поиски.

Возвращает: Dict с ключом data содержащим список популярных запросов

client.get_emotions()

Получить доступные эмоции для рецензий.

client.get_access_levels()

Получить уровни доступа к контенту.

client.get_counters()

Получить счётчики профиля.

client.get_context()

Получить контекст приложения.

client.get_privacy_settings()

Получить настройки приватности.

client.get_sync_state()

Получить состояние синхронизации.

client.get_metadata_secret()

Получить секретные метаданные.

client.get_user_json()

Получить полные данные пользователя.

client.get_push_notification_restrictions()

Получить ограничения для push уведомлений.

client.get_features()

Получить информацию о функциях.

Возвращает: Dict с информацией о доступности функций

client.get_series_following()

Получить серии, на которые я подписан.

Возвращает: Dict с ключом series содержащим список серий:

Таблица всех REST методов Client

Всего 21 метод (+ новый get_series_following):

Модели данных

Image / Avatar

Person

Label

Примеры

Публичные методы (без токена)

from yandex_book import YandexBookClient

client = YandexBookClient()

# Получить пользователя
user = client.get_user("b1234567890")
print(user.name, user.login)

# Книги пользователя
books = client.get_user_books(user.id_)
for book in books[:3]:
    print(book.display_title)

# Информация о книге
book = client.get_book("mqK3FFjg")
print(book.title, book.annotation)

Приватные методы (с токеном)

from yandex_book import YandexBookClient

client = YandexBookClient('y0_AgAAAA...')

# Проверить токен
if client.test_token():
    print("Токен валиден!")

# Профиль
me = client.get_profile()
print(me.name, me.login)

# Библиотека
library = client.get_my_library(limit=10)
for card in library:
    print(card.book.display_title, card.state)

# Добавить / удалить книгу
client.add_book("mqK3FFjg")

# Поиск через GraphQL
results = client.search("Мастер и Маргарита")

Async-версия

import asyncio
from yandex_book import YandexBookClientAsync

async def main():
    client = YandexBookClientAsync('y0_AgAAAA...')
    me = await client.get_profile()
    books = await client.get_user_books(me.id_)
    print(f"{me.name}: {len(books)} книг")
    await client._request.close()

asyncio.run(main())

Обработка ошибок

from yandex_book import YandexBookClient, NotFoundError, UnauthorizedError

client = YandexBookClient('y0_AgAAAA...')

try:
    user = client.get_user("nonexistent")
except NotFoundError:
    print("Пользователь не найден")
except UnauthorizedError:
    print("Неверный токен")

Лицензия

MIT