Signaux

Une liste de tous les signaux envoyés par Django

Voir aussi

Consultez la documentation sur la distribution de signaux pour plus d’informations sur la façon d’inscrire et de recevoir des signaux.

L’application commentaires envoie un ensemble de signaux liés aux commentaires.

Le système d’authentification envoie des signaux lorsqu’un utilisateur se connecte ou se déconnecte.

Signaux de modèle

Le module django.db.models.signals définit un ensemble de signaux envoyés par le système des modèles.

Avertissement

Beaucoup de ces signaux sont envoyés par différentes méthodes de modèle comme __init__() ou save(). Ces méthodes peuvent être surchargées dans votre propre code.

Si vous surchargez ces méthodes dans un de vos modèles, vous devez appeler la méthode de la classe parente si vous voulez que les signaux soient envoyés.

Notez également que Django stocke les gestionnaires de signaux comme référence faible par défaut. Cela signifie que si le récepteur est une fonction locale, il peut être purgé de la mémoire. Pour empêcher cela, indiquez weak=False lors de l’appel à la méthode connect() du signal.

pre_init

django.db.models.signals.pre_init

Lors de chaque instanciation d’un modèle Django, ce signal est envoyé au début de la méthode __init__() du modèle.

Paramètres envoyés avec ce signal :

sender

La classe de modèle dont une instance vient d’être créée.

args

Une liste de paramètres positionnels transmis à __init__():

kwargs

Un dictionnaire de paramètres nommés transmis à __init__():

Par exemple, le tutoriel contient cette ligne :

p = Poll(question="What's up?", pub_date=datetime.now())

Les paramètres envoyés au gestionnaire pre_init sont :

Paramètre

Valeur

sender

Poll (la classe elle-même)

args

[] (une liste vide, car aucun paramètre positionnel n’a été transmis à __init__())

kwargs {'question': "What's up?", 'pub_date': datetime.now()}

post_init

django.db.models.signals.post_init

Comme pre_init, mais celui-ci est envoyé lorsque la méthode __init__() se termine.

Paramètres envoyés avec ce signal :

sender

Comme ci-dessus : la classe de modèle dont une instance vient d’être créée.

instance

L’instance de modèle réelle qui vient d’être créée.

pre_save

django.db.models.signals.pre_save

Envoyé au début de la méthode save() d’un modèle.

Paramètres envoyés avec ce signal :

sender

La classe de modèle.

instance

L’instance réelle en cours d’enregistrement.

raw

Valeur booléenne ; True si le modèle est enregistré exactement comme présenté (par ex. lors du chargement d’un instantané). Il ne faut pas interroger ou modifier d’autres enregistrements de la base de données, car celle-ci pourrait se trouver provisoirement dans un état non cohérent.

using

L’alias de base de données utilisé.

New in Django 1.5.
update_fields

Le groupe de champs à mettre à jour explicitement défini dans la méthode save(). None si ce paramètre n’a pas été utilisé dans l’appel à save().

post_save

django.db.models.signals.post_save

Comme pre_save, mais envoyé à la fin de la méthode save().

Paramètres envoyés avec ce signal :

sender

La classe de modèle.

instance

L’instance réelle en cours d’enregistrement.

created

Valeur booléenne ; True si un nouvel enregistrement a été créé.

raw

Valeur booléenne ; True si le modèle est enregistré exactement comme présenté (par ex. lors du chargement d’un instantané). Il ne faut pas interroger ou modifier d’autres enregistrements de la base de données, car celle-ci pourrait se trouver provisoirement dans un état non cohérent.

using

L’alias de base de données utilisé.

New in Django 1.5.
update_fields

Le groupe de champs à mettre à jour explicitement défini dans la méthode save(). None si ce paramètre n’a pas été utilisé dans l’appel à save().

pre_delete

django.db.models.signals.pre_delete

Envoyé au début de la méthode delete() d’un modèle ou de la méthode delete() d’un QuerySet.

Paramètres envoyés avec ce signal :

sender

La classe de modèle.

instance

