/docs/ref/signals.txt

https://code.google.com/p/mango-py/ · Plain Text · 515 lines · 345 code · 170 blank · 0 comment · 0 complexity · 8a7fe644a9e74a634831fccf56e6d755 MD5 · raw file

  1. =======
  2. Signals
  3. =======
  4. A list of all the signals that Django sends.
  5. .. seealso::
  6. See the documentation on the :doc:`signal dispatcher </topics/signals>` for
  7. information regarding how to register for and receive signals.
  8. The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set
  9. of comment-related signals </ref/contrib/comments/signals>`.
  10. The :doc:`authentication framework </topics/auth>` sends :ref:`signals when
  11. a user is logged in / out <topics-auth-signals>`.
  12. Model signals
  13. =============
  14. .. module:: django.db.models.signals
  15. :synopsis: Signals sent by the model system.
  16. The :mod:`django.db.models.signals` module defines a set of signals sent by the
  17. module system.
  18. .. warning::
  19. Many of these signals are sent by various model methods like
  20. :meth:`~django.db.models.Model.__init__` or
  21. :meth:`~django.db.models.Model.save` that you can overwrite in your own
  22. code.
  23. If you override these methods on your model, you must call the parent class'
  24. methods for this signals to be sent.
  25. Note also that Django stores signal handlers as weak references by default,
  26. so if your handler is a local function, it may be garbage collected. To
  27. prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
  28. pre_init
  29. --------
  30. .. attribute:: django.db.models.signals.pre_init
  31. :module:
  32. .. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
  33. Whenever you instantiate a Django model,, this signal is sent at the beginning
  34. of the model's :meth:`~django.db.models.Model.__init__` method.
  35. Arguments sent with this signal:
  36. ``sender``
  37. The model class that just had an instance created.
  38. ``args``
  39. A list of positional arguments passed to
  40. :meth:`~django.db.models.Model.__init__`:
  41. ``kwargs``
  42. A dictionary of keyword arguments passed to
  43. :meth:`~django.db.models.Model.__init__`:.
  44. For example, the :doc:`tutorial </intro/tutorial01>` has this line:
  45. .. code-block:: python
  46. p = Poll(question="What's up?", pub_date=datetime.now())
  47. The arguments sent to a :data:`pre_init` handler would be:
  48. ========== ===============================================================
  49. Argument Value
  50. ========== ===============================================================
  51. ``sender`` ``Poll`` (the class itself)
  52. ``args`` ``[]`` (an empty list because there were no positional
  53. arguments passed to ``__init__``.)
  54. ``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}``
  55. ========== ===============================================================
  56. post_init
  57. ---------
  58. .. data:: django.db.models.signals.post_init
  59. :module:
  60. Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.
  61. Arguments sent with this signal:
  62. ``sender``
  63. As above: the model class that just had an instance created.
  64. ``instance``
  65. The actual instance of the model that's just been created.
  66. pre_save
  67. --------
  68. .. data:: django.db.models.signals.pre_save
  69. :module:
  70. This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
  71. method.
  72. Arguments sent with this signal:
  73. ``sender``
  74. The model class.
  75. ``instance``
  76. The actual instance being saved.
  77. .. versionadded:: 1.3
  78. ``using``
  79. The database alias being used.
  80. post_save
  81. ---------
  82. .. data:: django.db.models.signals.post_save
  83. :module:
  84. Like :data:`pre_save`, but sent at the end of the
  85. :meth:`~django.db.models.Model.save` method.
  86. Arguments sent with this signal:
  87. ``sender``
  88. The model class.
  89. ``instance``
  90. The actual instance being saved.
  91. ``created``
  92. A boolean; ``True`` if a new record was created.
  93. .. versionadded:: 1.3
  94. ``using``
  95. The database alias being used.
  96. pre_delete
  97. ----------
  98. .. data:: django.db.models.signals.pre_delete
  99. :module:
  100. Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
  101. method.
  102. Arguments sent with this signal:
  103. ``sender``
  104. The model class.
  105. ``instance``
  106. The actual instance being deleted.
  107. .. versionadded:: 1.3
  108. ``using``
  109. The database alias being used.
  110. post_delete
  111. -----------
  112. .. data:: django.db.models.signals.post_delete
  113. :module:
  114. Like :data:`pre_delete`, but sent at the end of the
  115. :meth:`~django.db.models.Model.delete` method.
  116. Arguments sent with this signal:
  117. ``sender``
  118. The model class.
  119. ``instance``
  120. The actual instance being deleted.
  121. Note that the object will no longer be in the database, so be very
  122. careful what you do with this instance.
  123. .. versionadded:: 1.3
  124. ``using``
  125. The database alias being used.
  126. m2m_changed
  127. -----------
  128. .. data:: django.db.models.signals.m2m_changed
  129. :module:
  130. .. versionadded:: 1.2
  131. Sent when a :class:`ManyToManyField` is changed on a model instance.
  132. Strictly speaking, this is not a model signal since it is sent by the
  133. :class:`ManyToManyField`, but since it complements the
  134. :data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
  135. when it comes to tracking changes to models, it is included here.
  136. Arguments sent with this signal:
  137. ``sender``
  138. The intermediate model class describing the :class:`ManyToManyField`.
  139. This class is automatically created when a many-to-many field is
  140. defined; you can access it using the ``through`` attribute on the
  141. many-to-many field.
  142. ``instance``
  143. The instance whose many-to-many relation is updated. This can be an
  144. instance of the ``sender``, or of the class the :class:`ManyToManyField`
  145. is related to.
  146. ``action``
  147. A string indicating the type of update that is done on the relation.
  148. This can be one of the following:
  149. ``"pre_add"``
  150. Sent *before* one or more objects are added to the relation.
  151. ``"post_add"``
  152. Sent *after* one or more objects are added to the relation.
  153. ``"pre_remove"``
  154. Sent *before* one or more objects are removed from the relation.
  155. ``"post_remove"``
  156. Sent *after* one or more objects are removed from the relation.
  157. ``"pre_clear"``
  158. Sent *before* the relation is cleared.
  159. ``"post_clear"``
  160. Sent *after* the relation is cleared.
  161. ``reverse``
  162. Indicates which side of the relation is updated (i.e., if it is the
  163. forward or reverse relation that is being modified).
  164. ``model``
  165. The class of the objects that are added to, removed from or cleared
  166. from the relation.
  167. ``pk_set``
  168. For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``
  169. actions, this is a list of primary key values that have been added to
  170. or removed from the relation.
  171. For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.
  172. .. versionadded:: 1.3
  173. ``using``
  174. The database alias being used.
  175. For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
  176. like this:
  177. .. code-block:: python
  178. class Topping(models.Model):
  179. # ...
  180. class Pizza(models.Model):
  181. # ...
  182. toppings = models.ManyToManyField(Topping)
  183. If we would do something like this:
  184. .. code-block:: python
  185. >>> p = Pizza.object.create(...)
  186. >>> t = Topping.objects.create(...)
  187. >>> p.toppings.add(t)
  188. the arguments sent to a :data:`m2m_changed` handler would be:
  189. ============== ============================================================
  190. Argument Value
  191. ============== ============================================================
  192. ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
  193. ``instance`` ``p`` (the ``Pizza`` instance being modified)
  194. ``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``)
  195. ``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`,
  196. so this call modifies the forward relation)
  197. ``model`` ``Topping`` (the class of the objects added to the
  198. ``Pizza``)
  199. ``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation)
  200. ``using`` ``"default"`` (since the default router sends writes here)
  201. ============== ============================================================
  202. And if we would then do something like this:
  203. .. code-block:: python
  204. >>> t.pizza_set.remove(p)
  205. the arguments sent to a :data:`m2m_changed` handler would be:
  206. ============== ============================================================
  207. Argument Value
  208. ============== ============================================================
  209. ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class)
  210. ``instance`` ``t`` (the ``Topping`` instance being modified)
  211. ``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)
  212. ``reverse`` ``True`` (``Pizza`` contains the :class:`ManyToManyField`,
  213. so this call modifies the reverse relation)
  214. ``model`` ``Pizza`` (the class of the objects removed from the
  215. ``Topping``)
  216. ``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the
  217. relation)
  218. ``using`` ``"default"`` (since the default router sends writes here)
  219. ============== ============================================================
  220. class_prepared
  221. --------------
  222. .. data:: django.db.models.signals.class_prepared
  223. :module:
  224. Sent whenever a model class has been "prepared" -- that is, once model has
  225. been defined and registered with Django's model system. Django uses this
  226. signal internally; it's not generally used in third-party applications.
  227. Arguments that are sent with this signal:
  228. ``sender``
  229. The model class which was just prepared.
  230. Management signals
  231. ==================
  232. Signals sent by :doc:`django-admin </ref/django-admin>`.
  233. post_syncdb
  234. -----------
  235. .. data:: django.db.models.signals.post_syncdb
  236. :module:
  237. Sent by :djadmin:`syncdb` after it installs an application.
  238. Any handlers that listen to this signal need to be written in a particular
  239. place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If
  240. handlers are registered anywhere else they may not be loaded by
  241. :djadmin:`syncdb`.
  242. Arguments sent with this signal:
  243. ``sender``
  244. The ``models`` module that was just installed. That is, if
  245. :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,
  246. ``sender`` will be the ``foo.bar.myapp.models`` module.
  247. ``app``
  248. Same as ``sender``.
  249. ``created_models``
  250. A list of the model classes from any app which :djadmin:`syncdb` has
  251. created so far.
  252. ``verbosity``
  253. Indicates how much information manage.py is printing on screen. See
  254. the :djadminopt:`--verbosity` flag for details.
  255. Functions which listen for :data:`post_syncdb` should adjust what they
  256. output to the screen based on the value of this argument.
  257. ``interactive``
  258. If ``interactive`` is ``True``, it's safe to prompt the user to input
  259. things on the command line. If ``interactive`` is ``False``, functions
  260. which listen for this signal should not try to prompt for anything.
  261. For example, the :mod:`django.contrib.auth` app only prompts to create a
  262. superuser when ``interactive`` is ``True``.
  263. For example, ``yourapp/management/__init__.py`` could be written like::
  264. from django.db.models.signals import post_syncdb
  265. import yourapp.models
  266. def my_callback(sender, **kwargs):
  267. # Your specific logic here
  268. pass
  269. post_syncdb.connect(my_callback, sender=yourapp.models)
  270. Request/response signals
  271. ========================
  272. .. module:: django.core.signals
  273. :synopsis: Core signals sent by the request/response system.
  274. Signals sent by the core framework when processing a request.
  275. request_started
  276. ---------------
  277. .. data:: django.core.signals.request_started
  278. :module:
  279. Sent when Django begins processing an HTTP request.
  280. Arguments sent with this signal:
  281. ``sender``
  282. The handler class -- e.g.
  283. :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled
  284. the request.
  285. request_finished
  286. ----------------
  287. .. data:: django.core.signals.request_finished
  288. :module:
  289. Sent when Django finishes processing an HTTP request.
  290. Arguments sent with this signal:
  291. ``sender``
  292. The handler class, as above.
  293. got_request_exception
  294. ---------------------
  295. .. data:: django.core.signals.got_request_exception
  296. :module:
  297. This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
  298. Arguments sent with this signal:
  299. ``sender``
  300. The handler class, as above.
  301. ``request``
  302. The :class:`~django.http.HttpRequest` object.
  303. Test signals
  304. ============
  305. .. module:: django.test.signals
  306. :synopsis: Signals sent during testing.
  307. Signals only sent when :doc:`running tests </topics/testing>`.
  308. template_rendered
  309. -----------------
  310. .. data:: django.test.signals.template_rendered
  311. :module:
  312. Sent when the test system renders a template. This signal is not emitted during
  313. normal operation of a Django server -- it is only available during testing.
  314. Arguments sent with this signal:
  315. ``sender``
  316. The :class:`~django.template.Template` object which was rendered.
  317. ``template``
  318. Same as sender
  319. ``context``
  320. The :class:`~django.template.Context` with which the template was
  321. rendered.
  322. Database Wrappers
  323. =================
  324. .. module:: django.db.backends
  325. :synopsis: Core signals sent by the database wrapper.
  326. Signals sent by the database wrapper when a database connection is
  327. initiated.
  328. connection_created
  329. ------------------
  330. .. data:: django.db.backends.signals.connection_created
  331. :module:
  332. .. versionchanged:: 1.2
  333. The connection argument was added
  334. Sent when the database wrapper makes the initial connection to the
  335. database. This is particularly useful if you'd like to send any post
  336. connection commands to the SQL backend.
  337. Arguments sent with this signal:
  338. ``sender``
  339. The database wrapper class -- i.e.
  340. :class:`django.db.backends.postgresql_psycopg2.DatabaseWrapper` or
  341. :class:`django.db.backends.mysql.DatabaseWrapper`, etc.
  342. ``connection``
  343. The database connection that was opened. This can be used in a
  344. multiple-database configuration to differentiate connection signals
  345. from different databases.