← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/python-django/jaunty

« back to all changes in this revision

Viewing changes to docs/ref/signals.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant, Eddy Mulyono
  • Date: 2008-09-16 12:18:47 UTC
  • mfrom: (1.1.5 upstream) (4.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080916121847-mg225rg5mnsdqzr0
Tags: 1.0-1ubuntu1
https://launchpad.net/bugs/264191
* Merge from Debian (LP: #264191), remaining changes:
  - Run test suite on build.

[Eddy Mulyono]
* Update patch to workaround network test case failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/signals.txt
 
1
.. _ref-signals:
 
2
 
 
3
=========================
 
4
Built-in signal reference
 
5
=========================
 
6
 
 
7
A list of all the signals that Django sends.
 
8
 
 
9
.. seealso::
 
10
 
 
11
    The :ref:`comment framework <ref-contrib-comments-index>` sends a :ref:`set
 
12
    of comment-related signals <ref-contrib-comments-signals>`.
 
13
 
 
14
Model signals
 
15
=============
 
16
 
 
17
.. module:: django.db.models.signals
 
18
   :synopsis: Signals sent by the model system.
 
19
 
 
20
The :mod:`django.db.models.signals` module defines a set of signals sent by the
 
21
module system.
 
22
 
 
23
.. warning::
 
24
 
 
25
    Many of these signals are sent by various model methods like
 
26
    :meth:`~django.db.models.Model.__init__` or
 
27
    :meth:`~django.db.models.Model.save` that you can overwrite in your own
 
28
    code.
 
29
 
 
30
    If you override these methods on your model, you must call the parent class'
 
31
    methods for this signals to be sent.
 
32
 
 
33
pre_init
 
34
--------
 
35
 
 
36
.. attribute:: django.db.models.signals.pre_init
 
37
   :module:
 
38
 
 
39
.. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
 
40
 
 
41
Whenever you instantiate a Django model,, this signal is sent at the beginning
 
42
of the model's :meth:`~django.db.models.Model.__init__` method.
 
43
 
 
44
Arguments sent with this signal:
 
45
 
 
46
    ``sender``
 
47
        The model class that just had an instance created.
 
48
 
 
49
    ``args``
 
50
        A list of positional arguments passed to
 
51
        :meth:`~django.db.models.Model.__init__`:
 
52
 
 
53
    ``kwargs``
 
54
        A dictionary of keyword arguments passed to
 
55
        :meth:`~django.db.models.Model.__init__`:.
 
56
 
 
57
For example, the :ref:`tutorial <intro-tutorial01>` has this line:
 
58
 
 
59
.. code-block:: python
 
60
 
 
61
    p = Poll(question="What's up?", pub_date=datetime.now())
 
62
 
 
63
The arguments sent to a :data:`pre_init` handler would be:
 
64
 
 
65
    ==========  ===============================================================
 
66
    Argument    Value
 
67
    ==========  ===============================================================
 
68
    ``sender``  ``Poll`` (the class itself)
 
69
 
 
70
    ``args``    ``[]`` (an empty list because there were no positional
 
71
                arguments passed to ``__init__``.)
 
72
 
 
73
    ``kwargs``  ``{'question': "What's up?", 'pub_date': datetime.now()}``
 
74
    ==========  ===============================================================
 
75
 
 
76
post_init
 
77
---------
 
78
 
 
79
.. data:: django.db.models.signals.post_init
 
80
   :module:
 
81
 
 
82
Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.
 
83
 
 
84
Arguments sent with this signal:
 
85
 
 
86
    ``sender``
 
87
        As above: rhe model class that just had an instance created.
 
88
 
 
89
    ``instance``
 
90
        The actual instance of the model that's just been created.
 
91
 
 
92
pre_save
 
93
--------
 
94
 
 
95
.. data:: django.db.models.signals.pre_save
 
96
   :module:
 
97
   
 
98
This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
 
99
method.
 
100
 
 
101
Arguments sent with this signal:
 
102
 
 
103
    ``sender``
 
104
        The model class.
 
105
 
 
106
    ``instance``
 
107
        The actual instance being saved.
 
108
 
 
109
post_save
 
110
---------
 
111
 
 
112
.. data:: django.db.models.signals.post_save
 
113
   :module: 
 
114
   
 
115
Like :data:`pre_save`, but sent at the end of the
 
116
:meth:`~django.db.models.Model.save` method.
 
117
 
 
118
Arguments sent with this signal:
 
119
 
 
120
    ``sender``
 
121
        The model class.
 
122
 
 
123
    ``instance``
 
124
        The actual instance being saved.
 
125
 
 
126
    ``created``
 
127
        A boolean; ``True`` if a new record was create.
 
128
 
 
129
pre_delete
 
130
----------
 
131
 
 
132
.. data:: django.db.models.signals.pre_delete
 
133
   :module:
 
134
   
 
135
Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
 
136
method.
 
137
 
 
138
Arguments sent with this signal:
 
139
 
 
140
    ``sender``
 
141
        The model class.
 
142
 
 
143
    ``instance``
 
144
        The actual instance being saved.
 
145
 
 
146
post_delete
 
147
-----------
 
148
 
 
149
.. data:: django.db.models.signals.post_delete
 
150
   :module: 
 
151
   
 
152
Like :data:`pre_delete`, but sent at the end of the
 
153
:meth:`~django.db.models.Model.delete` method.
 
154
 
 
155
Arguments sent with this signal:
 
156
 
 
157
    ``sender``
 
158
        The model class.
 
159
 
 
160
    ``instance``
 
161
        The actual instance being saved.
 
162
 
 
163
        Note that the object will no longer be in the database, so be very
 
164
        careful what you do with this instance
 
165
 
 
166
class_prepared
 
167
--------------
 
168
 
 
169
.. data:: django.db.models.signals.class_prepared
 
170
   :module:
 
171
   
 
172
Sent whenever a model class has been "prepared" -- that is, once model has
 
173
been defined and registered with Django's model system. Django uses this
 
174
signal internally; it's not generally used in third-party applications.
 
175
 
 
176
Arguments that are sent with this signal:
 
177
 
 
178
``sender``
 
179
    The model class which was just prepared.
 
180
 
 
181
Management signals
 
182
==================
 
183
 
 
184
Signals sent by :ref:`django-admin <ref-django-admin>`.
 
185
 
 
186
post_syncdb
 
187
-----------
 
188
 
 
189
.. data:: django.db.models.signals.post_syncdb
 
190
   :module:
 
191
 
 
192
Sent by :djadmin:`syncdb` after it installs an application.
 
193
 
 
194
Any handlers that listen to this signal need to be written in a particular
 
195
place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If
 
196
handlers are registered anywhere else they may not be loaded by
 
197
:djadmin:`syncdb`.
 
198
 
 
199
Arguments sent with this signal:
 
200
 
 
201
    ``sender``
 
202
        The ``models`` module that was just installed. That is, if
 
203
        :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,
 
204
        ``sender`` will be the ``foo.bar.myapp.models`` module.
 
205
 
 
206
    ``app``
 
207
        Same as ``sender``.
 
208
 
 
209
    ``created_models``
 
210
        A list of the model classes from any app which :djadmin:`syncdb` has
 
211
        created so far.
 
212
 
 
213
    ``verbosity``
 
214
        Indicates how much information manage.py is printing on screen. See
 
215
        the :djadminopt:`--verbosity`` flag for details.
 
216
 
 
217
        Functions which listen for :data:`post_syncdb` should adjust what they
 
218
        output to the screen based on the value of this argument.
 
219
 
 
220
    ``interactive``
 
221
        If ``interactive`` is ``True``, it's safe to prompt the user to input
 
222
        things on the command line. If ``interactive`` is ``False``, functions
 
223
        which listen for this signal should not try to prompt for anything.
 
224
 
 
225
        For example, the :mod:`django.contrib.auth` app only prompts to create a
 
226
        superuser when ``interactive`` is ``True``.
 
227
 
 
228
Request/response signals
 
229
========================
 
230
 
 
231
.. module:: django.core.signals
 
232
   :synopsis: Core signals sent by the request/response system.
 
233
 
 
234
Signals sent by the core framework when processing a request.
 
235
 
 
236
request_started
 
237
---------------
 
238
 
 
239
.. data:: django.core.signals.request_started
 
240
   :module: 
 
241
   
 
242
Sent when Django begins processing an HTTP request.
 
243
 
 
244
Arguments sent with this signal:
 
245
 
 
246
    ``sender``
 
247
        The handler class -- i.e.
 
248
        :class:`django.core.handlers.modpython.ModPythonHandler` or
 
249
        :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled
 
250
        the request.
 
251
 
 
252
request_finished
 
253
----------------
 
254
 
 
255
.. data:: django.core.signals.request_finished
 
256
   :module:
 
257
   
 
258
Sent when Django finishes processing an HTTP request.
 
259
 
 
260
Arguments sent with this signal:
 
261
 
 
262
    ``sender``
 
263
        The handler class, as above.
 
264
 
 
265
got_request_exception
 
266
---------------------
 
267
 
 
268
.. data:: django.core.signals.got_request_exception
 
269
   :module:
 
270
   
 
271
This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
 
272
 
 
273
Arguments sent with this signal:
 
274
 
 
275
    ``sender``
 
276
        The handler class, as above.
 
277
 
 
278
    ``request``
 
279
        The :class:`~django.http.HttpRequest` object.
 
280
 
 
281
Test signals
 
282
============
 
283
 
 
284
.. module:: django.test.signals
 
285
   :synopsis: Signals sent during testing.
 
286
 
 
287
Signals only sent when :ref:`running tests <topics-testing>`.
 
288
 
 
289
template_rendered
 
290
-----------------
 
291
 
 
292
.. data:: django.test.signals.template_rendered
 
293
   :module:
 
294
   
 
295
Sent when the test system renders a template. This signal is not emitted during
 
296
normal operation of a Django server -- it is only available during testing.
 
297
 
 
298
Arguments sent with this signal:
 
299
 
 
300
    sender
 
301
        The :class:`~django.template.Template` object which was rendered.
 
302
 
 
303
    template
 
304
        Same as sender
 
305
 
 
306
    context
 
307
        The :class:`~django.template.Context` with which the template was
 
308
        rendered.