L’instance réelle en cours de suppression.

using

L’alias de base de données utilisé.

post_delete

django.db.models.signals.post_delete

Comme pre_delete, mais envoyé à la fin de la méthode delete() d’un modèle ou de la méthode delete() d’un QuerySet.

Paramètres envoyés avec ce signal :

sender

La classe de modèle.

instance

L’instance réelle en cours de suppression.

Notez que l’objet ne se trouve plus dans la base de données, soyez donc très prudent avec ce que vous faites de cette instance.

using

L’alias de base de données utilisé.

m2m_changed

django.db.models.signals.m2m_changed

Envoyé lorsqu’un champ ManyToManyField est modifié dans une instance de modèle. Strictement parlant, il ne s’agit pas d’un signal de modèle car il est envoyé par ManyToManyField, mais comme il complète les signaux pre_save/post_save et pre_delete/post_delete en ce qui concerne le suivi des modifications des modèles, nous l’avons inclus sous cette rubrique.

Paramètres envoyés avec ce signal :

sender

La classe de modèles intermédiaire déterminant le champ ManyToManyField. Cette classe est automatiquement créée lors de la définition d’un champ plusieurs-à-plusieurs ; vous pouvez y accéder par l’attribut through du champ plusieurs-à-plusieurs.

instance

L’instance dont la relation plusieurs-à-plusieurs est mise à jour. Cela peut être une instance de sender ou de la classe à laquelle est liée le champ ManyToManyField.

action

Une chaîne indiquant le type de mise à jour effectuée sur la relation. Voici les valeurs possibles :

"pre_add"

Envoyé avant qu’un ou plusieurs objets soient ajoutés à la relation.

"post_add"

Envoyé après qu’un ou plusieurs objets ont été ajoutés à la relation.

"pre_remove"

Envoyé avant qu’un ou plusieurs objets soient supprimés de la relation.

"post_remove"

Envoyé après qu’un ou plusieurs objets ont été supprimés de la relation.

"pre_clear"

Envoyé avant que la relation soit effacée.

"post_clear"

Envoyé après que la relation a été effacée.

reverse

Indique quel côté de la relation est mis à jour (c’est-à-dire si c’est la relation directe ou inverse qui est en cours de modification).

model

La classe des objets qui sont ajoutés, supprimés ou retirés de la relation.

pk_set

Pour les signaux pre_add, post_add, pre_remove et post_remove, il s’agit d’un ensemble de valeurs de clé primaire qui ont été ajoutées ou enlevées de la relation.

Pour les signaux pre_clear et post_clear actions, cette valeur vaut None.

using

L’alias de base de données utilisé.

Par exemple, si une Pizza peut comporter plusieurs objets Topping, selon ce modèle :

class Topping(models.Model):
    # ...
    pass

class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

Si nous connectons un gestionnaire comme ceci :

from django.db.models.signals import m2m_changed

def toppings_changed(sender, **kwargs):
    # Do something
    pass

m2m_changed.connect(toppings_changed, sender=Pizza.toppings.through)

puis que nous faisons quelque chose comme ça :

>>> p = Pizza.objects.create(...)
>>> t = Topping.objects.create(...)
>>> p.toppings.add(t)

les paramètres envoyés à un gestionnaire m2m_changed (toppings_changed dans l’exemple ci-dessus) seraient :

Paramètre

Valeur

sender

Pizza.toppings.through (la classe plusieurs-à-plusieurs intermédiaire)

instance

p (l’instance Pizza en cours de modification)

action

"pre_add" (suivi d’un autre signal avec "post_add")

reverse

False (Pizza contient le champ ManyToManyField, ce qui fait que cette fonction modifie la relation directe)

model

Topping (la classe des objets ajoutés à Pizza)

pk_set

set([t.id]) (car seul Topping t a été ajouté à la relation)

using

"default" (parce que le routeur par défaut dirige les écritures à cette destination)

Et si nous faisions ensuite quelque chose comme ceci :

>>> t.pizza_set.remove(p)

