diff options
Diffstat (limited to 'parts/django/docs/ref/signals.txt')
| -rw-r--r-- | parts/django/docs/ref/signals.txt | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/parts/django/docs/ref/signals.txt b/parts/django/docs/ref/signals.txt deleted file mode 100644 index 4bc1f3f..0000000 --- a/parts/django/docs/ref/signals.txt +++ /dev/null @@ -1,475 +0,0 @@ -======= -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>`. - -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: - -.. 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 created. - -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. - -m2m_changed ------------ - -.. data:: django.db.models.signals.m2m_changed - :module: - -.. versionadded:: 1.2 - -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 *after* 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``. - -For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled -like this: - -.. code-block:: python - - class Topping(models.Model): - # ... - - class Pizza(models.Model): - # ... - toppings = models.ManyToManyField(Topping) - -If we would do something like this: - -.. code-block:: python - - >>> p = Pizza.object.create(...) - >>> t = Topping.objects.create(...) - >>> p.toppings.add(t) - -the arguments sent to a :data:`m2m_changed` handler 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) - ============== ============================================================ - -And if we would then do something like this: - -.. code-block:: python - - >>> 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) - ============== ============================================================ - -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 :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 :doc:`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. - -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: - -.. versionadded:: 1.1 - -.. versionchanged:: 1.2 - The connection argument was added - -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. |