Django includes a «signal dispatcher» which helps decoupled applications get\nnotified when actions occur elsewhere in the framework. In a nutshell, signals\nallow certain senders to notify a set of receivers that some action has\ntaken place. They’re especially useful when many pieces of code may be\ninterested in the same events.
\nFor example, a third-party app can register to be notified of settings\nchanges:
\nfrom django.apps import AppConfig\nfrom django.core.signals import setting_changed\n\n\ndef my_callback(sender, **kwargs):\n print("Setting changed!")\n\n\nclass MyAppConfig(AppConfig):\n ...\n\n def ready(self):\n setting_changed.connect(my_callback)\nDjango’s built-in signals let user code get notified of\ncertain actions.
\nYou can also define and send your own custom signals. See\nDefining and sending signals below.
\n\nTo receive a signal, register a receiver function using the\nSignal.connect() method. The receiver function is called when the signal\nis sent. All of the signal’s receiver functions are called one at a time, in\nthe order they were registered.
receiver – The callback function which will be connected to this\nsignal. See Receiver functions for more information.
sender – Specifies a particular sender to receive signals from. See\nConnecting to signals sent by specific senders for more information.
weak – Django stores signal handlers as weak references by\ndefault. Thus, if your receiver is a local function, it may be\ngarbage collected. To prevent this, pass weak=False when you call\nthe signal’s connect() method.
dispatch_uid – A unique identifier for a signal receiver in cases\nwhere duplicate signals may be sent. See\nPreventing duplicate signals for more information.
Let’s see how this works by registering a signal that\ngets called after each HTTP request is finished. We’ll be connecting to the\nrequest_finished signal.
First, we need to define a receiver function. A receiver can be any Python\nfunction or method:
\ndef my_callback(sender, **kwargs):\n print("Request finished!")\nNotice that the function takes a sender argument, along with wildcard\nkeyword arguments (**kwargs); all signal handlers must take these\narguments.
We’ll look at senders a bit later, but\nright now look at the **kwargs argument. All signals send keyword\narguments, and may change those keyword arguments at any time. In the case of\nrequest_finished, it’s documented as sending no\narguments, which means we might be tempted to write our signal handling as\nmy_callback(sender).
This would be wrong – in fact, Django will throw an error if you do so. That’s\nbecause at any point arguments could get added to the signal and your receiver\nmust be able to handle those new arguments.
\nReceivers may also be asynchronous functions, with the same signature but\ndeclared using async def:
async def my_callback(sender, **kwargs):\n await asyncio.sleep(5)\n print("Request finished!")\nSignals can be sent either synchronously or asynchronously, and receivers will\nautomatically be adapted to the correct call-style. See sending signals for more information.
\nThere are two ways you can connect a receiver to a signal. You can take the\nmanual connect route:
\nfrom django.core.signals import request_finished\n\nrequest_finished.connect(my_callback)\nAlternatively, you can use a receiver() decorator:
signal – A signal or a list of signals to connect a function to.
kwargs – Wildcard keyword arguments to pass to a\nfunction.
Here’s how you connect with the decorator:
\nfrom django.core.signals import request_finished\nfrom django.dispatch import receiver\n\n\n@receiver(request_finished)\ndef my_callback(sender, **kwargs):\n print("Request finished!")\nNow, our my_callback function will be called each time a request finishes.
Some signals get sent many times, but you’ll only be interested in receiving a\ncertain subset of those signals. For example, consider the\ndjango.db.models.signals.pre_save signal sent before a model gets\nsaved. Most of the time, you don’t need to know when any model gets saved –\njust when one specific model is saved.
In these cases, you can register to receive signals sent only by particular\nsenders. In the case of django.db.models.signals.pre_save, the sender\nwill be the model class being saved, so you can indicate that you only want\nsignals sent by some model:
from django.db.models.signals import pre_save\nfrom django.dispatch import receiver\nfrom myapp.models import MyModel\n\n\n@receiver(pre_save, sender=MyModel)\ndef my_handler(sender, **kwargs): ...\nThe my_handler function will only be called when an instance of MyModel\nis saved.
Different signals use different objects as their senders; you’ll need to\nconsult the built-in signal documentation for details of\neach particular signal.
\nWhen dispatch_uid is not provided, Django identifies each receiver using\nits Python object identity and registers it only once. For module-level\nfunctions, static methods, and class methods, the identity is stable, so\nconnecting the same receiver more than once has no effect:
def my_handler(sender, **kwargs): ...\n\n\nmy_signal.connect(my_handler) # Running this code again is a no-op.\nBound methods, which take a self argument, are different. Their identity\nis tied to the specific instance, so connecting the same method from a new\ninstance registers it as an additional receiver:
def connect_signals():\n backend = Backend()\n my_signal.connect(backend.my_handler) # A distinct receiver.\n\n\nconnect_signals() # Running this code again registers another receiver.\nWhen using a bound method as a receiver, multiple registrations can be\nprevented by supplying a unique dispatch_uid. This identifier will usually\nbe a string, although any hashable object will suffice. The receiver will only\nbe bound to the signal once for each unique dispatch_uid value:
from django.core.signals import request_finished\n\nrequest_finished.connect(my_callback, dispatch_uid="my_unique_identifier")\nYour applications can take advantage of the signal infrastructure and provide\nits own signals.
\n\nAll signals are django.dispatch.Signal instances.
Por ejemplo:
\nimport django.dispatch\n\npizza_done = django.dispatch.Signal()\nThis declares a pizza_done signal.
There are two ways to send signals synchronously in Django.
\nSignals may also be sent asynchronously.
\nTo send a signal, call either Signal.send(), Signal.send_robust(),\nawait Signal.asend(), or\nawait Signal.asend_robust(). You must provide the\nsender argument (which is a class most of the time) and may provide as many\nother keyword arguments as you like.
For example, here’s how sending our pizza_done signal might look:
class PizzaStore:\n ...\n\n def send_pizza(self, toppings, size):\n pizza_done.send(sender=self.__class__, toppings=toppings, size=size)\n ...\nAll four methods return a list of tuple pairs [(receiver, response), ...],\nrepresenting the list of called receiver functions and their response values.
send() differs from send_robust() in how exceptions raised by receiver\nfunctions are handled. send() does not catch any exceptions raised by\nreceivers; it simply allows errors to propagate. Thus not all receivers may\nbe notified of a signal in the face of an error.
send_robust() catches all errors derived from Python’s Exception class,\nand ensures all receivers are notified of the signal. If an error occurs, the\nerror instance is returned in the tuple pair for the receiver that raised the\nerror.
The tracebacks are present on the __traceback__ attribute of the errors\nreturned when calling send_robust().
asend() is similar to send(), but it is a coroutine that must be\nawaited:
async def asend_pizza(self, toppings, size):\n await pizza_done.asend(sender=self.__class__, toppings=toppings, size=size)\n ...\nWhether synchronous or asynchronous, receivers will be correctly adapted to\nwhether send() or asend() is used. Synchronous receivers will be\ncalled using sync_to_async() when invoked via asend(). Asynchronous\nreceivers will be called using async_to_sync() when invoked via\nsend(). Similar to the case for middleware,\nthere is a small performance cost to adapting receivers in this way. Note that\nin order to reduce the number of sync/async calling-style switches within a\nsend() or asend() call, the receivers are grouped by whether or not\nthey are async before being called. This means that an asynchronous receiver\nregistered before a synchronous receiver may be executed after the synchronous\nreceiver. In addition, async receivers are executed concurrently using\nasyncio.gather().
All built-in signals, except those in the async request-response cycle, are\ndispatched using Signal.send().
To disconnect a receiver from a signal, call Signal.disconnect(). The\narguments are as described in Signal.connect(). The method returns\nTrue if a receiver was disconnected and False if not. When sender\nis passed as a lazy reference to <app label>.<model>, this method always\nreturns None.
The receiver argument indicates the registered receiver to disconnect. It\nmay be None if dispatch_uid is used to identify the receiver.