.. only:: html
.. _capi-event:
Обработка событий. Модуль event
=================================
.. automodule:: event
Генерация событий
^^^^^^^^^^^^^^^^^^^^^^
В момент изменения данных пользователем, перед записью изменений
в базу данных вызывается функция :py:func:`before_event() `.
Если в теле этой функции генерируется исключение,
отправка изменений отменяется и пользователю выводится
сообщение об исключении.
Если код выполнен без исключений, то происходит запись изменений.
Если в момент записи возникла ошибка, например, пропало соединение
с интернетом или пользователь не имеет прав на данное изменение,
вызывается функция :py:func:`error_event() `.
Если запись изменений произошла корректно,
вызывается функция :py:func:`after_event() `.
.. automodule:: translate.event_generating
.. rubric:: Схема события
.. image:: ../img/capi_event.png
:align: center
Рассмотрим, как происходит событие на примере создания нового
сообщения в приложении Cerebro.
Пользователь пишет сообщение, прикладывает файлы и нажимает
кнопку "Отправить".
В этот момент происходит вызов функции :py:func:`before_event() `.
event.py::
def before_event(event):
...
Если во время выполнения кода функции :py:func:`before_event() `
было сгенерировано исключение,
то пользователю будет показано уведомление,
и создание нового сообщения не произойдет,
но перед пользователем останется интерфейс создания сообщения
с введенным им текстом и вложениями.
event.py::
def before_event(event):
...
raise Exception('Ouch')
...
Если выполнение кода произошло без исключительной ситуации,
происходит добавление нового сообщения в базу данных.
Если во время добавления происходит ошибка,
то сообщение не добавляется, пользователь получает сообщение
о причине ошибки и вызывается функция :py:func:`error_event() `.
event.py::
def error_event(error, event):
...
Если добавление сообщения прошло успешно, то вызывается
функция :py:func:`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:`создание сообщения
`,
:py:const:`создание задачи
`,
:py:const:`изменение прогресса
` и т.д.
.. automodule:: translate.event_types
В функцию :py:func:`error_event() ` передаются
:py:class:`объект ошибки `,
и :py:mod:`объекты классов `,
имя которых начинается с Before... Это тот же объект,
который передаётся в функцию :py:func:`before_event() `,
только без возможности производить изменения.
Все типы событий описаны в модуле :py:mod:`cerebro.events`
пакета :py:mod:`cerebro` в
:py:const:`базовом классе события Event `.
С примерами обработки событий можно ознакомится
:ref:`здесь `.