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

Реализация API сайта cinemate.cc на языке python.

Содержание:

Использование

Для начала использования библиотеки необходимо инициализировать основной класс:

from cinemate import Cinemate

cin = Cinemate(
    'your_username',
    'your_password',
    'your_passkey',
    'your_apikey'
)

Конфигурационный файл

Если не укзать данные для доступа к сайту (имя пользователя, пароль, passkey, apikey), то они будут считываться из файла ~/.cinemate или %HOME%\.cinemate в зависимости от операционной системы. Формат файла:

auth:
  username: your_username
  password: your_password
  passkey: your_passkey
  apikey: apikey

Файл может быть создан автоматически при инициализации основного класса в интерактивном режиме:

>>> from cinemate import Cinemate
>>> Cinemate()
Username: your_username
Password:
Passkey:
Apikey:
<Cinemate: your_username>

В целях безопасности пароль, passkey и apikey не отображаются. При инициализации данные будут сохранены и в следующий раз запрашиваться не будут.

Список методов API

Доступ к методам api осуществляется через аттрибуты объекта cinemate. Ниже приведена таблица сооветсвия методов API и данной реализации.

Метод API Описание Метод реализации
account.auth Авторизация по логину и паролю cin.account.auth()
account.profile Данные и статистика пользовательского аккаунта cin.account.profile()
account.updatelist Записи ленты обновлений пользователя cin.account.updatelist()
account.watchlist Метод возвращает список объектов слежения пользователя cin.account.watchlist()
movie Информация о фильме cin.movie.get(id)
movie.list Результаты поиска фильмов, используя заданные фильтры cin.movie.list()
movie.search Поиск по заголовкам фильмов cin.movie.search()
person Основная информация о персоне cin.person.get(id)
person.movies Фильмы, в съемке которых персона принимала участие cin.person(id).movies()
person.search Метод возвращает первые 10 результатов поиска по базе персон cin.person.search()
stats.new Метод возвращает статистику сайта за последние сутки cin.stats.new()

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

Фильмы

class cinemate.Movie(movie_id, **kwargs)[исходный код]

Класс реализуюзий фильмы, сериалы, короткометражки.

Параметры:
  • movie_id (int) – идентификатор фильма на cinemate.cc
  • title (Title) – название
  • year (int) – год выхода
  • type (int) – тип movie, serial, short
  • description (str) – описание
  • imdb (Rating) – рейтинг IMDb
  • kinopoisk (Rating) – рейтинг kinopoisk
  • poster (Poster) – постер фильма
  • release (Release) – даты релиза
  • runtime (int) – продолжительность в минутах
  • trailer (str) – ссылка на трейлер
  • url (str) – ссылка на cinemate.cc
  • genre (Genre) – список жанров
  • country (Country) – список стран
  • cast (list) – список актёров
  • director (list) – список режиссеров
fetch(*args, **kwargs)

Обёртка для метода fetch. Каждый раз после вызова метода экземпляр класса добавляется в _instances.

classmethod from_dict(dct)[исходный код]

Получить информацию о фильме из словаря, возвращаемого API.

Параметры:dct (dict) – словарь, возвращаемый API
Результат:фильм
Тип результата:Movie
classmethod get(movie_id)[исходный код]

Короткий аналог movie(123).fetch()

Параметры:movie_id (int) – идентификатор требуемого фильма
Результат:фильм
Тип результата:Movie
classmethod list(**kwargs)[исходный код]

Метод API movie.list возращает результаты поиска фильмов, используя заданные фильтры. По-умолчанию возвращается 10 первых фильмов.

Параметры:
  • kwargs (dict) – именованные фильтры
  • type (str) – тип фильмов. Возможные значения: movie, serial, short
  • year (int) – год выпуска фильма или сериала
  • genre (str or cinemate.Genre) – slug жанра
  • country (str or cinemate.Country) – slug страны
  • order_by (str) – критерий сортировки: create_date, release_date, ru_release_date
  • order (str) – порядок сортировки параметра order_by: desc, asc
  • order_from (datetime.date or str) – начальная дата среза параметра order_by в формате ДД.ММ.ГГГГ
  • order_to (datetime.date or str) – конечная дата среза параметра order_by в формате ДД.ММ.ГГГГ
  • page (int) – страница в выборке (по умолчанию 0)
  • per_page (int) – количество записей в выборке (по умолчанию 10, максимум 25)
Результат:

список фильмов

Тип результата:

list

Исключение:

ValueError – вызывается если указан один из параметров order_to/order_from, но не указан order_by

classmethod search(term)[исходный код]

Метод API movie.search производит поиск по заголовкам фильмов. Поддерживается уточняющий поиск по году выхода фильма и коррекцию ошибок при печати.

Параметры:term (str) – искомая строка
Результат:список фильов
Тип результата:list
class cinemate.Title(russian='', original='', english='')[исходный код]

Заголовки фильма на разных языках.

