Merge pull request #12 from TitaniumHocker/RELEASE-0.6

Release 0.6

docs/cli.rst

@@ -0,0 +1,56 @@
+CLI-утилита
+===========
+
+После установки данного пакета становится доступна CLI-утилита
+с одноименным с пакетом названием. Данная утилита предоставляет
+простейший интерфейс для доступа к атрибутам героя.
+
+Описание флагов и аргументов данной утилиты доступно при
+вызове утилиты с флагом `--help`.
+
+Пример использования
+--------------------
+
+Самый простой пример использования выглядит следующим образом
+
+.. code-block:: bash
+
+   $ gvapi --god "Some god" name
+   Some Hero
+
+В данном примере `name` - это имя атрибута класса `Hero`.
+
+Конфигурация
+------------
+
+Утилита позволяет задавать конфигурацию по умолчанию за счет
+переменных окружения.
+
+Для установки имени божества по умолчанию
+необходимо передать переменную окружения `GVAPI_GOD`.
+
+Установить токен по умолчанию можно через переменную окружения `GVAPI_TOKEN`.
+
+Данные переменные окружения могут быть заданы в конфигурационном
+файле используемой оболочки. Для BASH это будет `~/.bashrc`, а для
+ZSH - `~/.zshrc`. Пример установки переменных окружения в конфигурационном
+файле оболочки BASH представлен ниже:
+
+.. code-block:: bash
+
+   export GVAPI_GOD="Some god"
+   export GVAPI_TOKEN="awdoja"
+
+Особенности
+-----------
+
+Данная утилита при каждом своем вызове кэширует состояние объекта героя
+для предотвращения чрезмерного количества обращений к API. Согласно
+документации API Годвилля, фактически данные обновляются не чаще, чем
+раз в минуту, поэтому не имеет смысла обращаться к API чаще чем раз в минуту.
+Так же в документации можно найти предупреждение, что при слишком частом
+обращении к API можно получить бан.
+
+Если кэш по какой-либо причине был поврежден, это может привести к
+непредвиденному поведению утилиты. Для сброса кэша достаточно вызвать
+утилиту с соответствующим флагом `--drop-cache`.

docs/conf.py

@@ -22,7 +22,7 @@
 author = 'Titanium Hocker(Ivan Fedorov)'
 
 # The full version, including alpha/beta/rc tags
-release = '0.5'
+release = '0.6'
 
 
 # -- General configuration ---------------------------------------------------

docs/index.rst

@@ -9,6 +9,7 @@
  - Автоматическое обновление данных внутри объекта
  - Отслеживание ошибок с соответствующими исключениями
  - Возможность использоваться расширенного доступа с использованием токена
+ - Простая CLI утилита для использования данного пакета
 
 **Полезные ссылки:**
 
@@ -22,6 +23,7 @@
    :maxdepth: 2
 
    quickstart
+   cli
    gvapi
    license
 

gvapi/cli.py

@@ -1,19 +1,62 @@
 # -*- coding: utf-8 -*-
-'''Модуль, описывающий CLI-утилиту пакета gvapi'''
+"""Модуль, описывающий CLI-утилиту пакета gvapi"""
+import sys
 from os import environ
+from pathlib import Path
+from hashlib import md5
+import pickle
 import click
+from gvapi import Hero, errors
 
-from gvapi import Hero
 
