# Documentation Django 5.2.8

# Signaux

Une liste de tous les signaux envoyés par Django. Tous les signaux intégrés sont envoyés par la méthode `send()`.

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.

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

Les signaux peuvent rendre votre code plus difficile à maintenir. Avant de recourir aux signaux de modèles, considérez l’implémentation d’une méthode utilitaire d’un gestionnaire personnalisé, afin de mettre à jour vos modèles et d’appliquer toute logique supplémentaire, ou alors de surcharger les méthodes de 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.

Note also that Django stores signal handlers as weak references by default, so if your handler is a local function, it may be garbage collected. To prevent this, pass `weak=False` when you call the signal’s `connect()`.

Note

Le modèle `sender` des signaux de modèles peut être référencé de manière différée lors de la connexion à un récepteur en indiquant son étiquette d’application complète. Par exemple, un modèle `Question` défini dans l’application `polls` peut être référencé en tant que `'polls.Question'`. Ce type de référence peut être bien pratique lorsqu’on est confronté à des dépendances d’importation circulaire ou à des modèles interchangeables.

### `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 :

    q = Question(question_text="What's new?", pub_date=timezone.now())

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

Paramètre | Valeur
--- | ---
`sender` | `Question` (la classe elle-même)
`args` | `[]` (une liste vide, car aucun paramètre positionnel n’a été transmis à `__init__()`)
`kwargs` | `{'question_text': "What's new?",` `'pub_date': datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=datetime.UTC)}`

### `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.

  Note

  `instance._state` n’est pas défini avant l’envoi du signal `post_init`, ce qui fait que les attributs `_state` ont toujours leurs valeurs par défaut. Par exemple, `_state.db` vaut `None`.

Avertissement

Pour des raisons de performance, vous ne devriez pas exécuter de requête dans les récepteurs des signaux `pre_init` ou `post_init` parce qu’elles seraient exécutées pour chaque instance renvoyée durant une itération d’un jeu de requête.

### `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é.

`update_fields`

  Le groupe de champs à mettre à jour tel que transmis à la méthode `Model.save()`, ou `None` si `update_fields` n’a pas été transmis à `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é.

`update_fields`

  Le groupe de champs à mettre à jour tel que transmis à la méthode `Model.save()`, ou `None` si `update_fields` n’a pas été transmis à `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é.

`origin`

  L’instance `Model` ou `QuerySet` de l’origine de la suppression, c’est-à-dire l’instance sur laquelle la méthode `delete()` a été appelée.

### `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é.

`origin`

  L’instance `Model` ou `QuerySet` de l’origine de la suppression, c’est-à-dire l’instance sur laquelle la méthode `delete()` a été appelée.

