接收器函数¶

首先，我们需要定义一个接收器函数。接收器可以是任何 Python 函数或方法

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

请注意，该函数采用sender参数以及通配符关键字参数（**kwargs）；所有信号处理程序都必须采用这些参数。

我们稍后将讨论发送者稍后，但现在请查看**kwargs参数。所有信号都会发送关键字参数，并且可以随时更改这些关键字参数。对于request_finished，它被记录为不发送任何参数，这意味着我们可能会尝试将信号处理编写为my_callback(sender)。

这是错误的——事实上，如果您这样做，Django 会抛出一个错误。这是因为随时都可能向信号中添加参数，并且您的接收器必须能够处理这些新参数。

接收器也可以是异步函数，具有相同的签名，但使用async def声明。

async def my_callback(sender, **kwargs):
    await asyncio.sleep(5)
    print("Request finished!")

信号可以同步或异步发送，接收器将自动适应正确的调用样式。有关更多信息，请参见发送信号。

连接接收器函数¶

您可以通过两种方式将接收器连接到信号。您可以采用手动连接方式

from django.core.signals import request_finished

request_finished.connect(my_callback)

或者，您可以使用receiver()装饰器

receiver(signal, **kwargs)[source]¶

参数：

• signal – 要将函数连接到的信号或信号列表。

• kwargs – 要传递给函数的通配符关键字参数。

以下是使用装饰器连接的方法

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函数。

from django.apps import AppConfig
from django.core.signals import request_finished


class MyAppConfig(AppConfig):
    ...

    def ready(self):
        # Implicitly connect signal handlers decorated with @receiver.
        from . import signals

        # Explicitly connect a signal handler.
        request_finished.connect(signals.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): ...

只有在保存MyModel的实例时，才会调用my_handler函数。

不同的信号使用不同的对象作为其发送者；您需要参考内置信号文档以了解每个特定信号的详细信息。

防止重复信号¶

在某些情况下，连接接收器和信号的代码可能会运行多次。这可能导致您的接收器函数被注册多次，从而在信号事件发生时被调用多次。例如，ready() 方法在测试期间可能会执行多次。更一般地说，只要您的项目导入定义信号的模块，就会发生这种情况，因为信号注册会根据导入次数运行多次。

如果此行为存在问题（例如，当使用信号在保存模型时发送电子邮件时），请将唯一的标识符作为 dispatch_uid 参数传递以标识您的接收器函数。此标识符通常是一个字符串，尽管任何可哈希的对象都足够。最终结果是您的接收器函数将仅针对每个唯一的 dispatch_uid 值绑定到信号一次。

from django.core.signals import request_finished

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

定义信号¶

class Signal[source]¶

所有信号都是 django.dispatch.Signal 实例。

例如

import django.dispatch

pizza_done = django.dispatch.Signal()

这声明了一个 pizza_done 信号。

发送信号¶

有两种方法可以在 Django 中同步发送信号。

Signal.send(sender, **kwargs)[source]¶

Signal.send_robust(sender, **kwargs)[source]¶

信号也可以异步发送。

Signal.asend(sender, **kwargs)¶

Signal.asend_robust(sender, **kwargs)¶

要发送信号，请调用 Signal.send()、Signal.send_robust()、await Signal.asend() 或 await Signal.asend_robust() 之一。您必须提供 sender 参数（大多数情况下是类），并且可以提供任意数量的其他关键字参数。

例如，以下是发送我们的 pizza_done 信号可能的样子。

class PizzaStore:
    ...

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

所有四种方法都返回元组对列表 [(receiver, response), ...]，表示已调用的接收器函数及其响应值的列表。

send() 与 send_robust() 在处理接收器函数引发的异常的方式上有所不同。send() 不会捕获接收器引发的任何异常；它只是允许错误传播。因此，并非所有接收器都可能在出现错误时收到信号通知。

send_robust() 捕获所有源自 Python Exception 类的错误，并确保所有接收器都收到信号通知。如果发生错误，则错误实例将返回在引发错误的接收器的元组对中。

调用 send_robust() 时返回的错误的 __traceback__ 属性中存在回溯信息。

asend() 类似于 send()，但它是一个必须等待的协程。

async def asend_pizza(self, toppings, size):
    await pizza_done.asend(sender=self.__class__, toppings=toppings, size=size)
    ...

无论是同步还是异步，接收器都将正确适应使用 send() 还是 asend()。当通过 asend() 调用时，同步接收器将使用 sync_to_async() 调用。当通过 sync() 调用时，异步接收器将使用 async_to_sync() 调用。类似于 中间件的情况，以这种方式调整接收器会产生少量性能成本。请注意，为了减少 send() 或 asend() 调用中的同步/异步调用风格切换次数，接收器将根据它们是否为异步进行分组，然后再进行调用。这意味着在同步接收器之前注册的异步接收器可能在同步接收器之后执行。此外，异步接收器将使用 asyncio.gather() 并发执行。

除异步请求-响应周期中的信号外，所有内置信号都使用 Signal.send() 分派。