Документация пакета gvapi

Пакет gvapi это неофициальный враппер для API игры Годвилль.

Фичи:

  • Создание объекта героя с соответствующими атрибутами
  • Автоматическое обновление данных внутри объекта
  • Отслеживание ошибок с соответствующими исключениями
  • Возможность использоваться расширенного доступа с использованием токена
  • Простая CLI утилита для использования данного пакета

Полезные ссылки:

Оглавление

Быстрый старт

Установка

Данный пакет доступен для установки из PyPi:

python3 -m pip install gvapi

Также можно установить самую последнюю версию из репозитория:

git clone https://github.com/TitaniumHocker/gvapi.git
cd gvapi
python3 -m pip install .

Пример использования

Простейший пример использования будет выглядеть следующим образом.

from gvapi import Hero

hero = Hero('Mars', token='awudhawiudh')
print('ЗЛ: ~{}k, КП: {:.1f}%'.format(hero.goldf, hero.bricks_percent))

Данный скрипт выведет примерное количество золота героя и количество кирпичей.

python3 simple.py
ЗЛ: 8.0k, КП: 43.0%

CLI-утилита

После установки данного пакета становится доступна CLI-утилита с одноименным с пакетом названием. Данная утилита предоставляет простейший интерфейс для доступа к атрибутам героя.

Описание флагов и аргументов данной утилиты доступно при вызове утилиты с флагом –help.

Пример использования

Самый простой пример использования выглядит следующим образом

$ gvapi --god "Some god" name
Some Hero

В данном примере name - это имя атрибута класса Hero.

Конфигурация

Утилита позволяет задавать конфигурацию по умолчанию за счет переменных окружения.

Для установки имени божества по умолчанию необходимо передать переменную окружения GVAPI_GOD.

Установить токен по умолчанию можно через переменную окружения GVAPI_TOKEN.

Данные переменные окружения могут быть заданы в конфигурационном файле используемой оболочки. Для BASH это будет ~/.bashrc, а для ZSH - ~/.zshrc. Пример установки переменных окружения в конфигурационном файле оболочки BASH представлен ниже:

export GVAPI_GOD="Some god"
export GVAPI_TOKEN="awdoja"

Особенности

Данная утилита при каждом своем вызове кэширует состояние объекта героя для предотвращения чрезмерного количества обращений к API. Согласно документации API Годвилля, фактически данные обновляются не чаще, чем раз в минуту, поэтому не имеет смысла обращаться к API чаще чем раз в минуту. Так же в документации можно найти предупреждение, что при слишком частом обращении к API можно получить бан.

Если кэш по какой-либо причине был поврежден, это может привести к непредвиденному поведению утилиты. Для сброса кэша достаточно вызвать утилиту с соответствующим флагом –drop-cache.

API пакета gvapi

Модуль gvapi.hero

Основной модуль пакета, в котором описан класс Hero

class gvapi.hero.Hero(god: str, token: str = None, api_url: str = 'https://godville.net/gods/api', threshold: int = 300)
Базовые классы: object

Герой игры Годвилль

Через данный класс осуществляется доступ к данным героя.

Параметры:
  • god – Имя божества героя
  • token – Токен для доступа к API, optional
  • api_url – URL для доступа к API, optional
  • threshold – Задержка обновления данных о герое в секундах, optional
activatables

Список активируемых предметов.

Type:list
alignment

Характер героя.

Type:str
arena

число побед и поражений на арене.

Type:tuple
ark

Число тварей(ж, м)

Type:tuple
ark_completed_at

Дата постройки ковчега.

Type:str
aura

Аура, если отсутствует - пустая строка

Type:str
boss_name

Имя собранного в лаборатории босса.

Type:str
boss_power

Мощь собранного в лаборатории босса.

Type:str
bricks

Число кирпичей для храма.

Type:int
bricks_percent

Число кирпичей для храма в процентах.

Type:float
clan

Название гильдии героя.

Type:str
clan_pos

Ранг героя в гильдии.

Type:str
diary_last

Последняя запись в дневнике.

Type:str
distance

Дистанция до столицы, при нахождении в любом городе - 0.

Type:int
exp

Прогресс опыта.

Type:int
expired

Флаг актуальности данных, True в случае, когда данные неакутальны.

Type:bool
fight_type

Тип боя

Type:str
from_last_updated

Количество секунд, прошедших с последнего обновления данных.

Type:int
gender

Пол героя.

Type:str
godpower

Количество праны.

Type:int
godpower_percent

Количество праны в процентах.

Type:int
gold

Примерное количество золота.

Type:str
goldf

Приверное количество золота, отформатированное в тысячи.

Type:float
health

Количество очков здоровья героя.

Type:int
health_percent

Количество очков здоровья героя в процентах.

Type:float
inventory

Корнеж из количества предметов в инвентаре, максимального количества предметов и количества активируемых предметов.

