信号

Django includes a "signal dispatcher" which helps allow decoupled applicationsget notified when actions occur elsewhere in the framework. In a nutshell,signals allow certain senders to notify a set of receivers that some actionhas taken place. They're especially useful when many pieces of code may beinterested in the same events.

Django provides a set of built-in signals that let usercode get notified by Django itself of certain actions. These include some usefulnotifications:

• django.db.models.signals.pre_save &django.db.models.signals.post_save

Sent before or after a model's save() methodis called.

• django.db.models.signals.pre_delete &django.db.models.signals.post_delete

Sent before or after a model's delete()method or queryset's delete()method is called.

• django.db.models.signals.m2m_changed

Sent when a ManyToManyField on a model is changed.

• django.core.signals.request_started &django.core.signals.request_finished

Sent when Django starts or finishes an HTTP request.

See the built-in signal documentation for a complete list,and a complete explanation of each signal.

You can also define and send your own custom signals; see below.

Listening to signals

To receive a signal, register a receiver function using theSignal.connect() method. The receiver function is called when the signalis sent.

• Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None)[源代码]
• 参数:
  • receiver — The callback function which will be connected to thissignal. See Receiver functions for more information.
  • sender — Specifies a particular sender to receive signals from. SeeConnecting to signals sent by specific senders for more information.
  • weak — Django stores signal handlers as weak references bydefault. Thus, if your receiver is a local function, it may begarbage collected. To prevent this, pass weak=False when you callthe signal's connect() method.
  • dispatch_uid — A unique identifier for a signal receiver in caseswhere duplicate signals may be sent. SeePreventing duplicate signals for more information.

Let's see how this works by registering a signal thatgets called after each HTTP request is finished. We'll be connecting to therequest_finished signal.

Receiver functions

First, we need to define a receiver function. A receiver can be any Pythonfunction or method:

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

Notice that the function takes a sender argument, along with wildcardkeyword arguments (**kwargs); all signal handlers must take these arguments.

We'll look at senders a bit later, but right now look at the **kwargsargument. All signals send keyword arguments, and may change those keywordarguments at any time. In the case ofrequest_finished, it's documented as sending noarguments, which means we might be tempted to write our signal handling asmy_callback(sender).

This would be wrong — in fact, Django will throw an error if you do so. That'sbecause at any point arguments could get added to the signal and your receivermust be able to handle those new arguments.

Connecting receiver functions

There are two ways you can connect a receiver to a signal. You can take themanual connect route:

from django.core.signals import request_finished
 
request_finished.connect(my_callback)

Alternatively, you can use a receiver() decorator:

• receiver(signal)[源代码]
• 参数:signal — A signal or a list of signals to connect a function to.

Here's how you connect with the decorator:

from django.core.signals import request_finished
from django.dispatch import receiver
 
@receiver(request_finished)
def my_callback(sender, **kwargs):
    print("Request finished!")

Now, our my_callback function will be called each time a request finishes.

我的代码该放在哪？

Strictly speaking, signal handling and registration code can live anywhereyou like, although it's recommended to avoid the application's root moduleand its models module to minimize side-effects of importing code.

In practice, signal handlers are usually defined in a signalssubmodule of the application they relate to. Signal receivers areconnected in the ready() method of yourapplication configuration class. If you're using the receiver()decorator, simply import the signals submodule insideready().

注解

The ready() method may be executed more thanonce during testing, so you may want to guard your signals fromduplication, especially if you're planningto send them within tests.

Connecting to signals sent by specific senders

Some signals get sent many times, but you'll only be interested in receiving acertain subset of those signals. For example, consider thedjango.db.models.signals.pre_save signal sent before a model gets saved.Most of the time, you don't need to know when any model gets saved — justwhen one specific model is saved.

In these cases, you can register to receive signals sent only by particularsenders. In the case of django.db.models.signals.pre_save, the senderwill be the model class being saved, so you can indicate that you only wantsignals sent by some model:

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):
    ...

The my_handler function will only be called when an instance of MyModelis saved.

Different signals use different objects as their senders; you'll need to consultthe built-in signal documentation for details of eachparticular signal.

Preventing duplicate signals

In some circumstances, the code connecting receivers to signals may runmultiple times. This can cause your receiver function to be registered morethan once, and thus called multiple times for a single signal event.

If this behavior is problematic (such as when using signals tosend an email whenever a model is saved), pass a unique identifier asthe dispatch_uid argument to identify your receiver function. Thisidentifier will usually be a string, although any hashable object willsuffice. The end result is that your receiver function will only bebound to the signal once for each unique dispatch_uid value:

from django.core.signals import request_finished
 
request_finished.connect(my_callback, dispatch_uid="my_unique_identifier")

Defining and sending signals

Your applications can take advantage of the signal infrastructure and provideits own signals.

Defining signals

• class Signal(providing_args=list)[源代码]
• All signals are django.dispatch.Signal instances. Theproviding_args is a list of the names of arguments the signal will provideto listeners. This is purely documentational, however, as there is nothing thatchecks that the signal actually provides these arguments to its listeners.

例如:

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

This declares a pizza_done signal that will provide receivers withtoppings and size arguments.

Remember that you're allowed to change this list of arguments at any time, sogetting the API right on the first try isn't necessary.

Sending signals

There are two ways to send signals in Django.

• Signal.send(sender, **kwargs)[源代码]
• Signal.sendrobust(_sender, **kwargs)[源代码]
• To send a signal, call either Signal.send() (all built-in signals usethis) or Signal.send_robust(). You must provide the sender argument(which is a class most of the time) and may provide as many other keywordarguments as you like.

For example, here's how sending our pizza_done signal might look:

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

Both send() and send_robust() return a list of tuple pairs[(receiver, response), … ], representing the list of called receiverfunctions and their response values.

send() differs from sendrobust() in how exceptions raised by receiverfunctions are handled. send() does _not catch any exceptions raised byreceivers; it simply allows errors to propagate. Thus not all receivers maybe notified of a signal in the face of an error.

send_robust() catches all errors derived from Python's Exception class,and ensures all receivers are notified of the signal. If an error occurs, theerror instance is returned in the tuple pair for the receiver that raised the error.

The tracebacks are present on the traceback attribute of the errorsreturned when calling send_robust().

Disconnecting signals

• Signal.disconnect(receiver=None, sender=None, dispatch_uid=None)[源代码]
• To disconnect a receiver from a signal, call Signal.disconnect(). Thearguments are as described in Signal.connect(). The method returnsTrue if a receiver was disconnected and False if not.

The receiver argument indicates the registered receiver to disconnect. Itmay be None if dispatch_uid is used to identify the receiver.