### `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 actions `pre_add` et `post_add`, il s’agit d’un ensemble de clés primaires qui seront ou ont été ajoutées à la relation. Il peut s’agir d’un sous-ensemble des valeurs soumises pour l’ajout, car les insertions doivent filtrer les valeurs existantes afin d’éviter les erreurs de base de données `IntegrityError`.

  Pour les actions `pre_remove` et `post_remove`, il s’agit d’un ensemble de clés primaires qui ont été soumises pour la suppression de la relation. Ces valeurs ne dépendent pas du succès ou non de leur réelle suppression. En particulier, des valeurs inexistantes peuvent être soumises et apparaître donc dans `pk_set`, même si elles n’auront aucun effet sur la base de données.

  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` | `{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` | `{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.

Comme ce signal est envoyé durant le processus de remplissage du registre des applications et que `AppConfig.ready()` s’exécute après la fin de ce remplissage, les récepteurs ne peuvent pas être connectés dans cette méthode. Une possibilité est de les connecter dans `AppConfig.__init__()` en prenant soi de ne pas importer de modèles ni de déclencher des appels au registre des applications.

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_migrate`

django.db.models.signals.pre_migrate

Envoyé par la commande `migrate` afin le début de l’installation d’une application. Il n’est pas émis pour les applications qui n’ont pas de module `models`.

Paramètres envoyés avec ce signal :

`sender`

  Une instance `AppConfig` de l’application sur le point d’être migrée/synchronisée.

`app_config`

  Identique à `sender`.

`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_migrate` 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`.

`stdout`

  Un objet de type flux vers lequel sera redirigée la sortie verbeuse.

`using`

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

`plan`

  Le plan de migration qui sera utilisé pour l’exécution des migrations. Même si le plan ne fait pas partie de l’API publique, sa présence sert aux rares cas où il est nécessaire de connaître le plan. Un plan est une liste de tuples binaires avec le premier élément comme instance d’une classe de migration et le second élément indiquant si la migration a été défaite (`True`) ou appliquée (`False`).

`apps`

  Une instance de `Apps` contenant l’état du projet avant l’exécution des migrations. Elle devrait être utilisée en lieu et place du registre global `apps` pour récupérer les modèles sur lesquels portent les opérations.

### `post_migrate`

django.db.models.signals.post_migrate

Envoyé à la fin des commandes `migrate` (même si aucune migration n’est effectuée) et `flush`. Il n’est pas émis pour les applications qui ne possèdent pas de module `models`.

Les gestionnaires de ce signal ne doivent pas effectuer de modification de base de données car cela pourrait provoquer l’échec de la commande d’administration `flush` si elle s’exécute pendant la commande `migrate`.

Paramètres envoyés avec ce signal :

`sender`

  Une instance `AppConfig` de l’application qui vient d’être installée.

`app_config`

  Identique à `sender`.

`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_migrate` 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`.

`stdout`

  Un objet de type flux vers lequel sera redirigée la sortie verbeuse.

`using`

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

`plan`

  Le plan de migration utilisé pour l’exécution des migrations. Même si le plan ne fait pas partie de l’API publique, sa présence sert aux rares cas où il est nécessaire de connaître le plan. Un plan est une liste de tuples binaires avec le premier élément comme instance d’une classe de migration et le second élément indiquant si la migration a été défaite (`True`) ou appliquée (`False`).

`apps`

  Une instance de `Apps` contenant l’état du projet après l’exécution des migrations. Elle devrait être utilisée en lieu et place du registre global `apps` pour récupérer les modèles sur lesquels portent les opérations.

Par exemple, il est possible d’inscrire une fonction de rappel dans une classe `AppConfig` comme ceci :

    from django.apps import AppConfig
    from django.db.models.signals import post_migrate

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

    class MyAppConfig(AppConfig):
        ...

        def ready(self):
            post_migrate.connect(my_callback, sender=self)

Note

Si vous fournissez une instance `AppConfig` comme paramètre `sender`, contrôlez bien que le signal est inscrit dans la méthode `ready()`. Des instances `AppConfig` sont recréées pour les tests qui fonctionnent avec un réglage `INSTALLED_APPS` modifié (comme quand les réglages sont temporairement surchargés) et de tels signaux doivent alors être connectés pour chaque nouvelle instance de `AppConfig`.

## Signaux de requête et de réponse

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

Avertissement

Les signaux peuvent rendre le code plus difficile à maintenir. Considérez l’utilisation d’un intergiciel avant d’utiliser des signaux de requête/réponse.

### `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.

`environ`

  Le dictionnaire `environ` fourni à la requête.

### `request_finished`

django.core.signals.request_finished

Envoyé lorsque Django a terminé l’envoi d’une réponse HTTP à un client.

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`

  Inutilisé (toujours `None`).

`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.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 »). Utilisez le paramètre `enter` pour distinguer entre les deux cas.

Vous pouvez aussi importer ce signal à partir de `django.core.signals` pour éviter de l’importer à partir de `django.test` dans un contexte ne concernant pas les tests.

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

`enter`

  Une valeur booléenne ; `True` si le réglage doit être appliqué, `False` s’il doit être restauré.

### `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

Sent when the database wrapper makes the initial connection to the database. This is particularly useful if you’d like to send any post connection commands to the SQL backend.

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

## Tasks signals

New in Django 6.0.

Signals sent by the tasks framework.

### `task_enqueued`

django.tasks.signals.task_enqueued

Sent once a Task has been enqueued.

Paramètres envoyés avec ce signal :

`sender`

  The backend class which the Task was enqueued on to.

`task_result`

  The enqueued `TaskResult`.

### `task_started`

django.tasks.signals.task_started

Sent when a Task has started executing.

Paramètres envoyés avec ce signal :

`sender`

  The backend class which the Task was enqueued on to.

`task_result`

  The started `TaskResult`.

### `task_finished`

django.tasks.signals.task_finished

Sent once a Task has finished executing, successfully or otherwise.

Paramètres envoyés avec ce signal :

`sender`

  The backend class which the Task was enqueued on to.

`task_result`

  The finished `TaskResult`.