les paramètres envoyés à un gestionnaire m2m_changed seraient :

Paramètre

Valeur

sender

Pizza.toppings.through (la classe plusieurs-à-plusieurs intermédiaire)

instance

t (l’instance Topping en cours de modification)

action

"pre_remove" (suivi d’un autre signal avec "post_remove")

reverse

True (c’est Pizza qui contient le champ ManyToManyField, ce qui fait que cette fonction modifie la relation inverse)

model

Pizza (la classe des objets retirés de Topping)

pk_set

set([p.id]) (car seul Pizza p a été enlevé de la relation)

using

"default" (parce que le routeur par défaut dirige les écritures à cette destination)

class_prepared

django.db.models.signals.class_prepared

Envoyé chaque fois qu’une classe de modèle a été « préparée », c’est-à-dire après que le modèle a été défini et inscrit dans le système des modèles de Django. Django utilise ce signal en interne ; il n’est généralement pas utilisé dans des applications tierces.

Paramètres envoyés avec ce signal :

sender

La classe de modèle qui vient d’être préparée.

Signaux de gestion

Signaux envoyés par django-admin.

pre_syncdb

django.db.models.signals.pre_syncdb

Envoyé par la commande syncdb avant de commencer à installer une application.

Les gestionnaires à l’écoute de ce signal doivent se trouver à un endroit particulier : un module management dans l’une des applications de INSTALLED_APPS. Si les gestionnaires sont inscrits depuis un autre endroit, il se peut que syncdb ne puisse pas les charger.

Paramètres envoyés avec ce signal :

sender

Le module models qui vient d’être installé. C’est-à-dire, si syncdb vient d’installer une application nommée "foo.bar.myapp", sender correspondra au module foo.bar.myapp.models.

app

Identique à sender.

create_models

Une liste des classes de modèle d’applications que syncdb prévoit de créer.

verbosity

Indique la quantité d’informations que manage.py affiche à l’écran. Voir l’option --verbosity pour plus de détails.

Les fonctions à l’écoute de pre_syncdb devraient ajuster ce qu’elles affichent en fonction de la valeur de ce paramètre.

interactive

Si interactive vaut True, il est tout à fait possible de demander à l’utilisateur de saisir des informations sur la ligne de commande. Si interactive vaut False, les fonctions à l’écoute de ce signal ne doivent pas du tout interroger l’utilisateur.

Par exemple, l’application django.contrib.auth ne demande les informations de création du super-utilisateur que lorsqu’interactive vaut True.

db

L’alias de base de données sur laquelle une commande va agir.

post_syncdb

django.db.models.signals.post_syncdb

Envoyé par la commande syncdb après que celle-ci a installé une application, et après la commande flush.

Les gestionnaires à l’écoute de ce signal doivent se trouver à un endroit particulier : un module management dans l’une des applications de INSTALLED_APPS. Si les gestionnaires sont inscrits depuis un autre endroit, il se peut que syncdb ne puisse pas les charger. Il est important que les gestionnaires de ce signal effectuent des modifications idempotentes (c’est-à-dire pas de modification de base de données) car cela pourrait provoquer l’échec de la commande de gestion flush si elle s’exécute aussi pendant la commande syncdb.

Paramètres envoyés avec ce signal :

sender

Le module models qui vient d’être installé. C’est-à-dire, si syncdb vient d’installer une application nommée "foo.bar.myapp", sender correspondra au module foo.bar.myapp.models.

app

Identique à sender.

created_models

Une liste des classes de modèle d’applications que syncdb a créées jusqu’à ce point.

verbosity

Indique la quantité d’informations que manage.py affiche à l’écran. Voir l’option --verbosity pour plus de détails.

Les fonctions à l’écoute de post_syncdb devraient ajuster ce qu’elles affichent en fonction de la valeur de ce paramètre.

interactive

Si interactive vaut True, il est tout à fait possible de demander à l’utilisateur de saisir des informations sur la ligne de commande. Si interactive vaut False, les fonctions à l’écoute de ce signal ne doivent pas du tout interroger l’utilisateur.

