Сигналы¶

Функции приемника¶

Во-первых, нам нужно определить функцию-приемник. Приемником может быть любая функция или метод Python:

def my_callback(sender, **kwargs):
    print("Request finished!")

Обратите внимание, что функция принимает аргумент sender, а также аргументы ключевого слова (**kwargs); все обработчики сигналов должны принимать эти аргументы.

Мы рассмотрим посылающие сигналы a bit later, но сейчас обратите внимание на аргумент **kwargs. Все сигналы посылают аргументы с ключевыми словами и могут изменить эти аргументы в любой момент. В случае с request_finished, он документирован как не посылающий никаких аргументов, что означает, что у нас может возникнуть соблазн написать нашу обработку сигнала как my_callback(sender).

Это было бы неправильно - на самом деле, Django выдаст ошибку, если вы так сделаете. Это потому, что в любой момент в сигнал могут быть добавлены аргументы, и ваш приемник должен быть в состоянии обработать эти новые аргументы.

Подключение функций приемника¶

Существует два способа подключения приемника к сигналу. Можно воспользоваться ручным способом подключения:

from django.core.signals import request_finished

request_finished.connect(my_callback)

В качестве альтернативы можно использовать декоратор receiver():

receiver(signal)[исходный код]¶

Параметры:	signal – Сигнал или список сигналов, к которым подключается функция.

Вот как вы связываетесь с декоратором:

from django.core.signals import request_finished
from django.dispatch import receiver

@receiver(request_finished)
def my_callback(sender, **kwargs):
    print("Request finished!")

Теперь наша функция my_callback будет вызываться каждый раз, когда запрос завершается.

Подключение к сигналам, посылаемым определенными отправителями¶

Некоторые сигналы посылаются много раз, но вас будет интересовать получение только определенного подмножества таких сигналов. Например, рассмотрим сигнал django.db.models.signals.pre_save, посылаемый перед сохранением модели. В большинстве случаев вам не нужно знать, когда любая модель будет сохранена - только когда будет сохранена одна конкретная модель.

В этих случаях вы можете зарегистрироваться для получения сигналов, отправленных только определенными отправителями. В случае django.db.models.signals.pre_save отправителем будет класс сохраняемой модели, поэтому вы можете указать, что хотите получать сигналы, посылаемые только некоторой моделью:

from django.db.models.signals import pre_save
from django.dispatch import receiver
from myapp.models import MyModel


@receiver(pre_save, sender=MyModel)
def my_handler(sender, **kwargs):
    ...

Функция my_handler будет вызвана только при сохранении экземпляра MyModel.

Различные сигналы используют различные объекты в качестве отправителей; вам нужно обратиться к built-in signal documentation для получения подробной информации о каждом конкретном сигнале.

Предотвращение дублирования сигналов¶

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

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

from django.core.signals import request_finished

request_finished.connect(my_callback, dispatch_uid="my_unique_identifier")

Определение сигналов¶

class Signal(providing_args=list)[исходный код]¶

Все сигналы являются экземплярами django.dispatch.Signal. providing_args - это список имен аргументов, которые сигнал будет предоставлять слушателям. Однако это чисто документальное описание, поскольку ничто не проверяет, что сигнал действительно предоставляет эти аргументы своим слушателям.

Например:

import django.dispatch

pizza_done = django.dispatch.Signal(providing_args=["toppings", "size"])

Это объявляет сигнал pizza_done, который будет предоставлять приемникам аргументы toppings и size.

Помните, что вы можете изменить этот список аргументов в любое время, поэтому не обязательно получить API с первой попытки.

Подача сигналов¶

В Django существует два способа отправки сигналов.

Signal.send(sender, **kwargs)[исходный код]¶

Signal.send_robust(sender, **kwargs)[исходный код]¶

Чтобы послать сигнал, вызовите либо Signal.send() (все встроенные сигналы используют это), либо Signal.send_robust(). Вы должны предоставить аргумент sender (который в большинстве случаев является классом) и можете предоставить любое количество других аргументов с ключевыми словами.

Например, вот как может выглядеть отправка нашего сигнала pizza_done:

class PizzaStore:
    ...

    def send_pizza(self, toppings, size):
        pizza_done.send(sender=self.__class__, toppings=toppings, size=size)
        ...

И send(), и send_robust() возвращают список кортежных пар [(receiver, response), ... ], представляющих список вызванных функций-приемников и их ответные значения.

send() отличается от send_robust() тем, как обрабатываются исключения, поднятые функциями-приемниками. send() не перехватывает исключения, вызванные приемниками; он просто позволяет ошибкам распространяться. Таким образом, не все приемники могут быть уведомлены о сигнале при возникновении ошибки.

send_robust() ловит все ошибки, производные от класса Python Exception, и обеспечивает уведомление всех приемников о сигнале. Если произошла ошибка, экземпляр ошибки возвращается в кортеже для приемника, который вызвал ошибку.

Трассировки присутствуют на атрибуте __traceback__ ошибок, возвращаемых при вызове send_robust().