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

Модуль event позволяет обрабатывать события, происходящие в приложении.

event.py:

def before_event(error, event): 
        ...

def after_event(event): 
        ...
        
def error_event(event): 
        ...

События происходят при изменении данных в приложении пользователем и программный интерфейс позволяет управлять этими событиями. Приложение генерирует события при выполнении определенных действий. При этом вызываются соответствующие функции before_event(), after_event() или error_event() из модуля event.

События происходят при операциях изменения данных, поэтому смысл этих функций сводится к следующему:

  • before_event() - действие перед изменением данных;
  • after_event() - действие после изменения данных;
  • error_event() - обработка ошибки изменения данных.

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

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

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

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

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

Событие без ошибок:

before_event(event)
...
# приложение сохраняет изменения
...    
after_event(event)

Событие с генерацией исключения в before_event:

before_event(event)
    ...
    raise Exception('Отменить изменение')        
...
# приложение показывает сообщение исключения

Событие c ошибкой сохранения изменений:

before_event(event)
...
# приложение сохраняет изменения... Возникла ошибка
# приложение показывает сообщение ошибки
...    
error_event(error, event)

Схема события

_images/capi_event.png

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

Пользователь пишет сообщение, прикладывает файлы и нажимает кнопку «Отправить». В этот момент происходит вызов функции before_event().

event.py:

def before_event(event):
    ...

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

event.py:

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

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

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

event.py:

def error_event(error, event):
    ...

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

event.py:

def after_event(event):
    ...

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

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

event.before_event(event)[исходный код]

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

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

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

event.after_event(event)[исходный код]

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

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

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

event.error_event(error, event)[исходный код]

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

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

8.3. Типы событий

Типы события различаются типом изменения данных. Например, есть такие типы как, создание сообщения, создание задачи, изменение прогресса и т.д.

Для каждого типа события, существует набор классов описания объектов, которые передаются в функции обработки событий. По типу события и функции обработки, определяется интерфейс объекта события.

event.py:

def before_event(event):    
    if (event.event_type() == event.EVENT_CREATION_OF_MESSAGE) # создание сообщения
        # объект event использует интерфейс класса BeforeEventCreationOfMessage

def after_event(event):     
    if (event.event_type() == event.EVENT_CREATION_OF_MESSAGE) # создание сообщения
        # объект event использует интерфейс класса AfterEventCreationOfMessage

def error_event(error, event):      
    if (event.event_type() == event.EVENT_CREATION_OF_MESSAGE) # создание сообщения
        # объект event использует интерфейс класса BeforeEventCreationOfMessage

Как правило, в функцию before_event() передаются объекты классов, имя которых начинается с Before… Tакие объекты имеют функции, позволяющие узнать текущие значения, новые значения и внести дополнительные изменения.

def before_event(event):    
    if (event.event_type() == event.EVENT_CHANGING_OF_MESSAGE) # редактирование сообщения
        omessage = event.original_message() # получаем объект оригинального сообщения
        
        if (event.work_time() != omessage.work_time())  # сравниваем текущее значение рабочего времени сообщения и вновь введенного пользователем.
            raise Exception('Изменение рабочих часов невозможно!')
            
        event.set_client_visible(True) # устанавливаем видимость для клиентов

В функцию after_event() передаются объекты классов, имя которых начинается с After… Tакие объекты имеют функции, позволяющие узнать новые значения.

def after_event(event):     
    if (event.event_type() == event.EVENT_CHANGING_OF_TASKS_NAME) # изменение имени задачи
        task_name = event.name() # получаем новое имя

В функцию error_event() передаются объект ошибки, и объекты классов, имя которых начинается с Before… Это тот же объект, который передаётся в функцию before_event(), только без возможности производить изменения.

Все типы событий описаны в модуле cerebro.events пакета cerebro в базовом классе события Event.

С примерами обработки событий можно ознакомится здесь.