diff --git a/docs/api.rst b/docs/api.rst index 5ad17401..69ef38b5 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -508,36 +508,65 @@ Useful Internals .. autoclass:: flask.blueprints.BlueprintSetupState :members: +.. _core-signals-list: + Signals ------- -.. when modifying this list, also update the one in signals.rst - .. versionadded:: 0.6 -.. data:: signals_available +.. data:: signals.signals_available ``True`` if the signaling system is available. This is the case when `blinker`_ is installed. +The following signals exist in Flask: + .. data:: template_rendered 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:: request_started - This signal is sent before any request processing started but when the - request context was set up. Because the request context is already + 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:: request_finished 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:: got_request_exception 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 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 - This signal is sent when the application is tearing down the request. - This is always called, even if an error happened. An `exc` keyword - argument is passed with the exception that caused the teardown. + 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) - .. versionchanged:: 0.9 - The `exc` parameter was added. + 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 - This signal is sent when the application is tearing down the - application context. This is always called, even if an error happened. - An `exc` keyword argument is passed with the exception that caused the - teardown. The sender is the application. + 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:: appcontext_pushed 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 @@ -576,17 +656,25 @@ Signals .. versionadded:: 0.10 + .. data:: message_flashed This signal is sent when the application is flashing a message. The messages is sent as `message` keyword argument and the category as `category`. - .. versionadded:: 0.10 + Example subscriber:: -.. currentmodule:: None + recorded = [] + def record(sender, message, category, **extra): + recorded.append((message, category)) -.. class:: flask.signals.Namespace + from flask import message_flashed + message_flashed.connect(record, app) + + .. versionadded:: 0.10 + +.. class:: signals.Namespace An alias for :class:`blinker.base.Namespace` if blinker is available, 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 operations, including connecting. + .. _blinker: https://pypi.python.org/pypi/blinker + Class-Based Views ----------------- diff --git a/docs/signals.rst b/docs/signals.rst index ecb49d5f..b368194c 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -184,169 +184,7 @@ With Blinker 1.1 you can also easily subscribe to signals by using the new 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