559 lines
16 KiB
Plaintext
559 lines
16 KiB
Plaintext
=======
|
|
Signals
|
|
=======
|
|
|
|
A list of all the signals that Django sends.
|
|
|
|
.. seealso::
|
|
|
|
See the documentation on the :doc:`signal dispatcher </topics/signals>` for
|
|
information regarding how to register for and receive signals.
|
|
|
|
The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set
|
|
of comment-related signals </ref/contrib/comments/signals>`.
|
|
|
|
The :doc:`authentication framework </topics/auth>` sends :ref:`signals when
|
|
a user is logged in / out <topics-auth-signals>`.
|
|
|
|
Model signals
|
|
=============
|
|
|
|
.. module:: django.db.models.signals
|
|
:synopsis: Signals sent by the model system.
|
|
|
|
The :mod:`django.db.models.signals` module defines a set of signals sent by the
|
|
module system.
|
|
|
|
.. warning::
|
|
|
|
Many of these signals are sent by various model methods like
|
|
:meth:`~django.db.models.Model.__init__` or
|
|
:meth:`~django.db.models.Model.save` that you can overwrite in your own
|
|
code.
|
|
|
|
If you override these methods on your model, you must call the parent class'
|
|
methods for this signals to be sent.
|
|
|
|
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 :meth:`~django.dispatch.Signal.connect`.
|
|
|
|
pre_init
|
|
--------
|
|
|
|
.. attribute:: django.db.models.signals.pre_init
|
|
:module:
|
|
|
|
.. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
|
|
|
|
Whenever you instantiate a Django model, this signal is sent at the beginning
|
|
of the model's :meth:`~django.db.models.Model.__init__` method.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The model class that just had an instance created.
|
|
|
|
``args``
|
|
A list of positional arguments passed to
|
|
:meth:`~django.db.models.Model.__init__`:
|
|
|
|
``kwargs``
|
|
A dictionary of keyword arguments passed to
|
|
:meth:`~django.db.models.Model.__init__`:.
|
|
|
|
For example, the :doc:`tutorial </intro/tutorial01>` has this line::
|
|
|
|
p = Poll(question="What's up?", pub_date=datetime.now())
|
|
|
|
The arguments sent to a :data:`pre_init` handler would be:
|
|
|
|
========== ===============================================================
|
|
Argument Value
|
|
========== ===============================================================
|
|
``sender`` ``Poll`` (the class itself)
|
|
|
|
``args`` ``[]`` (an empty list because there were no positional
|
|
arguments passed to ``__init__``.)
|
|
|
|
``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}``
|
|
========== ===============================================================
|
|
|
|
post_init
|
|
---------
|
|
|
|
.. data:: django.db.models.signals.post_init
|
|
:module:
|
|
|
|
Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
As above: the model class that just had an instance created.
|
|
|
|
``instance``
|
|
The actual instance of the model that's just been created.
|
|
|
|
pre_save
|
|
--------
|
|
|
|
.. data:: django.db.models.signals.pre_save
|
|
:module:
|
|
|
|
This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
|
|
method.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The model class.
|
|
|
|
``instance``
|
|
The actual instance being saved.
|
|
|
|
``raw``
|
|
A boolean; ``True`` if the model is saved exactly as presented
|
|
(i.e. when loading a fixture). One should not query/modify other
|
|
records in the database as the database might not be in a
|
|
consistent state yet.
|
|
|
|
``using``
|
|
The database alias being used.
|
|
|
|
.. versionadded:: 1.5
|
|
|
|
``update_fields``
|
|
The set of fields to update explicitly specified in the ``save()`` method.
|
|
``None`` if this argument was not used in the ``save()`` call.
|
|
|
|
post_save
|
|
---------
|
|
|
|
.. data:: django.db.models.signals.post_save
|
|
:module:
|
|
|
|
Like :data:`pre_save`, but sent at the end of the
|
|
:meth:`~django.db.models.Model.save` method.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The model class.
|
|
|
|
``instance``
|
|
The actual instance being saved.
|
|
|
|
``created``
|
|
A boolean; ``True`` if a new record was created.
|
|
|
|
``raw``
|
|
A boolean; ``True`` if the model is saved exactly as presented
|
|
(i.e. when loading a fixture). One should not query/modify other
|
|
records in the database as the database might not be in a
|
|
consistent state yet.
|
|
|
|
``using``
|
|
The database alias being used.
|
|
|
|
.. versionadded:: 1.5
|
|
|
|
``update_fields``
|
|
The set of fields to update explicitly specified in the ``save()`` method.
|
|
``None`` if this argument was not used in the ``save()`` call.
|
|
|
|
pre_delete
|
|
----------
|
|
|
|
.. data:: django.db.models.signals.pre_delete
|
|
:module:
|
|
|
|
Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
|
|
method and a queryset's :meth:`~django.db.models.query.QuerySet.delete` method.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The model class.
|
|
|
|
``instance``
|
|
The actual instance being deleted.
|
|
|
|
``using``
|
|
The database alias being used.
|
|
|
|
post_delete
|
|
-----------
|
|
|
|
.. data:: django.db.models.signals.post_delete
|
|
:module:
|
|
|
|
Like :data:`pre_delete`, but sent at the end of a model's
|
|
:meth:`~django.db.models.Model.delete` method and a queryset's
|
|
:meth:`~django.db.models.query.QuerySet.delete` method.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The model class.
|
|
|
|
``instance``
|
|
The actual instance being deleted.
|
|
|
|
Note that the object will no longer be in the database, so be very
|
|
careful what you do with this instance.
|
|
|
|
``using``
|
|
The database alias being used.
|
|
|
|
m2m_changed
|
|
-----------
|
|
|
|
.. data:: django.db.models.signals.m2m_changed
|
|
:module:
|
|
|
|
Sent when a :class:`ManyToManyField` is changed on a model instance.
|
|
Strictly speaking, this is not a model signal since it is sent by the
|
|
:class:`ManyToManyField`, but since it complements the
|
|
:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
|
|
when it comes to tracking changes to models, it is included here.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The intermediate model class describing the :class:`ManyToManyField`.
|
|
This class is automatically created when a many-to-many field is
|
|
defined; you can access it using the ``through`` attribute on the
|
|
many-to-many field.
|
|
|
|
``instance``
|
|
The instance whose many-to-many relation is updated. This can be an
|
|
instance of the ``sender``, or of the class the :class:`ManyToManyField`
|
|
is related to.
|
|
|
|
``action``
|
|
A string indicating the type of update that is done on the relation.
|
|
This can be one of the following:
|
|
|
|
``"pre_add"``
|
|
Sent *before* one or more objects are added to the relation.
|
|
``"post_add"``
|
|
Sent *after* one or more objects are added to the relation.
|
|
``"pre_remove"``
|
|
Sent *before* one or more objects are removed from the relation.
|
|
``"post_remove"``
|
|
Sent *after* one or more objects are removed from the relation.
|
|
``"pre_clear"``
|
|
Sent *before* the relation is cleared.
|
|
``"post_clear"``
|
|
Sent *after* the relation is cleared.
|
|
|
|
``reverse``
|
|
Indicates which side of the relation is updated (i.e., if it is the
|
|
forward or reverse relation that is being modified).
|
|
|
|
``model``
|
|
The class of the objects that are added to, removed from or cleared
|
|
from the relation.
|
|
|
|
``pk_set``
|
|
For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``
|
|
actions, this is a list of primary key values that have been added to
|
|
or removed from the relation.
|
|
|
|
For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.
|
|
|
|
``using``
|
|
The database alias being used.
|
|
|
|
For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
|
|
like this::
|
|
|
|
class Topping(models.Model):
|
|
# ...
|
|
pass
|
|
|
|
class Pizza(models.Model):
|
|
# ...
|
|
toppings = models.ManyToManyField(Topping)
|
|
|
|
If we connected a handler like this::
|
|
|
|
def toppings_changed(sender, **kwargs):
|
|
# Do something
|
|
pass
|
|
|
|
m2m_changed.connect(toppings_changed, sender=Pizza.toppings.through)
|
|
|
|
and then did something like this::
|
|
|
|
>>> p = Pizza.object.create(...)
|
|
>>> t = Topping.objects.create(...)
|
|
>>> p.toppings.add(t)
|
|
|
|
the arguments sent to a :data:`m2m_changed` handler (``topppings_changed`` in
|
|
the example above) would be:
|
|
|
|
============== ============================================================
|
|
Argument Value
|
|
============== ============================================================
|
|
``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
|
|
|
|
``instance`` ``p`` (the ``Pizza`` instance being modified)
|
|
|
|
``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``)
|
|
|
|
``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`,
|
|
so this call modifies the forward relation)
|
|
|
|
``model`` ``Topping`` (the class of the objects added to the
|
|
``Pizza``)
|
|
|
|
``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation)
|
|
|
|
``using`` ``"default"`` (since the default router sends writes here)
|
|
============== ============================================================
|
|
|
|
And if we would then do something like this::
|
|
|
|
>>> t.pizza_set.remove(p)
|
|
|
|
the arguments sent to a :data:`m2m_changed` handler would be:
|
|
|
|
============== ============================================================
|
|
Argument Value
|
|
============== ============================================================
|
|
``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
|
|
|
|
``instance`` ``t`` (the ``Topping`` instance being modified)
|
|
|
|
``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)
|
|
|
|
``reverse`` ``True`` (``Pizza`` contains the :class:`ManyToManyField`,
|
|
so this call modifies the reverse relation)
|
|
|
|
``model`` ``Pizza`` (the class of the objects removed from the
|
|
``Topping``)
|
|
|
|
``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the
|
|
relation)
|
|
|
|
``using`` ``"default"`` (since the default router sends writes here)
|
|
============== ============================================================
|
|
|
|
class_prepared
|
|
--------------
|
|
|
|
.. data:: django.db.models.signals.class_prepared
|
|
:module:
|
|
|
|
Sent whenever a model class has been "prepared" -- that is, once model has
|
|
been defined and registered with Django's model system. Django uses this
|
|
signal internally; it's not generally used in third-party applications.
|
|
|
|
Arguments that are sent with this signal:
|
|
|
|
``sender``
|
|
The model class which was just prepared.
|
|
|
|
Management signals
|
|
==================
|
|
|
|
Signals sent by :doc:`django-admin </ref/django-admin>`.
|
|
|
|
post_syncdb
|
|
-----------
|
|
|
|
.. data:: django.db.models.signals.post_syncdb
|
|
:module:
|
|
|
|
Sent by the :djadmin:`syncdb` command after it installs an application, and the
|
|
:djadmin:`flush` command.
|
|
|
|
Any handlers that listen to this signal need to be written in a particular
|
|
place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If
|
|
handlers are registered anywhere else they may not be loaded by
|
|
:djadmin:`syncdb`. It is important that handlers of this signal perform
|
|
idempotent changes (e.g. no database alterations) as this may cause the
|
|
:djadmin:`flush` management command to fail if it also ran during the
|
|
:djadmin:`syncdb` command.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The ``models`` module that was just installed. That is, if
|
|
:djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,
|
|
``sender`` will be the ``foo.bar.myapp.models`` module.
|
|
|
|
``app``
|
|
Same as ``sender``.
|
|
|
|
``created_models``
|
|
A list of the model classes from any app which :djadmin:`syncdb` has
|
|
created so far.
|
|
|
|
``verbosity``
|
|
Indicates how much information manage.py is printing on screen. See
|
|
the :djadminopt:`--verbosity` flag for details.
|
|
|
|
Functions which listen for :data:`post_syncdb` should adjust what they
|
|
output to the screen based on the value of this argument.
|
|
|
|
``interactive``
|
|
If ``interactive`` is ``True``, it's safe to prompt the user to input
|
|
things on the command line. If ``interactive`` is ``False``, functions
|
|
which listen for this signal should not try to prompt for anything.
|
|
|
|
For example, the :mod:`django.contrib.auth` app only prompts to create a
|
|
superuser when ``interactive`` is ``True``.
|
|
|
|
For example, ``yourapp/management/__init__.py`` could be written like::
|
|
|
|
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)
|
|
|
|
Request/response signals
|
|
========================
|
|
|
|
.. module:: django.core.signals
|
|
:synopsis: Core signals sent by the request/response system.
|
|
|
|
Signals sent by the core framework when processing a request.
|
|
|
|
request_started
|
|
---------------
|
|
|
|
.. data:: django.core.signals.request_started
|
|
:module:
|
|
|
|
Sent when Django begins processing an HTTP request.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The handler class -- e.g.
|
|
:class:`django.core.handlers.wsgi.WsgiHandler` -- that handled
|
|
the request.
|
|
|
|
request_finished
|
|
----------------
|
|
|
|
.. data:: django.core.signals.request_finished
|
|
:module:
|
|
|
|
Sent when Django finishes processing an HTTP request.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The handler class, as above.
|
|
|
|
got_request_exception
|
|
---------------------
|
|
|
|
.. data:: django.core.signals.got_request_exception
|
|
:module:
|
|
|
|
This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The handler class, as above.
|
|
|
|
``request``
|
|
The :class:`~django.http.HttpRequest` object.
|
|
|
|
Test signals
|
|
============
|
|
|
|
.. module:: django.test.signals
|
|
:synopsis: Signals sent during testing.
|
|
|
|
Signals only sent when :doc:`running tests </topics/testing>`.
|
|
|
|
setting_changed
|
|
---------------
|
|
|
|
.. versionadded:: 1.4
|
|
|
|
.. data:: django.test.signals.setting_changed
|
|
:module:
|
|
|
|
This signal is sent when the value of a setting is changed through the
|
|
:meth:`django.test.TestCase.setting` context manager or the
|
|
:func:`django.test.utils.override_settings` decorator/context manager.
|
|
|
|
It's actually sent twice: when the new value is applied ("setup") and when the
|
|
original value is restored ("teardown").
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The settings handler.
|
|
|
|
``setting``
|
|
The name of the setting.
|
|
|
|
``value``
|
|
The value of the setting after the change. For settings that initially
|
|
don't exist, in the "teardown" phase, ``value`` is ``None``.
|
|
|
|
template_rendered
|
|
-----------------
|
|
|
|
.. data:: django.test.signals.template_rendered
|
|
:module:
|
|
|
|
Sent when the test system renders a template. This signal is not emitted during
|
|
normal operation of a Django server -- it is only available during testing.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The :class:`~django.template.Template` object which was rendered.
|
|
|
|
``template``
|
|
Same as sender
|
|
|
|
``context``
|
|
The :class:`~django.template.Context` with which the template was
|
|
rendered.
|
|
|
|
Database Wrappers
|
|
=================
|
|
|
|
.. module:: django.db.backends
|
|
:synopsis: Core signals sent by the database wrapper.
|
|
|
|
Signals sent by the database wrapper when a database connection is
|
|
initiated.
|
|
|
|
connection_created
|
|
------------------
|
|
|
|
.. data:: django.db.backends.signals.connection_created
|
|
:module:
|
|
|
|
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.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The database wrapper class -- i.e.
|
|
:class:`django.db.backends.postgresql_psycopg2.DatabaseWrapper` or
|
|
:class:`django.db.backends.mysql.DatabaseWrapper`, etc.
|
|
|
|
``connection``
|
|
The database connection that was opened. This can be used in a
|
|
multiple-database configuration to differentiate connection signals
|
|
from different databases.
|