cleverapi 0.3.4
Python Clever Api

# **Clever API**
Библиотека созданная для удобного взаимодействия с API мобильного приложения Клевер, разрабатываемого во ВКонтакте.

## Навигация
- [Установка](#Установка)
- [Использование](#Использование)
- [Получение токена](#Получение-токена)
- [Обработчики](#Обработчики)
- [Действия](#Действия)
- [Отправка ответа](#Отправка-ответа)
- [Бамп](#Бамп)
- [События](#События)
    - [sq_game_winners](#sq_game_winners)
    - [sq_friend_answer](#sq_friend_answer)
    - [sq_question](#sq_question)
    - [sq_ed_game](#sq_ed_game)
    - [sq_question_answers_right](#sq_question_answers_right)
    - [video_comment_new](#video_comment_new)
- [Примеры](#Примеры)

## Установка
Протестирована работа с Python 3.6.

* Установка с помощью pip (пакетный менеджер Python):
```
$ pip install cleverapi --upgrade
```
* Установка из исходного кода (требуется git)
```
$ git clone https://github.com/oncecreated/cleverapi.git
$ cd cleverapi
$ python setup.py install
```

## Использование
Вывод текста вопроса из онлайн викторины:

```python
from cleverapi import CleverApi, CleverLongPoll

api = CleverApi("TOKEN")
lp = CleverLongPoll(api)

@lp.question_handler()
def new_question(event):
    print(event["question"]["text"])

lp.game_waiting()
```
Главной точкой взаимодействия библиотеки с Клевером, является **CleverLongPoll** реализуемый библиотекой. С помощью него становится возможным в реальном времени получать игровые события, будь то ответ вашего друга или новый вопрос.

## Получение токена
Для работы библиотеки необходимо получить access_token приложения Клевер, сделать это можно воспользовавшись ссылкой (access_token будет в адресной строке после подтверждения прав доступа):

`http://oauth.vk.com/authorize?client_id=6334949&scope=589842&display=mobile&response_type=token`

## Обработчики
Поступающие игровые события нужно как-то обрабатывать, для этого нужно использовать специальные обработчики.

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

```python
@lp.game_winners_handler()
def print_winners(event):
    print(event)
```

У функции после декоратора должен быть единственный параметр, отвечающий за информацию о событии.

Список доступных декораторов:

|Декоратор | Тип события | Описание|
|---|---|---|
| `comment_handler`| `video_comment_new`|Событие комментария к игровой трансляции|
| `question_handler`|`sq_question`|Событие нового вопроса|
| `friend_answer_handler`|`sq_friend_answer`|Событие ответа друга пользователя|
| `right_answer_handler`|`sq_question_answers_right`|Событие результата ответа на вопрос|
| `end_game_handler`|`sq_ed_game`|Событие окончания викторины|
| `game_winners_handler`| `sq_game_winners` |Событие списка победивших игроков |
| `start_game_handler`|-|Дополнительный декоратор, сигнализирует о начале игры |
| `all_events_handler`|-|Дополнительный декоратор, служит для получения всех событий пришедших с LongPoll |
| `last_time_answer`|`sq_question`|Дополнительный декоратор, вызываемый в последнее возможное время ответа на вопрос (может быть полезно, когда нужно ответить не сразу после получения вопроса) |


## Действия
В игре существуют некоторые действия, за которые вам начисляют клеверсы. Для начисления виртуальных монеты необходимо самостоятельно вызывать метод **send_action***.

В параметрах необходимо передать тип действия (**cleverapi.Action**) и идентификатор пользователя.

Например, если вы правильно ответили на вопрос, то не забудьте оповестить об этом сервер:
```python
from cleverapi import Action
api.send_action(Action.ANSWER_CORRECT)
```

Список возможных действий:

|Действие | Описание|
|---|---|
| `Action.WATCHED_GAME`|Вы досмотрели игру до конца|
| `Action.JOIN_GAME`|Вы присоединились к игре|
| `Action.ANSWER_CORRECT`|Вы дали правильный ответ|
| `ACtion.WIN_GAME`|Вы выиграли игру|
| `Action.INVITE_FRIEND`|Вы пригласили друга|
| `Action.COMMUNITY_NOTIFY`|Вы подписались на уведомления сообщества Клевер|

## Отправка ответа
Для отправки ответа используется метод. **send_answer**:
```python
api.send_answer(coins_answer, game_id, answer_id, question_id)
```
Параметры метода:
- `coins_answer` (`bool`) - Передавайте True если играете на клеверсы, передавайте значение False, если вы продолжаете играть на деньги. *Осторожно, если вы передадите значение False когда уже выбыли из игры ваш ответ не будет засчитан*
- `game_id` (`int`) - идентификатор текущей игры, его можно получить из атрибута `game_id` класса `CleverLongPoll`

## Бамп
Для бампа используется метод. **bump**:
```python
api.bump(lat, lon)
```
Параметры метода:
- `lat` (`string`) - Широта
- `lon` (`string`) - Долгота

Передаются в виде градусов (xx.xxxxxx)

Внимание: За 1 бамп с 1 человеком дают 50 клеверсов, с 1 человеком можно бампится 1 раз в неделю. Лимит бампов в неделю: 1000 клеверсов.

## События
Игровые события в формате JSON.

### **sq_game_winners** 
```json
{  
   "type":"sq_game_winners",
   "owner_id":-162894513,
   "video_id":456230000,
   "users":[  
      {  
         "name":"Самира В.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Владислав П.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Варвара Д.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Анастасия Ф.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Тёма Б.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Евгений В.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Вячеслав З.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Дарья М.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      },
      {  
         "name":"Светлана С.",
         "photo_url":"https://vk.com/images/camera_200.png?ava=1"
      }
   ],
   "prize":0,
   "winners_num":9,
   "version":2
}
```

### **sq_friend_answer** 
Необходимо купить их отображение за 299 клеверсов (id подарка 50)
```json
{  
   "type":"sq_friend_answer",
   "game_id":200,
   "user_id":100,
   "answer_id":0,
   "photo_url":"https://vk.com/images/camera_200.png?ava=1",
   "is_live_enabled":true
}
```

### **sq_question** 
```json
{  
   "type":"sq_question",
   "owner_id":-162894513,
   "video_id":456239000,
   "question":{  
      "id":11,
      "text":"Кто основал социальную сеть ВКонтакте?",
      "answers":[  
         {  
            "id":0,
            "text":"Николай Дуров"
         },
         {  
            "id":1,
            "text":"Павел Дуров"
         },
         {  
            "id":2,
            "text":"Илон Маск"
         }
      ],
      "time":null,
      "number":1
   },
   "version":2
}
```

### **sq_ed_game**
```json
{  
   "type":"sq_ed_game",
   "owner_id":-162894513,
   "video_id":456230000,
   "version":2
}
```

### **sq_question_answers_right**
```json
{  
   "type":"sq_question_answers_right",
   "owner_id":-162894513,
   "video_id":456230000,
   "question":{  
      "text":"Кто основал социальную сеть ВКонтакте?",
      "answers":[  
         {  
            "id":0,
            "text":"Николай Дуров",
            "users_answered":1584
         },
         {  
            "id":1,
            "text":"Павел Дуров",
            "users_answered":389217
         },
         {  
            "id":2,
            "text":"Илон Маск",
            "users_answered":389
         }
      ],
      "right_answer_id":1,
      "id":11,
      "is_first":true,
      "is_last":false,
      "number":1,
      "sent_time":1529600002,
      "answer_set":true
   },
   "question_time":1529600000,
   "version":2
}
```

### **video_comment_new**
```json
{  
   "type":"video_comment_new",
   "owner_id":-162894513,
   "video_id":456230000,
   "comment":{  
      "id":0,
      "from_id":100,
      "date":152960000,
      "text":"мыши"
   },
   "user":{  
      "id":100,
      "photo_50":"https://vk.com/images/camera_200.png?ava=1",
      "photo_100":"https://vk.com/images/camera_200.png?ava=1",
      "first_name":"Павел",
      "last_name":"Анисимов",
      "sex":2
   },
   "version":2
}
```

## Примеры
[like_friends.py](https://github.com/oncecreated/cleverapi/blob/master/examples/like_friends.py) - использование библиотеки для создания бота, который выбирает наиболее популярный ответ у друзей
[bump.py](https://github.com/oncecreated/cleverapi/blob/master/examples/bump.py) - использование библиотеки для бампа, который происходит в выбранных координатах