Django contient un « distributeur de signaux » qui permet aux applications découplées de pouvoir plus facilement être averties quand des actions se produisent ailleurs dans un projet. En résumé, les signaux permettent à certains expéditeurs d’avertir un ensemble de destinataires qu’une action a eu lieu. Ils sont particulièrement utiles lorsque beaucoup de parties de code peuvent être intéressées aux mêmes événements.
\nPar exemple, une application tierce peut s’inscrire pour être avertie des modifications de réglages
\nfrom django.apps import AppConfig\nfrom django.core.signals import setting_changed\n\n\ndef my_receiver(sender, **kwargs):\n print("Setting changed!")\n\n\nclass MyAppConfig(AppConfig):\n ...\n\n def ready(self):\n setting_changed.connect(my_receiver)\nLes signaux propres à Django permettent à du code utilisateur d’être averti de certaines actions.
\nVous pouvez également définir et envoyer vos propres signaux personnalisés. Voir Définition et envoi de signaux ci-dessous.
\n\nPour recevoir un signal, inscrivez une fonction réceptrice en utilisant la méthode Signal.connect(). Cette fonction sera appelée au moment où le signal est envoyé. Toutes les fonctions réceptrices d’un signal sont appelées consécutivement dans l’ordre où elles ont été inscrites.
receiver – La fonction réceptrice qui sera connectée à ce signal. Voir Fonctions réceptrices pour plus d’informations.
sender – Indique un expéditeur particulier duquel recevoir les signaux. Voir Connexion aux signaux envoyés par des expéditeurs spécifiques pour plus d’informations.
weak – Django stores signal receivers 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 – Un identifiant unique pour un récepteur de signal afin d’éviter que certains signaux puissent être envoyés à double. Voir Prévention des signaux dupliqués pour plus d’informations.
Voyons comment ça fonctionne en inscrivant un signal qui sera appelé à la fin de chaque requête HTTP. Nous allons nous connecter au signal request_finished.
Tout d’abord, nous devons définir une fonction réceptrice. Celle-ci peut être n’importe quelle fonction ou méthode Python :
\ndef my_receiver(sender, **kwargs):\n print("Request finished!")\nNotice that the function takes a sender argument, along with wildcard\nkeyword arguments (**kwargs); all signal receivers 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_receiver(sender).
Ce serait une erreur. En fait, Django génère une exception dans ce cas, parce que l’on doit s’attendre à ce que de nouveaux paramètres soient ajoutés dans le temps et la fonction réceptrice doit être capable d’accepter ces nouveaux paramètres.
\nLes récepteurs peuvent aussi être des fonctions asynchrones, avec la même signature mais déclarées comme async def:
async def my_receiver(sender, **kwargs):\n await asyncio.sleep(5)\n print("Request finished!")\nLes signaux peuvent être envoyés de manière synchrone ou asynchrone, et les récepteurs s’adapteront automatiquement au style d’appel approprié. Voir envoi de signaux pour plus d’informations.
\nIl y a deux façons de connecter une fonction réceptrice à un signal. Vous pouvez choisir l’option de la connexion manuelle :
\nfrom django.core.signals import request_finished\n\nrequest_finished.connect(my_receiver)\nL’autre possibilité est d’utiliser le décorateur receiver():
signal – Un signal ou une liste de signaux auxquels connecter la fonction.
kwargs – Autres paramètres nommés arbitraires à passer à la fonction.
Voici comment faire la connexion avec le décorateur :
\nfrom django.core.signals import request_finished\nfrom django.dispatch import receiver\n\n\n@receiver(request_finished)\ndef my_receiver(sender, **kwargs):\n print("Request finished!")\nNow, our my_receiver function will be called each time a request finishes.
Certains signaux sont envoyés de nombreuses fois, mais vous n’êtes pas toujours intéressé à tous les recevoir. Par exemple, considérez le signal django.db.models.signals.pre_save envoyé avant chaque enregistrement de modèle. La plupart du temps, vous n’avez pas besoin de savoir quand chaque modèle est enregistré, mais seulement pour un modèle spécifique.
Dans ces situations, vous pouvez inscrire une fonction pour qu’elle ne reçoive les signaux que de certains expéditeurs. Dans le cas de django.db.models.signals.pre_save, l’expéditeur sera la classe du modèle en cours d’enregistrement, il est donc possible d’indiquer que vous ne voulez recevoir que les signaux envoyés par certains modèles :
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): ...\nLa fonction my_handler ne sera appelée que lors de l’enregistrement d’une instance de MyModel.
Différents signaux utilisent différents objets comme expéditeurs ; il s’agit de consulter la documentation des signaux intégrés pour plus de détails sur chaque signal.
\nLorsque dispatch_uid n’est pas fourni, Django identifie chaque récepteur en utilisant son identité d’objet Python et l’inscrit une seule fois. Pour les fonctions de niveau module, les méthodes statiques et les méthodes de classes, l’identité est stable, ce qui fait qu’une connexion du même récepteur à plusieurs reprises n’a aucun effet :
def my_handler(sender, **kwargs): ...\n\n\nmy_signal.connect(my_handler) # Running this code again is a no-op.\nLes méthodes liées qui acceptent un argument self sont un cas différent. Leur identité est liée à une instance spécifique, ce qui fait que la connexion d’une même méthode mais d’une nouvelle instance va l’inscrire comme nouveau récepteur :
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.\nLors de l’utilisation d’une méthode liée comme récepteur, plusieurs inscriptions peuvent être évitées en fournissant un dispatch_uid unique. Il s’agit généralement d’une chaîne de caractères, même si n’importe quel objet hachable peut faire l’affaire. Le récepteur ne sera inscrit au signal qu’une seule fois par valeur unique de dispatch_uid:
from django.core.signals import request_finished\n\nrequest_finished.connect(my_receiver, dispatch_uid="my_unique_identifier")\nLes applications peuvent profiter de l’infrastructure des signaux et fournir leurs propres signaux.
\n\nTous les signaux sont des instances de django.dispatch.Signal.
Par exemple :
\nimport django.dispatch\n\npizza_done = django.dispatch.Signal()\nCeci déclare un signal pizza_done.
Il y a deux façons d’envoyer des signaux dans Django de manière snychrone.
\nLes signaux peuvent aussi être envoyés de manière asynchrone.
\nPour envoyer un signal, appelez Signal.send(), Signal.send_robust(), await Signal.asend(), or await Signal.asend_robust(). Vous devez indiquer l’argument sender (qui est une classe la plupart du temps) et vous pouvez ajouter autant d’arguments nommés que vous le souhaitez.
Par exemple, voici comment envoyer notre signal pizza_done:
class PizzaStore:\n ...\n\n def send_pizza(self, toppings, size):\n pizza_done.send(sender=self.__class__, toppings=toppings, size=size)\n ...\nLes quatre méthodes renvoient uns liste de paires de tuples [(récepteur, réponse), ... ] correspondant à la liste des fonctions réceptrices appelées et la valeur de leur réponse.
send() diffère de send_robust() par la manière dont les exceptions générées par les fonctions réceptrices sont traitées. send() n’intercepte aucune exception générée par les récepteurs ; elle laisse simplement les erreurs se propager. Il est donc possible que certains récepteurs ne soient pas notifiés par le signal en cas d’erreur.
send_robust() intercepte toutes les erreurs héritant de la classe Exception de Python et s’assure que tous les récepteurs soient notifiés par le signal. Si une erreur survient, l’instance d’erreur est renvoyée dans le tuple correspondant au récepteur qui a généré l’erreur.
Les traces de débogage sont présentes dans l’attribut __traceback__ des erreurs renvoyées lors des appels à send_robust().
asend() est semblable à send(), mais il s’agit d’une coroutine qu’il faut appeler par await:
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.TaskGroup.
Tous les signaux intégrés à Django, sauf ceux faisant partie du cycle requête-réponse asynchrone, sont envoyés par Signal.send().
Pour déconnecter un récepteur d’un signal, appelez Signal.disconnect(). Les paramètres sont identiques à ceux décrits pour Signal.connect(). La méthode renvoie True si un récepteur a été déconnecté, sinon False. Lorsque sender est transmis comme référence différée à <app label>.<model>, cette méthode renvoie toujours None.
Le paramètre receiver indique le récepteur inscrit qu’il s’agit de déconnecter. Il peut valoir None si dispatch_uid est utilisé pour identifier le récepteur.