maya-chen/flask
1
0
Fork 0
forked from orbit-oss/flask
Code Pull requests Activity

Deduplicate signals docs

Browse source 
Triggered by #1390
This commit is contained in:
Markus Unterwaditzer 2015-06-10 18:37:07 +02:00
parent 3e07b9c287
commit beec47a7cc
2 changed files with 109 additions and 181 deletions
Download patch file Download diff file Expand all files Collapse all files

126
docs/api.rst
View file

@ -508,36 +508,65 @@ Useful Internals
.. autoclass:: flask.blueprints.BlueprintSetupState .. autoclass:: flask.blueprints.BlueprintSetupState
:members: :members:
.. _core-signals-list:
Signals Signals
------- -------
.. when modifying this list, also update the one in signals.rst
.. versionadded:: 0.6 .. versionadded:: 0.6
.. data:: signals_available .. data:: signals.signals_available
``True`` if the signaling system is available. This is the case ``True`` if the signaling system is available. This is the case
when `blinker`_ is installed. when `blinker`_ is installed.
The following signals exist in Flask:
.. data:: template_rendered .. data:: template_rendered
This signal is sent when a template was successfully rendered. The This signal is sent when a template was successfully rendered. The
signal is invoked with the instance of the template as `template` signal is invoked with the instance of the template as `template`
and the context as dictionary (named `context`). and the context as dictionary (named `context`).
Example subscriber::
def log_template_renders(sender, template, context, **extra):
sender.logger.debug('Rendering template "%s" with context %s',
template.name or 'string template',
context)
from flask import template_rendered
template_rendered.connect(log_template_renders, app)
.. data:: request_started .. data:: request_started
This signal is sent before any request processing started but when the This signal is sent when the request context is set up, before
request context was set up. Because the request context is already any request processing happens. Because the request context is already
bound, the subscriber can access the request with the standard global bound, the subscriber can access the request with the standard global
proxies such as :class:`~flask.request`. proxies such as :class:`~flask.request`.
Example subscriber::
def log_request(sender, **extra):
sender.logger.debug('Request context is set up')
from flask import request_started
request_started.connect(log_request, app)
.. data:: request_finished .. data:: request_finished
This signal is sent right before the response is sent to the client. This signal is sent right before the response is sent to the client.
It is passed the response to be sent named `response`. It is passed the response to be sent named `response`.
Example subscriber::
def log_response(sender, response, **extra):
sender.logger.debug('Request context is about to close down. '
'Response: %s', response)
from flask import request_finished
request_finished.connect(log_response, app)
.. data:: got_request_exception .. data:: got_request_exception
This signal is sent when an exception happens during request processing. This signal is sent when an exception happens during request processing.
@ -545,26 +574,77 @@ Signals
in debug mode, where no exception handling happens. The exception in debug mode, where no exception handling happens. The exception
itself is passed to the subscriber as `exception`. itself is passed to the subscriber as `exception`.
Example subscriber::
def log_exception(sender, exception, **extra):
sender.logger.debug('Got exception during processing: %s', exception)
from flask import got_request_exception
got_request_exception.connect(log_exception, app)
.. data:: request_tearing_down .. data:: request_tearing_down
This signal is sent when the application is tearing down the request. This signal is sent when the request is tearing down. This is always
This is always called, even if an error happened. An `exc` keyword called, even if an exception is caused. Currently functions listening
argument is passed with the exception that caused the teardown. to this signal are called after the regular teardown handlers, but this
is not something you can rely on.
.. versionchanged:: 0.9 Example subscriber::
The `exc` parameter was added.
def close_db_connection(sender, **extra):
session.close()
from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)
As of Flask 0.9, this will also be passed an `exc` keyword argument
that has a reference to the exception that caused the teardown if
there was one.
.. data:: appcontext_tearing_down .. data:: appcontext_tearing_down
This signal is sent when the application is tearing down the This signal is sent when the app context is tearing down. This is always
application context. This is always called, even if an error happened. called, even if an exception is caused. Currently functions listening
An `exc` keyword argument is passed with the exception that caused the to this signal are called after the regular teardown handlers, but this
teardown. The sender is the application. is not something you can rely on.
Example subscriber::
def close_db_connection(sender, **extra):
session.close()
from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)
This will also be passed an `exc` keyword argument that has a reference
to the exception that caused the teardown if there was one.
.. data:: appcontext_pushed .. data:: appcontext_pushed
This signal is sent when an application context is pushed. The sender This signal is sent when an application context is pushed. The sender
is the application. is the application. This is usually useful for unittests in order to
temporarily hook in information. For instance it can be used to
set a resource early onto the `g` object.
Example usage::
from contextlib import contextmanager
from flask import appcontext_pushed
@contextmanager
def user_set(app, user):
def handler(sender, **kwargs):
g.user = user
with appcontext_pushed.connected_to(handler, app):
yield
And in the testcode::
def test_user_me(self):
with user_set(app, 'john'):
c = app.test_client()
resp = c.get('/users/me')
assert resp.data == 'username=john'
.. versionadded:: 0.10 .. versionadded:: 0.10
@ -576,17 +656,25 @@ Signals
.. versionadded:: 0.10 .. versionadded:: 0.10
.. data:: message_flashed .. data:: message_flashed
This signal is sent when the application is flashing a message. The This signal is sent when the application is flashing a message. The
messages is sent as `message` keyword argument and the category as messages is sent as `message` keyword argument and the category as
`category`. `category`.
Example subscriber::
recorded = []
def record(sender, message, category, **extra):
recorded.append((message, category))
from flask import message_flashed
message_flashed.connect(record, app)
.. versionadded:: 0.10 .. versionadded:: 0.10
.. currentmodule:: None .. class:: signals.Namespace
.. class:: flask.signals.Namespace
An alias for :class:`blinker.base.Namespace` if blinker is available, An alias for :class:`blinker.base.Namespace` if blinker is available,
otherwise a dummy class that creates fake signals. This class is otherwise a dummy class that creates fake signals. This class is
@ -600,8 +688,10 @@ Signals
do nothing but will fail with a :exc:`RuntimeError` for all other do nothing but will fail with a :exc:`RuntimeError` for all other
operations, including connecting. operations, including connecting.
.. _blinker: https://pypi.python.org/pypi/blinker .. _blinker: https://pypi.python.org/pypi/blinker
Class-Based Views Class-Based Views
----------------- -----------------

