.. only:: html

.. _capi-event:

Обработка событий. Модуль event
=================================

.. automodule:: event  

Генерация событий
^^^^^^^^^^^^^^^^^^^^^^

В момент изменения данных пользователем, перед записью изменений
в базу данных вызывается функция :py:func:`before_event() <event.before_event>`. 
Если в теле этой функции генерируется исключение,
отправка изменений отменяется и пользователю выводится
сообщение об исключении. 

Если код выполнен без исключений, то происходит запись изменений.

Если в момент записи возникла ошибка, например, пропало соединение
с интернетом или пользователь не имеет прав на данное изменение,
вызывается функция :py:func:`error_event() <event.error_event>`.

Если запись изменений произошла корректно,
вызывается функция :py:func:`after_event() <event.after_event>`.

.. automodule:: translate.event_generating

.. rubric:: Схема события
    
.. image:: ../img/capi_event.png
    :align: center

Рассмотрим, как происходит событие на примере создания нового
сообщения в приложении Cerebro.

Пользователь пишет сообщение, прикладывает файлы и нажимает
кнопку "Отправить".
В этот момент происходит вызов функции :py:func:`before_event() <event.before_event>`.

event.py::

    def before_event(event):	
        ...

Если во время выполнения кода функции :py:func:`before_event() <event.before_event>`
было сгенерировано исключение,
то пользователю будет показано уведомление,
и создание нового сообщения не произойдет,
но перед пользователем останется интерфейс создания сообщения
с введенным им текстом и вложениями.

event.py::
    
    def before_event(event):	
        ...
        raise Exception('Ouch')
        ...

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

Если во время добавления происходит ошибка,
то сообщение не добавляется, пользователь получает сообщение
о причине ошибки и вызывается функция :py:func:`error_event() <event.error_event>`.

event.py::
    
    def error_event(error, event):		
        ...

Если добавление сообщения прошло успешно, то вызывается
функция :py:func:`after_event() <event.after_event>`.

event.py::
    
    def after_event(event):
        ...

Если во время выполнения кода функции after_event было сгенерировано
исключение, то пользователю будет показано сообщение
с этим исключением.

.. _capi-event-func:

Функции обработки событий
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. //comment
.. py:module:: event
    :noindex:

.. py:function:: before_event(event)

    В функцию передается объект события с определенными свойствами,
    которые позволяют определить, какое изменение данных произойдет
    и внести собственные изменения.

    В теле функции могут выполняться различные проверки и вноситься
    изменения в данные, которые затем будут переданы в приложение. 
    Это способ контроля изменения данных пользователем,
    который позволяет проверять эти данные перед их записью
    в базу данных, корректировать или отменять их.  
    Для того чтобы отменить событие (изменение данных),
    нужно в сгенерировать исключение. В этом случаи обработка события
    будет остановлена и пользователю будет показано сообщение
    исключения.

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

.. py:function:: after_event(event)

    В функцию передается объект события
    с определенными свойствами, которые позволяют определить,
    какое изменение данных произошло.

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


.. py:function:: error_event(error, event)

    При вызове этой функции в неё передается
    объект ошибки и объект события, которые позволяют определить,
    какая ошибка и при каком событии произошла.
    Вызов функции происходит в случаи какой-либо ошибки,
    произошедшей в момент внесения данных в базу.

Классы объектов событий описаны в модуле :py:mod:`cerebro.events`
пакета :py:mod:`cerebro`.


Типы событий
^^^^^^^^^^^^^^^^^^

Типы события различаются типом изменения данных.
Например, есть такие типы как,
:py:const:`создание сообщения
<cerebro.events.Event.EVENT_CREATION_OF_MESSAGE>`,
:py:const:`создание задачи
<cerebro.events.Event.EVENT_CREATION_OF_TASK>`,
:py:const:`изменение прогресса
<cerebro.events.Event.EVENT_CHANGING_OF_TASKS_PROGRESS>` и т.д. 

.. automodule:: translate.event_types

В функцию :py:func:`error_event() <event.error_event>` передаются
:py:class:`объект ошибки <cerebro.events.EventError>`,
и :py:mod:`объекты классов <cerebro.events>`,
имя которых начинается с Before... Это тот же объект,
который передаётся в функцию :py:func:`before_event() <event.before_event>`,
только без возможности производить изменения.


Все типы событий описаны в модуле :py:mod:`cerebro.events`
пакета :py:mod:`cerebro` в 
:py:const:`базовом классе события Event <cerebro.events.Event.EVENT_>`.

С примерами обработки событий можно ознакомится
:ref:`здесь <capi-examples>`.