====== Константы ======

^ Имя ^ Значение ^ Описание ^
| ''SESSION_TIMEOUT'' | ''86400'' | Продолжительность сессии пользователя в секундах |


====== Исключения ======

^ Имя ^ Предок ^ Описание ^
| ''IDError'' | ''aw_web_tools.Error'' | Общий класс ошибок идентификации |
| ''IDCheckError'' | ''IDError'' | Ошибка проверки ID |
| ''IDNotFound'' | ''IDCheckError'' | Запрос не идентифицирован |
| ''UIDError'' | ''IDError'' | Ошибки при работе с классом пользовательского идентификатора |


====== Классы объектов ======

===== UID =====

Класс пользовательского идентификатора.

Обеспечивает хранение идентификационной информации о пользователе.

==== Свойства объекта ====

^ Свойство ^ Описание ^
| ''name'' | Имя пользователя |
| ''level'' | Заданный пользователю уровень допуска |
| ''sess_id'' | Заданный ID сессии работы с системой |


==== Конструктор ====

<code>
UID(uname, [acc_level], [sess_id], [acc_tags], [user_meta])
</code>

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''uname'' | ''str'' |  --  | Имя пользователя внутри системы |
| ''acc_level'' | ''int'' | ''-1'' | Уровень допуска пользователя. Интерпретация целиком на стороне приложения. |
| ''sess_id'' | ''str'' | ''None'' | Идентификатор сессии пользователя |
| ''acc_tags'' | ''Iterable[str]'' | ''None'' | Строковые константы, определяющие конкретное множество доступных пользователю ресурсов. Интерпретация целиком на стороне приложения. |
| ''user_meta'' | ''Dict[str, str]'' | ''None'' | Иная полезная приложению информация, сохранённая в виде тег-значение |


==== Преобразование в строку ====

При вызове
<code>
str(obj)
</code>
Значением будет имя пользователя.


==== get_access() ====

Получить теги доступа, заданные параметром ''acc_tags'' конструктора.
<code>
obj.get_access()
</code>

**Возвращает:** Список тегов доступа либо пустой список, если их не заданно.


==== get_meta() ====

Получить словарь метаинформации о пользователе, заданной параметром ''user_meta'' конструктора.
<code>
obj.get_meta()
</code>

**Возвращает:** Словарь с мета-информацией либо пустой словарь, если она не заданна.


==== to_dict() ====

Создаёт словарь на основе объекта. Словарь получается следующей структуры:
<code yaml>
n: obj.name,
id: obj.sess_id
al: obj.level
a: obj.get_access()
m: obj.get_meta()
</code>


===== IDHelper =====

Класс поддержки идентификации. Может выступать в качестве **плагина ''bottle''**, а также декорировать методы обработки url данного фреймворка.


==== Конструктор ====

<code>
IDHelper(app_name, sign_secret, [sess_timeout])
</code>

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''app_name'' | ''str'' |  --  | Имя приложения. Допускаются цифры символы латиницы и знак ''-'', остальное запрещено |
| ''sign_secret'' | ''str'' |  --  | Ключ подпись JWT для построения cookie |
| ''sess_timeout'' | ''int'' | ''SESSION_TIMEOUT'' | Время жизни сессии пользователя |


==== make_cookie() ====

Формирует объект ''Cookie'' для идентификации сессии пользователя.

<code>
obj.make_cookie([uid], [request], [is_secure], [is_httponly])
</code>

**Возвращает:** Объект [[.:cookie#Cookie]], на основе данного [[#UID]].

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''uid'' | ''UID'' | ''None'' | [[#UID]] на основе которого формируется cookie. Если не задано (''None'') берётся из контекста запроса |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Экземпляр запроса, на основании которого формируется ответ. |
| ''is_secure'' | ''bool'' | ''True'' | Установить признак ''secure'' на cookie |
| ''is_httponly'' | ''bool'' | ''True'' | Установить признак ''httponly'' на cookie |

Имя cookie при этом имеет вид:
<code bash>
X-ID-${obj.app_name}
</code>
То есть строится на основе имени приложения, заданного при создании объекта


==== set_id() ====

Установка cookie на ответ пользователю

<code>
obj.set_id([uid], [response], [request], [is_secure], [is_httponly])
</code>

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''uid'' | ''UID'' | ''None'' | [[#UID]] на основе которого формируется cookie. Если не задано (''None'') берётся из контекста запроса |
| ''response'' | ''bottle.BaseResponse'' | ''bottle.response'' | Объект ответа, на который устанавливаем cookie. |
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Экземпляр запроса, на основании которого формируется ответ. |
| ''is_secure'' | ''bool'' | ''True'' | Установить признак ''secure'' на cookie |
| ''is_httponly'' | ''bool'' | ''True'' | Установить признак ''httponly'' на cookie |


==== env_id() ====

Получаем ID из контекста запроса (для случая, когда проверка и валидация ID проведена на уровне плагина или декоратора

**Метод статический**

<code>
IDHelper.env_id([request])
</code>

**Возвращает:** Объект [[#UID]], связанный с данным запросом, или возбуждает ''IDNotFound'', если он не задан.

^ Параметр ^ Тип ^ По умолчанию ^ Описание ^
| ''request'' | ''bottle.BaseRequest'' | ''bottle.request'' | Экземпляр обрабатываемого запроса. |


==== need_id() ====

Декоратор для проверки UID для заданного пути в приложении.
<code python>

app = bottle.Bottle()

id_helper = IDHelper('some_name', 'some Very $ecr3t K3y')

@id_helper.need_id
@app.get('/resource'):
  pass
</code>