164
docs/signals.rst
View file

@ -184,169 +184,7 @@ With Blinker 1.1 you can also easily subscribe to signals by using the new
Core Signals Core Signals
------------ ------------
.. when modifying this list, also update the one in api.rst Take a look at :ref:`core-signals-list` for a list of all builtin signals.
The following signals exist in Flask:
.. data:: flask.template_rendered
:noindex:
This signal is sent when a template was successfully rendered. The
signal is invoked with the instance of the template as `template`
and the context as dictionary (named `context`).
Example subscriber::
def log_template_renders(sender, template, context, **extra):
sender.logger.debug('Rendering template "%s" with context %s',
template.name or 'string template',
context)
from flask import template_rendered
template_rendered.connect(log_template_renders, app)
.. data:: flask.request_started
:noindex:
This signal is sent when the request context is set up, before
any request processing happens. Because the request context is already
bound, the subscriber can access the request with the standard global
proxies such as :class:`~flask.request`.
Example subscriber::
def log_request(sender, **extra):
sender.logger.debug('Request context is set up')
from flask import request_started
request_started.connect(log_request, app)
.. data:: flask.request_finished
:noindex:
This signal is sent right before the response is sent to the client.
It is passed the response to be sent named `response`.
Example subscriber::
def log_response(sender, response, **extra):
sender.logger.debug('Request context is about to close down. '
'Response: %s', response)
from flask import request_finished
request_finished.connect(log_response, app)
.. data:: flask.got_request_exception
:noindex:
This signal is sent when an exception happens during request processing.
It is sent *before* the standard exception handling kicks in and even
in debug mode, where no exception handling happens. The exception
itself is passed to the subscriber as `exception`.
Example subscriber::
def log_exception(sender, exception, **extra):
sender.logger.debug('Got exception during processing: %s', exception)
from flask import got_request_exception
got_request_exception.connect(log_exception, app)
.. data:: flask.request_tearing_down
:noindex:
This signal is sent when the request is tearing down. This is always
called, even if an exception is caused. Currently functions listening
to this signal are called after the regular teardown handlers, but this
is not something you can rely on.
Example subscriber::
def close_db_connection(sender, **extra):
session.close()
from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)
As of Flask 0.9, this will also be passed an `exc` keyword argument
that has a reference to the exception that caused the teardown if
there was one.
.. data:: flask.appcontext_tearing_down
:noindex:
This signal is sent when the app context is tearing down. This is always
called, even if an exception is caused. Currently functions listening
to this signal are called after the regular teardown handlers, but this
is not something you can rely on.
Example subscriber::
def close_db_connection(sender, **extra):
session.close()
from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)
This will also be passed an `exc` keyword argument that has a reference
to the exception that caused the teardown if there was one.
.. data:: flask.appcontext_pushed
:noindex:
This signal is sent when an application context is pushed. The sender
is the application. This is usually useful for unittests in order to
temporarily hook in information. For instance it can be used to
set a resource early onto the `g` object.
Example usage::
from contextlib import contextmanager
from flask import appcontext_pushed
@contextmanager
def user_set(app, user):
def handler(sender, **kwargs):
g.user = user
with appcontext_pushed.connected_to(handler, app):
yield
And in the testcode::
def test_user_me(self):
with user_set(app, 'john'):
c = app.test_client()
resp = c.get('/users/me')
assert resp.data == 'username=john'
.. versionadded:: 0.10
.. data:: flask.appcontext_popped
:noindex:
This signal is sent when an application context is popped. The sender
is the application. This usually falls in line with the
:data:`appcontext_tearing_down` signal.
.. versionadded:: 0.10
.. data:: flask.message_flashed
:noindex:
This signal is sent when the application is flashing a message. The
messages is sent as `message` keyword argument and the category as
`category`.
Example subscriber::
recorded = []
def record(sender, message, category, **extra):
recorded.append((message, category))
from flask import message_flashed
message_flashed.connect(record, app)
.. versionadded:: 0.10
.. _blinker: https://pypi.python.org/pypi/blinker .. _blinker: https://pypi.python.org/pypi/blinker