From 71e9694856627d4027c9df066045f0e1c2b5cf27 Mon Sep 17 00:00:00 2001 From: Joseph Victor Zammit Date: Sat, 22 Oct 2022 18:52:53 +0200 Subject: [PATCH] Fixed #30801 -- Improved guidance for making good use of signals. --- docs/ref/signals.txt | 14 +++++++++++++ docs/topics/signals.txt | 44 ++++++++++++++++++++--------------------- 2 files changed, 35 insertions(+), 23 deletions(-) diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index d9c07b415c..0e2a701fcd 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -22,6 +22,14 @@ Model signals The :mod:`django.db.models.signals` module defines a set of signals sent by the model system. +.. warning:: + + Signals can make your code harder to maintain. Consider implementing a + helper method on a :ref:`custom manager `, to + both update your models and perform additional logic, or else + :ref:`overriding model methods ` before using + model signals. + .. warning:: Many of these signals are sent by various model methods like @@ -546,6 +554,12 @@ Request/response signals Signals sent by the core framework when processing a request. +.. warning:: + + Signals can make your code harder to maintain. Consider :doc:`using a + middleware ` before using request/response + signals. + ``request_started`` ------------------- diff --git a/docs/topics/signals.txt b/docs/topics/signals.txt index 829bf039df..657c89a37c 100644 --- a/docs/topics/signals.txt +++ b/docs/topics/signals.txt @@ -11,38 +11,34 @@ allow certain *senders* to notify a set of *receivers* that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. -Django provides a :doc:`set of built-in signals ` that let user -code get notified by Django itself of certain actions. These include some useful -notifications: +For example, a third-party app can register to be notified of settings +changes:: -* :data:`django.db.models.signals.pre_save` & - :data:`django.db.models.signals.post_save` + from django.apps import AppConfig + from django.core.signals import setting_changed - Sent before or after a model's :meth:`~django.db.models.Model.save` method - is called. + def my_callback(sender, **kwargs): + print("Setting changed!") -* :data:`django.db.models.signals.pre_delete` & - :data:`django.db.models.signals.post_delete` + class MyAppConfig(AppConfig): + ... - Sent before or after a model's :meth:`~django.db.models.Model.delete` - method or queryset's :meth:`~django.db.models.query.QuerySet.delete` - method is called. + def ready(self): + setting_changed.connect(my_callback) -* :data:`django.db.models.signals.m2m_changed` +Django's :doc:`built-in signals ` let user code get notified of +certain actions. - Sent when a :class:`~django.db.models.ManyToManyField` on a model is changed. +You can also define and send your own custom signals. See +:ref:`defining-and-sending-signals` below. -* :data:`django.core.signals.request_started` & - :data:`django.core.signals.request_finished` +.. warning:: - Sent when Django starts or finishes an HTTP request. + Signals give the appearance of loose coupling, but they can quickly lead to + code that is hard to understand, adjust and debug. -See the :doc:`built-in signal documentation ` for a complete list, -and a complete explanation of each signal. - -You can also `define and send your own custom signals`_; see below. - -.. _define and send your own custom signals: `defining and sending signals`_ + Where possible you should opt for directly calling the handling code, + rather than dispatching via a signal. Listening to signals ==================== @@ -218,6 +214,8 @@ bound to the signal once for each unique ``dispatch_uid`` value:: request_finished.connect(my_callback, dispatch_uid="my_unique_identifier") +.. _defining-and-sending-signals: + Defining and sending signals ============================