Ticket #11441: patch11441-1.diff

File patch11441-1.diff, 5.5 KB (added by gremmie, 5 years ago)
  • django/dispatch/dispatcher.py

     
    4141                A function or an instance method which is to receive signals.
    4242                Receivers must be hashable objects.
    4343
    44                 if weak is True, then receiver must be weak-referencable (more
     44                If weak is True, then receiver must be weak-referencable (more
    4545                precisely saferef.safeRef() must be able to create a reference
    4646                to the receiver).
    4747       
     
    5252                dispatch_uid.
    5353
    5454            sender
    55                 The sender to which the receiver should respond Must either be
     55                The sender to which the receiver should respond. Must either be
    5656                of type Signal, or None to receive events from any sender.
    5757
    5858            weak
    59                 Whether to use weak references to the receiver By default, the
     59                Whether to use weak references to the receiver. By default, the
    6060                module will attempt to use weak references to the receiver
    6161                objects. If this parameter is false, then strong references will
    6262                be used.
     
    170170        Arguments:
    171171       
    172172            sender
    173                 The sender of the signal Can be any python object (normally one
     173                The sender of the signal. Can be any python object (normally one
    174174                registered with a connect if you actually want something to
    175175                occur).
    176176
     
    182182        Return a list of tuple pairs [(receiver, response), ... ]. May raise
    183183        DispatcherKeyError.
    184184
    185         if any receiver raises an error (specifically any subclass of
     185        If any receiver raises an error (specifically any subclass of
    186186        Exception), the error instance is returned as the result for that
    187187        receiver.
    188188        """
  • docs/topics/signals.txt

     
    141141the :doc:`built-in signal documentation </ref/signals>` for details of each
    142142particular signal.
    143143
     144Additional signal connection options
     145------------------------------------
     146
     147The complete signature for the signal ``connect()`` function is:
     148
     149.. method:: Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None)
     150
     151The *receiver* and *sender* arguments have been described in detail above. The
     152two remaining arguments are optional, and are described here:
     153
     154   * *weak* - Django stores signal handlers as weak references by
     155     default. Thus, if your receiver function is a local function, it may be
     156     garbage collected. To prevent this, pass ``weak=False`` when you call the
     157     signal's ``connect()`` function.
     158
     159   * *dispatch_uid* - In some circumstances, the module you are
     160     connecting signals in may be imported multiple times. This can cause
     161     your receiver function to be registered more than once, and thus called
     162     multiples times for a single signal event.
     163
     164     If this behavior is problematic (for example, you may using signals to
     165     send an e-mail whenever a model is saved), pass a unique identifier as the
     166     ``dispatch_uid`` argument to identify your receiver function. This
     167     identifier will usually be a string, although any hashable object will
     168     suffice. The end result is that your receiver function will only be
     169     bound to the signal for each unique *dispatch_uid* value.
     170
    144171Defining and sending signals
    145172============================
    146173
     
    171198Sending signals
    172199---------------
    173200
     201There are two ways to send send signals in Django.
     202
    174203.. method:: Signal.send(sender, **kwargs)
    175204
    176 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.
     205.. method:: Signal.send_robust(sender, **kwargs)
    177206
     207To send a signal, call either :meth:`Signal.send` or :meth:`Signal.send_robust`.
     208You must provide the ``sender`` argument, and may provide as many other keyword
     209arguments as you like.
     210
    178211For example, here's how sending our ``pizza_done`` signal might look:
    179212
    180213.. code-block:: python
     
    186219            pizza_done.send(sender=self, toppings=toppings, size=size)
    187220            ...
    188221
     222Both ``send()`` and ``send_robust()`` return a list of tuple pairs
     223``[(receiver, response), ... ]``, representing the list of called receiver
     224functions and their response values.
    189225
     226``send()`` differs from ``send_robust()`` in how exceptions raised by receiver
     227functions are handled. ``send()`` does *not* catch any exceptions raised by
     228receivers; it simply allows errors to propagate. Thus not all receivers may
     229be notified of a signal in the face of an error.
     230
     231``send_robust()`` catches all errors derived from Python's ``Exception`` class,
     232and ensures all receivers are notified of the signal. If an error occurs, the
     233error instance is returned in the tuple pair for the receiver that raised the error.
     234
     235Disconnecting signals
     236=====================
     237
     238.. method:: Signal.disconnect(receiver=None, sender=None, weak=True, dispatch_uid=None)
     239
     240To disconnect a receiver from a signal, call :meth:`Signal.disconnect`. The
     241arguments are as described in `additional signal connection options`_.
     242
     243The *receiver* argument indicates the registered receiver to disconnect. It may
     244be ``None`` if ``dispatch_uid`` is used to identify the receiver.
Back to Top