SignauxLien vers cette rubrique#

Fonctions réceptricesLien vers cette rubrique#

Tout d’abord, nous devons définir une fonction réceptrice. Celle-ci peut être n’importe quelle fonction ou méthode Python :

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

Remarquez que la fonction accepte un paramètre sender, accompagné des paramètres nommés génériques (**kwargs) ; tous les gestionnaires de signal doivent accepter ces paramètres.

Nous aborderons le paramètre sender un peu plus loin, mais commençons par examiner le paramètre **kwargs. Tous les signaux envoient des paramètres nommés et peuvent changer ces paramètres nommés à tout instant. Dans le cas de request_finished, sa documentation indique qu’il n’envoie pas de paramètre, ce qui signifie que nous pourrions être tentés d’écrire notre fonction de signal comme my_callback(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.

Connexion des fonctions réceptricesLien vers cette rubrique#

Il y a deux façons de connecter une fonction réceptrice à un signal. Vous pouvez choisir l’option de la connexion manuelle :

from django.core.signals import request_finished

request_finished.connect(my_callback)

L’autre possibilité est d’utiliser le décorateur receiver():

receiver(signal, **kwargs)Lien vers cette définition#

Paramètres:

• 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 :

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


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

À partir de cet instant, la fonction my_callback sera appelée chaque fois qu’une requête se termine.

Connexion aux signaux envoyés par des expéditeurs spécifiquesLien vers cette rubrique#

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
from django.dispatch import receiver
from myapp.models import MyModel


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

La 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.

Prévention des signaux dupliquésLien vers cette rubrique#

Dans certaines circonstances, le code faisant la connexion entre les récepteurs et les signaux peut être exécuté à plusieurs reprises. En conséquence, la fonction de réception peut être inscrite plus d’une fois et être ensuite appelée plusieurs fois pour un même événement de signal. Par exemple, la méthode ready()  peut être exécutée plus d’une fois pendant l’exécution des tests. Plus généralement, ceci se produit à chaque fois que votre projet importe le module où les signaux sont définis, car l’enregistrement d’un signal se produit autant de fois qu’il est importé.

Si ce comportement est problématique (par exemple quand des signaux sont utilisés pour envoyer des courriels quand un modèle est enregistré), indiquez un identifiant unique dans le paramètre dispatch_uid pour identifier votre fonction réceptrice. 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. En conséquence, la fonction réceptrice ne sera inscrite au signal qu’une seule fois par valeur unique de dispatch_uid:

from django.core.signals import request_finished

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

Définition de signauxLien vers cette rubrique#

class SignalLien vers cette définition#

Tous les signaux sont des instances de django.dispatch.Signal.

Par exemple :

import django.dispatch

pizza_done = django.dispatch.Signal()

Ceci déclare un signal pizza_done.

Envoi de signauxLien vers cette rubrique#

Il y a deux façons d’envoyer des signaux dans Django.

Signal.send(sender, **kwargs)Lien vers cette définition#

Signal.send_robust(sender, **kwargs)Lien vers cette définition#

Pour envoyer un signal, appelez Signal.send() (tous les signaux intégrés l’utilisent) ou Signal.send_robust(). Vous devez indiquer le paramètre sender (qui est une classe la plupart du temps) et vous pouvez ajouter autant de paramètres nommés que vous le souhaitez.

Par exemple, voici comment envoyer notre signal pizza_done:

class PizzaStore:
    ...

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

Aussi bien send() que send_robust() 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().