Ticket #11441: patch11441-1.diff

django/dispatch/dispatcher.py

@@ -41 +41 @@
                 A function or an instance method which is to receive signals.
                 Receivers must be hashable objects.
 
-                if weak is True, then receiver must be weak-referencable (more
+                If weak is True, then receiver must be weak-referencable (more
                 precisely saferef.safeRef() must be able to create a reference
                 to the receiver).
         
@@ -52 +52 @@
                 dispatch_uid.
 
             sender
-                The sender to which the receiver should respond Must either be
+                The sender to which the receiver should respond. Must either be
                 of type Signal, or None to receive events from any sender.
 
             weak
-                Whether to use weak references to the receiver By default, the
+                Whether to use weak references to the receiver. By default, the
                 module will attempt to use weak references to the receiver
                 objects. If this parameter is false, then strong references will
                 be used.
@@ -170 +170 @@
         Arguments:
         
             sender
-                The sender of the signal Can be any python object (normally one
+                The sender of the signal. Can be any python object (normally one
                 registered with a connect if you actually want something to
                 occur).
 
@@ -182 +182 @@
         Return a list of tuple pairs [(receiver, response), ... ]. May raise
         DispatcherKeyError.
 
-        if any receiver raises an error (specifically any subclass of
+        If any receiver raises an error (specifically any subclass of
         Exception), the error instance is returned as the result for that
         receiver.
         """

docs/topics/signals.txt

@@ -141 +141 @@
 the :doc:`built-in signal documentation </ref/signals>` for details of each
 particular signal.
 
+Additional signal connection options
+------------------------------------
+
+The complete signature for the signal ``connect()`` function is:
+
+.. method:: Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None)
+
+The *receiver* and *sender* arguments have been described in detail above. The
+two remaining arguments are optional, and are described here:
+
+   * *weak* - Django stores signal handlers as weak references by
+     default. Thus, if your receiver function is a local function, it may be
+     garbage collected. To prevent this, pass ``weak=False`` when you call the
+     signal's ``connect()`` function.
+
+   * *dispatch_uid* - In some circumstances, the module you are
+     connecting signals in may be imported multiple times. This can cause
+     your receiver function to be registered more than once, and thus called
+     multiples times for a single signal event. 
+
+     If this behavior is problematic (for example, you may using signals to
+     send an e-mail whenever a model is saved), pass a unique identifier as the
+     ``dispatch_uid`` argument to identify your receiver function. This
+     identifier will usually be a string, although any hashable object will
+     suffice. The end result is that your receiver function will only be
+     bound to the signal for each unique *dispatch_uid* value.
+
 Defining and sending signals
 ============================
 
@@ -171 +198 @@
 Sending signals
 ---------------
 
+There are two ways to send send signals in Django.
+
 .. method:: Signal.send(sender, **kwargs)
 
-To send a signal, call :meth:`Signal.send`. You must provide the ``sender`` argument, and may provide as many other keyword arguments as you like.
+.. method:: Signal.send_robust(sender, **kwargs)
 
+To send a signal, call either :meth:`Signal.send` or :meth:`Signal.send_robust`.
+You must provide the ``sender`` argument, and may provide as many other keyword
+arguments as you like.
+
 For example, here's how sending our ``pizza_done`` signal might look:
 
 .. code-block:: python
@@ -186 +219 @@
             pizza_done.send(sender=self, toppings=toppings, size=size)
             ...
 
+Both ``send()`` and ``send_robust()`` return a list of tuple pairs
+``[(receiver, response), ... ]``, representing the list of called receiver
+functions and their response values.
 
+``send()`` differs from ``send_robust()`` in how exceptions raised by receiver
+functions are handled. ``send()`` does *not* catch any exceptions raised by
+receivers; it simply allows errors to propagate. Thus not all receivers may
+be notified of a signal in the face of an error.
+
+``send_robust()`` catches all errors derived from Python's ``Exception`` class,
+and ensures all receivers are notified of the signal. If an error occurs, the
+error instance is returned in the tuple pair for the receiver that raised the error.
+
+Disconnecting signals
+=====================
+
+.. method:: Signal.disconnect(receiver=None, sender=None, weak=True, dispatch_uid=None)
+
+To disconnect a receiver from a signal, call :meth:`Signal.disconnect`. The
+arguments are as described in `additional signal connection options`_.
+
+The *receiver* argument indicates the registered receiver to disconnect. It may
+be ``None`` if ``dispatch_uid`` is used to identify the receiver.