+@click.command()
+@click.option('-g', '--god', required=False, default=environ.get('GVAPI_GOD'), help='Имя божества')
+@click.option('-t', '--token', required=False, default=environ.get('GVAPI_TOKEN'), help='Токен')
+@click.option('--drop-cache', is_flag=True, default=False, help='Сбросить кэш при выполнении')
+@click.argument('property_name', required=True)
+def cli(god, token, drop_cache, property_name):
+    """CLI-интерфейс для доступа к API игры Годвилль.
 
-@click.group()
-@click.option('--verbose', is_flag=True, default=False, help='Запуск в режиме отладки.')
-@click.pass_context
-def cli(ctx, verbose):
-    '''CLI-интерфейс для доступа к API игры Годвилль.'''
-    ctx.ensure_object(dict)
-    ctx.obj['verbose'] = verbose
+    Аргументы:
 
+        PROPERTY_NAME Имя свойства героя
 
-if __name__ == '__main__':
-    cli(obj={})
+    Полный список свойств и примеры использования данного
+    CLI-интерфейса можно получить в документации."""
+    if not god:
+        raise errors.GVAPIException('Не получено имя божества.')
+
+    cache_dir = Path(Path.joinpath(Path.home(), '.cache', 'gvapi'))
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    if token:
+        cache_filename = md5('{}:{}'.format(god, token).encode()).hexdigest()
+    else:
+        cache_filename = md5(god.encode()).hexdigest()
+
+    cache = Path(Path.joinpath(cache_dir, cache_filename))
+
+    if cache.is_file() and not drop_cache:
+        with open(cache, 'rb') as dump:
+            hero = pickle.loads(dump.read())
+    else:
+        if token:
+            hero = Hero(god, token)
+        else:
+            hero = Hero(god)
+
+    try:
+        value = getattr(hero, property_name)
+    except AttributeError:
+        click.echo("Получено некорректное свойство {}".format(property_name))
+        sys.exit(1)
+    except errors.NeedToken:
+        click.echo('Для доступа к данному свойству необходим токен')
+        sys.exit(1)
+    except errors.InvalidToken:
+        click.echo("Токен невалиден или был сброшен")
+        sys.exit(1)
+    click.echo(value)
+
+    with open(cache, 'wb') as dump:
+        dump.write(pickle.dumps(hero))

gvapi/errors.py

@@ -1,64 +1,64 @@
 # -*- coding: utf-8 -*-
-'''Модуль с исключениями.
+"""Модуль с исключениями.
 
-В данном модуле описаны исключения, использующиеся в пакете.'''
+В данном модуле описаны исключения, использующиеся в пакете."""
 from requests import Response
 
 
 class GVAPIException(Exception):
-    '''Общее исключение пакета.
+    """Общее исключение пакета.
     От данного исключения наследуются остальные исключения пакета.
-    '''
+    """
 
 class UnknownGod(GVAPIException):
-    '''Бог не был найден.'''
+    """Бог не был найден."""
     def __init__(self, god: str, message: str = 'Божество {} не было найдено.'):
         self.god = god
         self.message = message.format(self.god)
         super().__init__(self.message)
 
 
 class APIUnavailable(GVAPIException):
-    '''API недоступно.'''
+    """API недоступно."""
     def __init__(self, exc: Exception,  message: str = 'API Недоступно {}'):
         self.message = message.format(exc)
         super().__init__(self.message)
 
 
 class UnexpectedAPIResponse(GVAPIException):
-    '''Непредвиденный ответ API.'''
+    """Непредвиденный ответ API."""
     def __init__(self, resp: Response, message: str = 'Непредвиденный ответ API {}: {}'):
         self.resp = resp
         self.messsage = message.format(resp.status_code, resp.text)
         super().__init__(self.messsage)
 
 
 class InvalidToken(GVAPIException):
-    '''Токен невалилен или был сброшен.'''
+    """Токен невалилен или был сброшен."""
     def __init__(self, token: str, message: str = 'Токен {} невалиден или был сброшен'):
         self.token = token
         self.message = message.format(token)
         super().__init__(self.message)
 
 
 class NeedToken(GVAPIException):
-    '''Для доступа необходим токен.'''
+    """Для доступа необходим токен."""
     def __init__(self, message: str = 'Для доступа к данному атрибуту необходим токен'):
         self.message = message
         super().__init__(self.message)
 
 
 class TheTempleIsUndone(GVAPIException):
-    '''Храм еще не построен.'''
+    """Храм еще не построен."""
 
 
 class TheArkIsUndone(GVAPIException):
-    '''Ковчег еще не построен.'''
+    """Ковчег еще не построен."""
 
 
 class TheSavingsInUndone(GVAPIException):
-    '''Сбережения(пенсия) еще не собраны.'''
+    """Сбережения(пенсия) еще не собраны."""
 
 
 class MinThresholdException(GVAPIException):
-    '''Порог обновления меньше минимального значения.'''
+    """Порог обновления меньше минимального значения."""