Type:tuple
inventory_max_num

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

Type:int
inventory_num

Количество предметов в инвентаре.

Type:int
is_alive

Жив ли герой.

Type:bool
is_fighting

Находится ли герой в бою(арена, босс, заплыв, подземка).

Type:bool
last_upd

Время последнего обновления данных.

Type:datetime
level

Уровень героя.

Type:int
lock

Заблокированы ли запросы к API.

Type:bool
max_godpower

Максимальное количество праны.

Type:int
max_health

Максимальное количество очков здоровья героя.

Type:int
motto

Девиз героя.

Type:str
name

Имя героя.

Type:str
quest

Текст текущего задания.

Type:str
quest_progress

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

Type:float
savings

Примерное число сбережений.

Type:str
savings_completed_at

Дата окончания сбора пенсии.

Type:str
savingsf

Отформатированное в миллионы число сбережений

Type:float
shop_name

Название лавки, только у пенсионеров.

Type:str
sync() → None

Синхронизировать данные

Произвести синхронизацию данных. Синхронизация производится только в случае если прошла задержка обновления данных(threshold).

t_level

Троговый уровень.

Type:int
temple_completed_at

Когда был достроен храм.

Type:str
threshold

Задержка обновления данных о герое в секундах.

Type:int
token

Токен в защищенном формате(не скрыты только последние 4 символа). Если токен не используется, то возвращает None

Type:str
town_name

Имя города, пустая строка если в поле или в бою.

Type:str
wood_count

Количество поленьев.

Type:int
words

Количество слов в книге.

Type:int

Модуль gvapi.pet

class gvapi.pet.Pet(hero)
Базовые классы: object

Класс питомца

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

Параметры:hero (Hero) – экземпляр класса героя, которому принадлежит данный питомец
class_name

Вид питомца.

Type:str
level

Уровень питомца.

Type:int
name

Имя питомца.

Type:str
wounded

Контужен ли питомец.

Type:bool

Модуль gvapi.util

В данном модуле расположены всякие штучки, в часности декораторы необходимые для корректной работы классов Hero и Pet

gvapi.util.syncing(func: Callable[[Any], Any]) → Callable[[Any], Any]

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

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

Параметры:func – декорируемый метод
Результат:метод, обернутый в декоратор
gvapi.util.tokenized(func: Callable[[Any], Any]) → Callable[[Any], Any]

Декоратор для метода, требующего использования токена.

При вызове метода, обернутого в данный декоратор, произойдет проверка на наличие токена в классе переданного метода.

Параметры:

func – декорируемый метод
Результат:

метод, обернутый в декоратор
Исключение:
  • NeedToken – в случае, если производится обращение к атрибуту, доступному только при использовании токена, без использования токена.
  • InvalidToken – в случае, если токен невалиден или был сброшен.

Модуль gvapi.errors

Модуль с исключениями.

В данном модуле описаны исключения, использующиеся в пакете.

exception gvapi.errors.APIUnavailable(exc: Exception, message: str = 'API Недоступно {}')
Базовые классы: gvapi.errors.GVAPIException

API недоступно.

exception gvapi.errors.GVAPIException
Базовые классы: Exception

Общее исключение пакета. От данного исключения наследуются остальные исключения пакета.

exception gvapi.errors.InvalidToken(token: str, message: str = 'Токен {} невалиден или был сброшен')
Базовые классы: gvapi.errors.GVAPIException

Токен невалилен или был сброшен.

exception gvapi.errors.MinThresholdException
Базовые классы: gvapi.errors.GVAPIException

Порог обновления меньше минимального значения.

exception gvapi.errors.NeedToken(message: str = 'Для доступа к данному атрибуту необходим токен')
Базовые классы: gvapi.errors.GVAPIException

Для доступа необходим токен.

exception gvapi.errors.TheArkIsUndone
Базовые классы: gvapi.errors.GVAPIException

Ковчег еще не построен.

exception gvapi.errors.TheSavingsInUndone
Базовые классы: gvapi.errors.GVAPIException

Сбережения(пенсия) еще не собраны.

exception gvapi.errors.TheTempleIsUndone
Базовые классы: gvapi.errors.GVAPIException

Храм еще не построен.

exception gvapi.errors.UnexpectedAPIResponse(resp: requests.models.Response, message: str = 'Непредвиденный ответ API {}: {}')
Базовые классы: gvapi.errors.GVAPIException

Непредвиденный ответ API.

exception gvapi.errors.UnknownGod(god: str, message: str = 'Божество {} не было найдено.')
Базовые классы: gvapi.errors.GVAPIException

Бог не был найден.

Лицензия исходного кода

MIT License

Copyright (c) 2020 Ivan Fedorov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the «Software»), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED «AS IS», WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Помощь

Нашел ошибку, есть вопрос или предложение? Открой issue на GitHub