Параметры:
  • russian (str) – название фильма на русском языке
  • original (str) – оригинальное название фильма
  • english (str) – название фильма на английском языке
classmethod from_dict(dct)[исходный код]

Задать название фильма из словаря, возвращаемого API.

Параметры:dct (dict) – словарь, возвращаемый API
Результат:фильм
Тип результата:.Movie
class cinemate.Genre(name, slug=None)[исходный код]

Жанр фильма.

Параметры:
  • name (str) – название жанра
  • slug (str) – slug жанра
class cinemate.Poster(small, medium, big)[исходный код]

Постер фильма в трёх размерах.

Параметры:
  • small (str) – ссылка на картинку маленького размера
  • medium (str) – ссылка на картинку среднего размера
  • big (str) – ссылка на картинку большого размера
class cinemate.Release(world=None, russia=None)[исходный код]

Даты релиза фильма.

Параметры:
  • world (str) – дата выхода фильма в прокат
  • russia (str) – дата выхода фильма в российский прокат
class cinemate.Rating(votes=0, rating=0)[исходный код]

Рейтинг фильма imdb и kinopoisk.

Параметры:
  • votes (int) – количесвто отданных голосов
  • rating (float) – рейтинг фильма
class cinemate.Country(name, slug=None)[исходный код]

Страна производства фильма.

Параметры:
  • name (str) – имя страны на русском языке
  • slug (str) – slug страны

Актеры и режиссеры

class cinemate.Person(person_id, **kwargs)[исходный код]

Класс персоны.

Параметры:
  • person_id (int) – идентификатор персоны на cinemate.cc
  • name (str) – русскоязычное имя персоны
  • name_original (str) – имя персоны в оригинале
  • photo (Photo) – фотграфия персоны
  • url (str) – ссылка на страницу персоны
fetch(*args, **kwargs)

Обёртка для метода fetch. Каждый раз после вызова метода экземпляр класса добавляется в _instances.

classmethod from_dict(dct)[исходный код]

Информация о персоне из словаря, возвращаемого API.

Параметры:dct (dict) – словарь, возвращаемый API
Результат:персона
Тип результата:Person
classmethod get(person_id)[исходный код]

Короткий аналог person(123).fetch()

Параметры:person_id (int) – идентификатор персоны
Результат:персона
Тип результата:Person
movies()[исходный код]

Метод API person.movies возвращает фильмы, в съемке которых персона принимала участие в качестве актера или режиссера.

Результат:словарь с ключами actor, director
Тип результата:dict
classmethod search(term)[исходный код]

Метод API movie.search возвращает первые 10 результатов поиска по базе персон.

Параметры:term (str) – искомая строка; поддерживает коррекцию ошибок при печати
Результат:список персон
Тип результата:list
class cinemate.Photo(small, medium, big)[исходный код]

Фотография персоны. Включает в себя 3 тега со ссылками на фотографии разных размеров.

Параметры:
  • small (str) – фотография в маленьком разрешении
  • medium (str) – фотография в среднем разрешении
  • big – фотография в большом разрешении
Type:

big: str

Доступ к пользовательским данным

class cinemate.Account[исходный код]

Класс для получения пользовательских данных.

auth()[исходный код]

Метод API account.auth возвращает passkey.

Результат:passkey
Тип результата:str
profile()[исходный код]

Метод API account.profile получить поля профиля.

Результат:словарь с полями профиля
Тип результата:dict
updatelist()[исходный код]

Метод API account.updatelist возвращает записи ленты обновлений пользователя.

Результат:список персон и фильмов за которыми следит пользователь
Тип результата:list
watchlist()[исходный код]

Метод API account.watchlist возвращает список объектов слежения пользователя.

Результат:словарь объектов слежения с ключами movie, person
Тип результата:dict

Статистика сайта

class cinemate.Stats[исходный код]

Статистика сайта.

new()[исходный код]

Метод API stats.new возвращает статистику сайта за последние сутки.

Результат:словарь содежащий статистику за последние сутки
Тип результата:dict

Расширение функционала

Можно расширить базовый функционал библиотеки собственными методами и классами.

Пример:

from requests import session
from cinemate import Cinemate, Movie
from cinemate.utils import BaseCinemate


class MovieWithLinks(Movie):
    """ Добавление дополнительного метода к основному классу. """
    def links(self):
        return self.cinemate.link.for_movie(self.id)


class Link(BaseCinemate):
    """ Собственный класс для работы с ссылками. """
    @classmethod
    def for_movie(cls, movie_id):
        """ your code here """


class CinemateExtra(Cinemate):
    """ Переопределение главного класса. """
    def __init__(self, *args, **kwargs):
        super(CinemateExtra, self).__init__(*args, **kwargs)
        self.session = session()
        # переопределение класса movie
        self.movie = type('movie', (MovieWithLinks,), {'cinemate': self})
        # добавление класса link
        self.link = type('link', (Link,), {'cinemate': self})

    def login(self):
        """ your code here """