polka 2.5.0
A module provides access to the public Polka API. (https://polka.academy/).
License: MIT
Requires Python: >=3.6,<4.0
Keywords: polka,books,russian,api

# ПОЛКА

Python модуль для доступа к API образовательного проекта [«Полка»](https://polka.academy).

## Установка

Для работы модуля требуется Python 3.6+. Никаких зависимостей, кроме стандартной библиотеки нет.

```python
pip install polka
```

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

Для получения данных в сыром виде «как есть», существуют функции `rawbooks`, `rawbook`, `rawsearch`, `rawlists`, `rawlist` и другие начинающиеся на `raw`.


```python
>>> import polka

>>> [func for func in dir(polka) if func.startswith("raw")]
['rawbook', 'rawbooks', 'rawlist', 'rawlists', 'rawpunditfavs', 'rawpunditposts', 'rawpundits', 'rawsearch']
```

Но удобнее использовать функции `books`, `lists`, `pundits`, `search` и объекты `Book`, `Compilation` и `Pundit`.

Функция `books` возвращает список книг, каждая из которых является объектом `Book`.

```python
>>> for book in polka.books()[:3]:
...     assert isinstance(book, polka.Book)
...     print(f"{book.title:<25} {book.year.start}")
Герой нашего времени      1840
Анна Каренина             1877
Мёртвые души              1842
```

`Book` содержит всю доступную информацию о книге, включая вопросы и ответы (если имеются).

```python
>>> book
Book(title='Мёртвые души', authors=['Николай Гоголь'])

>>> book.description
'Великая поэма, праздник нелепости и гротеска, от которой парадоксальным образом отсчитывают историю русского реализма. Задумав трёхчастное произведение по образцу «Божественной комедии», Гоголь успел завершить только первый том — в котором ввёл в литературу нового героя, дельца и плута, и создал бессмертный образ России как птицы-тройки, несущейся в неизвестном направлении.'

>>> book.pundit
Pundit(name='Варвара Бабицкая')

>>> item = book.questions[0] # first question
>>> item.question
'О чём эта книга?'

>>> item.answer # or item.answer_with_notes
'В губернский город N. приезжает отставной чиновник Павел Иванович Чичиков, человек, лишённый отличительных черт и всем приходящийся по нраву. Очаровав губернатора, городских чиновников и окрестных помещиков, Чичиков начинает объезжать последних с загадочной целью: он скупает мёртвые души, то есть умерших недавно крепостных, которые ещё не внесены в ревизскую сказку и потому формально считаются живыми. Навестив последовательно карикатурных, каждый в своём роде, Собакевича, Манилова, Плюшкина, Коробочку и Ноздрёва, Чичиков оформляет купчие и готовится довести до конца свой таинственный план, но к концу первого (и единственного завершённого) тома поэмы в городе N. сгущаются какие-то хтонические силы, разражается скандал, и Чичиков, по формулировке Набокова, «покидает город на крыльях одного из тех восхитительных лирических отступлений... которые писатель всякий раз размещает между деловыми встречами персонажа». Так заканчивается первый том поэмы, задуманной Гоголем в трёх частях; третий том так и не был написан, а второй Гоголь сжёг — сегодня нам доступны только его реконструкции по сохранившимся отрывкам, причём в разных редакциях, поэтому, говоря о «Мёртвых душах», мы подразумеваем в общем случае только первый их том, завершённый и опубликованный автором.'
```

Функция `pundits` возвращает список представленных на сайте экспертов.

```python
>>> for expert in polka.pundits()[:3]:
...     assert isinstance(expert, polka.Pundit)
...     print(expert)
Pundit(name='Евгения Абелюк')
Pundit(name='Михаил Айзенберг')
Pundit(name='Александр Архангельский')
```

Каждый эксперт представлен объектом `Pundit`.

```python
>>> expert
Pundit(name='Варвара Бабицкая')

>>> expert.credit
'Литературный критик, редактор проекта «Полка»'

>>> expert.description
'Редактор, литературный критик, переводчик. Редактор проекта «Полка». Делала литературные и культурные разделы и печаталась на портале OpenSpace.ru, а затем Colta.ru, в проекте «Сноб», на радио «Свободная Европа»/«Радио Свобода», в журнале The New Times, писала для сайта «Афиша–Воздух», сайта «Горький» и других. Как редактор и переводчик сделала несколько книг для издательств «НЛО», Corpus, «Стрелка».'

>>> for book in expert.wrote_about:
...     print(book)
Book(title='Горе от ума', authors=['Александр Грибоедов'])
Book(title='Житие протопопа Аввакума', authors=['Аввакум Петров'])
Book(title='Картины прошедшего', authors=['Александр Сухово-Кобылин'])
Book(title='Колымские рассказы', authors=['Варлам Шаламов'])
Book(title='Леди Макбет Мценского уезда', authors=['Николай Лесков'])
Book(title='Мёртвые души', authors=['Николай Гоголь'])

>>> expert.favorites
[]
```

Функция `lists` возвращает компиляции книг по темам и направлениям.

```python
>>> for compilation in polka.lists()[:3]:
...     print(compilation)
Compilation(title='Древняя Русь')
Compilation(title='Русский классицизм')
Compilation(title='Открытие истории')
```

Каждый список представлен объектом `Compilation`.

```python
>>> compilation
Compilation(title='Антиутопия')

>>> compilation.short_description
'От строительства «Интеграла» до Дня открытых убийств'

>>> compilation.description
'Первопроходцем жанра антиутопии в XX веке оказывается Евгений Замятин, однако затем эстафету подхватывают Америка и Европа: в Советском Союзе антиутопия перестаёт быть фактом литературы и реализуется на практике. Создатели советских антиутопий, появившихся после долгого перерыва, уже учитывали опыт Хаксли и Оруэлла, имея, однако, перед ними то жутковатое преимущество, что советские антиутопии пишутся во многом с натуры. Тоталитарное государство посягает на основные права и потребности человека, распоряжается его жизнью и свободой, залезает к нему в постель, в кастрюлю и в голову, а литература пытается понять те социальные и психические механизмы, которые сделали это возможным: сперва противясь наступлению тоталитаризма, человек со временем приспосабливается и даже пытается использовать с итуацию к своей выгоде.'

>>> for book in compilation.books:
...     print(book)
Book(title='Мы', authors=['Евгений Замятин'])
Book(title='Говорит Москва', authors=['Юлий Даниэль'])
Book(title='Улитка на склоне', authors=['Аркадий Стругацкий', 'Борис Стругацкий'])
Book(title='Невозвращенец', authors=['Александр Кабаков'])
```

Функция `search` ищет указанную подстроку среди статей, списков и экспертов.

```python
>>> for title, entry, obj in polka.search("двойник")[:3]:
...     assert isinstance(obj, (polka.Book, polka.Pundit, polka.Compilation))
...     print(f"{title.upper()}: ...{entry}...")
ФЁДОР ДОСТОЕВСКИЙ «БЕДНЫЕ ЛЮДИ»: ...людей», Достоевский сразу же принялся за повесть «Двойник» о...
АЛЕКСАНДР ПУШКИН «ЦЫГАНЫ»: ...выполняет важную функцию в сюжете поэмы — своеобразного двойника...
МИХАИЛ ЛЕРМОНТОВ «ГЕРОЙ НАШЕГО ВРЕМЕНИ»: ...Как и пародийный Грушницкий, этот двойник должен быть...
```

[��](#ПОЛКА)