Par exemple, l’application django.contrib.auth ne demande les informations de création du super-utilisateur que lorsqu’interactive vaut True.

db

L’alias de base de données utilisé pour la synchronisation. La valeur par défaut correspond à la base de données default.

Par exemple, yourapp/management/__init__.py pourrait être écrit comme ceci :

from django.db.models.signals import post_syncdb
import yourapp.models

def my_callback(sender, **kwargs):
    # Your specific logic here
    pass

post_syncdb.connect(my_callback, sender=yourapp.models)

Signaux de requête et de réponse

Signaux envoyés par le système de base lors du traitement d’une requête.

request_started

django.core.signals.request_started

Envoyé lorsque Django commence à traiter une requête HTTP.

Paramètres envoyés avec ce signal :

sender

La classe de gestion – par ex. django.core.handlers.wsgi.WsgiHandler – qui est chargée de la requête.

request_finished

django.core.signals.request_finished

Envoyé lorsque Django termine de traiter une requête HTTP.

Changed in Django 1.5:

Avant Django 1.5, ce signal était envoyé avant de renvoyer le contenu au client. Afin de prendre en compte les réponses en flux, il est maintenant envoyé après que la réponse a été complètement renvoyée au client.

Note

Certains serveurs et intergiciels WSGI n’appellent pas toujours close sur la réponse après avoir traité une requête, notamment uWSGI avant la version 1.2.6 et l’intergiciel de signalement d’erreurs de Sentry jusqu’à la version 2.0.7. Dans ces cas, ce signal n’est pas envoyé du tout. Par conséquent, il se peut que des connexions de base de données et de serveurs memcache puissent être laissées ouvertes.

Paramètres envoyés avec ce signal :

sender

La classe de gestion, comme ci-dessus.

got_request_exception

django.core.signals.got_request_exception

Ce signal est envoyé chaque fois que Django rencontre une exception lors du traitement d’une requête HTTP entrante.

Paramètres envoyés avec ce signal :

sender

La classe de gestion, comme ci-dessus.

request

L’objet HttpRequest.

Signaux de test

Ces signaux ne sont envoyés que lors du fonctionnement des tests.

setting_changed

django.test.signals.setting_changed

Ce signal est envoyé lorsque la valeur d’un réglage a été modifiée par le gestionnaire de contexte django.test.TestCase.settings() ou le décorateur/gestionnaire de contexte django.test.utils.override_settings().

En fait, il est envoyé deux fois : lorsque la nouvelle valeur est appliquée (« setup ») et lorsque la valeur originale est restaurée (« teardown »).

Paramètres envoyés avec ce signal :

sender

Le gestionnaire des réglages.

setting

Le nom du réglage.

valeur

La valeur du réglage après la modification. Pour les réglages qui n’existent initialement pas, durant la phase de « teardown », value vaut None.

template_rendered

django.test.signals.template_rendered

Envoyé lorsque le système de test produit un gabarit. Ce signal n’est pas émis pendant les opérations normales d’un serveur Django, il n’est disponible que durant les tests.

Paramètres envoyés avec ce signal :

sender

L’objet Template qui a été produit.

template

Identique à sender

context

L’objet Context avec lequel le gabarit a été produit.

Adaptateurs de base de données

Signaux envoyés par l’adaptateur de base de données lorsqu’une connexion à la base de données est initiée.

connection_created

django.db.backends.signals.connection_created

Envoyé lorsque l’adaptateur de base de données crée la connexion initiale à la base de données. C’est particulièrement utile si vous avez besoin d’envoyer des commandes post connexion au moteur SQL.

Paramètres envoyés avec ce signal :

sender

La classe d’adaptation de la base de données – c’est-à-dire django.db.backends.postgresql_psycopg2.DatabaseWrapper ou django.db.backends.mysql.DatabaseWrapper, etc.

connection

La connexion de base de données qui a été ouverte. Cela peut être utilisé dans une configuration à plusieurs bases de données pour différencier les signaux de connexion de différentes bases de données.