🎬 KINOPAPI - БИБЛИОТЕКА ДЛЯ РАБОТЫ С API КИНОПОИСКА

Warning

Данный инструмент разработан и опубликован исключительно в образовательных целях и предназначен для личного использования. Он не является официальным инструментом и не нарушает условия использования сторонних сервисов, с которыми взаимодействует. Автор не несёт ответственности за последствия его использования, включая, но не ограничиваясь, возможными блокировками, ограничениями доступа или юридическими последствиями. Ответственность за соблюдение условий использования сторонних сервисов, с которыми взаимодействует инструмент, полностью лежит на пользователе.

---

KINOPAPI - библиотека для работы с API Кинопоиска, она была разработана в учебных целях, для изучения способов работы с API и предоставляет удобный и эффективный интерфейс для получения информации с платформы Кинопоиск.

Библиотека поддерживает как синхронный, так и асинхронный (включая работу с файлами тел запросов) режим работы, что делает её гибкой и удобной для самых разных сценариев.

Ниже пример использования функции для глобального поиска по запросу:

import json
import asyncio
from kinopapi import suggest_search_async

async def start():
    request = await suggest_search_async("Властелин колец")
    data = await request.json()
    print(json.dumps(data, indent=4, ensure_ascii=False))

asyncio.run(start())

Вывод полученных данных (для компактности большее кол-во строк было скрыто):

{
    // ...
    "id": 328,
    // ...
    "title": {
        "russian": "Властелин колец: Братство кольца",
        "original": "The Lord of the Rings: The Fellowship of the Ring",
        "__typename": "Title"
    },
    "rating": {
        "kinopoisk": {
            "isActive": true,
            "value": 8.62,
            "__typename": "RatingValue"
        },
        "__typename": "Rating"
    },
    "poster": {
        "avatarsUrl": "//avatars.mds.yandex.net/get-kinopoisk-image/6201401/a2d5bcae-a1a9-442f-8195-f5373a5ba77f",
        "fallbackUrl": null,
        "__typename": "Image"
    },
    // ...
    "productionYear": 2001,
    // ...

⭐ Что крутого?

🤔 Что за мемчик?

• 🎬 21 запрос в асинхронном и синхронном вариантах (ещё два запроса в разработке).
• 🔑 Нет необходимости в API-ключе или регистрации для доступа.
• 🚀 Без парсинга страниц — только быстрые и стабильные API-запросы.
• 📊 Актуальная и достоверная информация о фильмах и сериалах.
• 🔍 Доступ к поисковому алгоритму, рекомендациям и подбору схожего контента.
• 🎥 Медиа-контент: трейлеры, постеры и изображения.
• 💬 Отзывы пользователей, интересные факты и рецензии критиков.
• ⚡ Быстрая и удобная интеграция возможностей API Кинопоиска в ваши проекты.
• 🤖 Идеально подходит для использования в ботах, приложениях и сервисах, которые требуют информации о фильмах, сериалах и актерах с Кинопоиска.

🚀 Установка:

1. Клонируем репозиторий:

   git clone https://github.com/cloudsucker/kinopapi.git

2. Переходим в созданную директорию:

   cd kinopapi

3. Создаём виртуальное окружение (опционально):

   Рекомендуется, если в проекте не создано виртуальнуе окружение.

   python -m venv .venv

   Активируем виртуальное окружение:

   Windows:

   .venv\Scripts\activate

   Linux/macOS:

   source .venv/bin/activate

4. Устанавливаем библиотеку:

   Обычная установка:

   pip install .

   Этот вариант устанавливает библиотеку как статический пакет, после чего клонированную директорию можно удалить. Если выйдет новая версия, её нужно будет обновлять вручную c помощью pip install --upgrade .

   Установка в режиме редактирования:

   pip install -e .

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

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

🧪 Тестирование

Note

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

Тестирование асинхронного режима

python -m unittest tests/test_async_requests.py

Тестирование обычного режима

python -m unittest tests/test_sync_requests.py

📝 Описание запросов

Запросы делятся на несколько основных типов:

1. Film - запросы для фильмов.
2. TvSeries - запросы для сериалов.
3. Movies - запросы общего типа (обычно включают и фильмы и сериалы).
4. Person — запросы, связанные с людьми кинематографа.
5. Search — запросы для поиска.

Формат запроса и примеры

Запросы к API реализуются в виде функций, принимающих параметры, которые затем заменяются в теле запроса. Рассмотрим формат на примере:

Пример запроса: FILM_MEDIA_POSTS

Функции:

# FILM_MEDIA_POSTS
def film_media_posts(film_id: int) -> requests.Response:
    """API-запрос для получения медиа-постов фильма по его ID."""
    return _request("FILM_MEDIA_POSTS", filmId=film_id)


# [ ASYNC ] FILM_MEDIA_POSTS
async def film_media_posts_async(film_id: int) -> aiohttp.ClientResponse:
    """Асинхронный API-запрос для получения медиа-постов фильма по его ID."""
    return await _request_async("FILM_MEDIA_POSTS", filmId=film_id)

Тело запроса:

{
    "operationName": "FilmMediaPosts",
    "variables": {
        "mediaPostsLimit": 8,
        "filmId": 1209193 // это значение меняется на переданное в функцию
    },
    "query": "query FilmMediaPosts($filmId: Long!, $mediaPostsLimit: Int = 10) { film(id: $filmId) { id mediaPosts: post(limit: $mediaPostsLimit) { items { id title commentsCount publishedAt commentable type thumbImage { avatarsUrl fallbackUrl __typename } __typename } total __typename } __typename } } "
}

Параметр filmId заменяется значением, переданным в функцию, и используется в ключе variables.filmId в теле запроса.

Примечание: В ASYNC методах для работы с файлами используется aiofiles, так что вся работа происходит асинхронно.

🔗 Зависимости

• aiofiles==24.1.0
• aiohttp==3.11.11
• requests==2.32.3

📬 Обратная связь

Библиотека активно развивается, буду рад обратной связи.

По всем вопросам: [email protected]