316 lines
8.1 KiB
Plaintext
316 lines
8.1 KiB
Plaintext
.. _ref-signals:
|
|
|
|
=========================
|
|
Built-in signal reference
|
|
=========================
|
|
|
|
A list of all the signals that Django sends.
|
|
|
|
.. seealso::
|
|
|
|
See the documentation on the :ref:`signal dispatcher <topics-signals>` for
|
|
information regarding how to register for and receive signals.
|
|
|
|
The :ref:`comment framework <ref-contrib-comments-index>` sends a :ref:`set
|
|
of comment-related signals <ref-contrib-comments-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 :ref:`tutorial <intro-tutorial01>` has this line:
|
|
|
|
.. code-block:: python
|
|
|
|
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.
|
|
|
|
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 create.
|
|
|
|
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.
|
|
|
|
Arguments sent with this signal:
|
|
|
|
``sender``
|
|
The model class.
|
|
|
|
``instance``
|
|
The actual instance being deleted.
|
|
|
|
post_delete
|
|
-----------
|
|
|
|
.. data:: django.db.models.signals.post_delete
|
|
:module:
|
|
|
|
Like :data:`pre_delete`, but sent at the end of the
|
|
:meth:`~django.db.models.Model.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.
|
|
|
|
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 :ref:`django-admin <ref-django-admin>`.
|
|
|
|
post_syncdb
|
|
-----------
|
|
|
|
.. data:: django.db.models.signals.post_syncdb
|
|
:module:
|
|
|
|
Sent by :djadmin:`syncdb` after it installs an application.
|
|
|
|
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`.
|
|
|
|
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``.
|
|
|
|
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 -- i.e.
|
|
:class:`django.core.handlers.modpython.ModPythonHandler` or
|
|
: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 :ref:`running tests <topics-testing>`.
|
|
|
|
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.
|