forked from orbit-oss/flask
Fixed inconsistent double spacing in docs/api.rst
This commit is contained in:
parent
e7c82f9c47
commit
5dfd2126a6
1 changed files with 45 additions and 45 deletions
90
docs/api.rst
90
docs/api.rst
|
|
@ -3,7 +3,7 @@ API
|
||||||
|
|
||||||
.. module:: flask
|
.. module:: flask
|
||||||
|
|
||||||
This part of the documentation covers all the interfaces of Flask. For
|
This part of the documentation covers all the interfaces of Flask. For
|
||||||
parts where Flask depends on external libraries, we document the most
|
parts where Flask depends on external libraries, we document the most
|
||||||
important right here and provide links to the canonical documentation.
|
important right here and provide links to the canonical documentation.
|
||||||
|
|
||||||
|
|
@ -34,12 +34,12 @@ Incoming Request Data
|
||||||
.. attribute:: request
|
.. attribute:: request
|
||||||
|
|
||||||
To access incoming request data, you can use the global `request`
|
To access incoming request data, you can use the global `request`
|
||||||
object. Flask parses incoming request data for you and gives you
|
object. Flask parses incoming request data for you and gives you
|
||||||
access to it through that global object. Internally Flask makes
|
access to it through that global object. Internally Flask makes
|
||||||
sure that you always get the correct data for the active thread if you
|
sure that you always get the correct data for the active thread if you
|
||||||
are in a multithreaded environment.
|
are in a multithreaded environment.
|
||||||
|
|
||||||
This is a proxy. See :ref:`notes-on-proxies` for more information.
|
This is a proxy. See :ref:`notes-on-proxies` for more information.
|
||||||
|
|
||||||
The request object is an instance of a :class:`~flask.Request`.
|
The request object is an instance of a :class:`~flask.Request`.
|
||||||
|
|
||||||
|
|
@ -69,7 +69,7 @@ To access the current session you can use the :class:`session` object:
|
||||||
The session object works pretty much like an ordinary dict, with the
|
The session object works pretty much like an ordinary dict, with the
|
||||||
difference that it keeps track of modifications.
|
difference that it keeps track of modifications.
|
||||||
|
|
||||||
This is a proxy. See :ref:`notes-on-proxies` for more information.
|
This is a proxy. See :ref:`notes-on-proxies` for more information.
|
||||||
|
|
||||||
The following attributes are interesting:
|
The following attributes are interesting:
|
||||||
|
|
||||||
|
|
@ -79,10 +79,10 @@ To access the current session you can use the :class:`session` object:
|
||||||
|
|
||||||
.. attribute:: modified
|
.. attribute:: modified
|
||||||
|
|
||||||
``True`` if the session object detected a modification. Be advised
|
``True`` if the session object detected a modification. Be advised
|
||||||
that modifications on mutable structures are not picked up
|
that modifications on mutable structures are not picked up
|
||||||
automatically, in that situation you have to explicitly set the
|
automatically, in that situation you have to explicitly set the
|
||||||
attribute to ``True`` yourself. Here an example::
|
attribute to ``True`` yourself. Here an example::
|
||||||
|
|
||||||
# this change is not picked up because a mutable object (here
|
# this change is not picked up because a mutable object (here
|
||||||
# a list) is changed.
|
# a list) is changed.
|
||||||
|
|
@ -93,8 +93,8 @@ To access the current session you can use the :class:`session` object:
|
||||||
.. attribute:: permanent
|
.. attribute:: permanent
|
||||||
|
|
||||||
If set to ``True`` the session lives for
|
If set to ``True`` the session lives for
|
||||||
:attr:`~flask.Flask.permanent_session_lifetime` seconds. The
|
:attr:`~flask.Flask.permanent_session_lifetime` seconds. The
|
||||||
default is 31 days. If set to ``False`` (which is the default) the
|
default is 31 days. If set to ``False`` (which is the default) the
|
||||||
session will be deleted when the user closes the browser.
|
session will be deleted when the user closes the browser.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -155,9 +155,9 @@ Application Globals
|
||||||
|
|
||||||
To share data that is valid for one request only from one function to
|
To share data that is valid for one request only from one function to
|
||||||
another, a global variable is not good enough because it would break in
|
another, a global variable is not good enough because it would break in
|
||||||
threaded environments. Flask provides you with a special object that
|
threaded environments. Flask provides you with a special object that
|
||||||
ensures it is only valid for the active request and that will return
|
ensures it is only valid for the active request and that will return
|
||||||
different values for each request. In a nutshell: it does the right
|
different values for each request. In a nutshell: it does the right
|
||||||
thing, like it does for :class:`request` and :class:`session`.
|
thing, like it does for :class:`request` and :class:`session`.
|
||||||
|
|
||||||
.. data:: g
|
.. data:: g
|
||||||
|
|
@ -347,14 +347,14 @@ Signals
|
||||||
|
|
||||||
.. data:: signals.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:
|
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`).
|
||||||
|
|
||||||
|
|
@ -388,7 +388,7 @@ The following signals exist in Flask:
|
||||||
.. data:: request_started
|
.. data:: request_started
|
||||||
|
|
||||||
This signal is sent when the request context is set up, before
|
This signal is sent when the request context is set up, before
|
||||||
any request processing happens. 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`.
|
||||||
|
|
||||||
|
|
@ -408,7 +408,7 @@ The following signals exist in Flask:
|
||||||
Example subscriber::
|
Example subscriber::
|
||||||
|
|
||||||
def log_response(sender, response, **extra):
|
def log_response(sender, response, **extra):
|
||||||
sender.logger.debug('Request context is about to close down. '
|
sender.logger.debug('Request context is about to close down. '
|
||||||
'Response: %s', response)
|
'Response: %s', response)
|
||||||
|
|
||||||
from flask import request_finished
|
from flask import request_finished
|
||||||
|
|
@ -445,8 +445,8 @@ The following signals exist in Flask:
|
||||||
|
|
||||||
.. data:: request_tearing_down
|
.. data:: request_tearing_down
|
||||||
|
|
||||||
This signal is sent when the request is tearing down. This is always
|
This signal is sent when the request is tearing down. This is always
|
||||||
called, even if an exception is caused. Currently functions listening
|
called, even if an exception is caused. Currently functions listening
|
||||||
to this signal are called after the regular teardown handlers, but this
|
to this signal are called after the regular teardown handlers, but this
|
||||||
is not something you can rely on.
|
is not something you can rely on.
|
||||||
|
|
||||||
|
|
@ -464,8 +464,8 @@ The following signals exist in Flask:
|
||||||
|
|
||||||
.. data:: appcontext_tearing_down
|
.. data:: appcontext_tearing_down
|
||||||
|
|
||||||
This signal is sent when the app context is tearing down. This is always
|
This signal is sent when the app context is tearing down. This is always
|
||||||
called, even if an exception is caused. Currently functions listening
|
called, even if an exception is caused. Currently functions listening
|
||||||
to this signal are called after the regular teardown handlers, but this
|
to this signal are called after the regular teardown handlers, but this
|
||||||
is not something you can rely on.
|
is not something you can rely on.
|
||||||
|
|
||||||
|
|
@ -482,9 +482,9 @@ The following signals exist in Flask:
|
||||||
|
|
||||||
.. 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. This is usually useful for unittests in order to
|
is the application. This is usually useful for unittests in order to
|
||||||
temporarily hook in information. For instance it can be used to
|
temporarily hook in information. For instance it can be used to
|
||||||
set a resource early onto the `g` object.
|
set a resource early onto the `g` object.
|
||||||
|
|
||||||
Example usage::
|
Example usage::
|
||||||
|
|
@ -511,8 +511,8 @@ The following signals exist in Flask:
|
||||||
|
|
||||||
.. data:: appcontext_popped
|
.. data:: appcontext_popped
|
||||||
|
|
||||||
This signal is sent when an application context is popped. The sender
|
This signal is sent when an application context is popped. The sender
|
||||||
is the application. This usually falls in line with the
|
is the application. This usually falls in line with the
|
||||||
:data:`appcontext_tearing_down` signal.
|
:data:`appcontext_tearing_down` signal.
|
||||||
|
|
||||||
.. versionadded:: 0.10
|
.. versionadded:: 0.10
|
||||||
|
|
@ -520,7 +520,7 @@ The following signals exist in Flask:
|
||||||
|
|
||||||
.. 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`.
|
||||||
|
|
||||||
|
|
@ -538,7 +538,7 @@ The following signals exist in Flask:
|
||||||
.. class:: signals.Namespace
|
.. class:: 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
|
||||||
available for Flask extensions that want to provide the same fallback
|
available for Flask extensions that want to provide the same fallback
|
||||||
system as Flask itself.
|
system as Flask itself.
|
||||||
|
|
||||||
|
|
@ -579,7 +579,7 @@ Generally there are three ways to define rules for the routing system:
|
||||||
which is exposed as :attr:`flask.Flask.url_map`.
|
which is exposed as :attr:`flask.Flask.url_map`.
|
||||||
|
|
||||||
Variable parts in the route can be specified with angular brackets
|
Variable parts in the route can be specified with angular brackets
|
||||||
(``/user/<username>``). By default a variable part in the URL accepts any
|
(``/user/<username>``). By default a variable part in the URL accepts any
|
||||||
string without a slash however a different converter can be specified as
|
string without a slash however a different converter can be specified as
|
||||||
well by using ``<converter:name>``.
|
well by using ``<converter:name>``.
|
||||||
|
|
||||||
|
|
@ -613,7 +613,7 @@ Here are some examples::
|
||||||
pass
|
pass
|
||||||
|
|
||||||
An important detail to keep in mind is how Flask deals with trailing
|
An important detail to keep in mind is how Flask deals with trailing
|
||||||
slashes. The idea is to keep each URL unique so the following rules
|
slashes. The idea is to keep each URL unique so the following rules
|
||||||
apply:
|
apply:
|
||||||
|
|
||||||
1. If a rule ends with a slash and is requested without a slash by the
|
1. If a rule ends with a slash and is requested without a slash by the
|
||||||
|
|
@ -622,11 +622,11 @@ apply:
|
||||||
2. If a rule does not end with a trailing slash and the user requests the
|
2. If a rule does not end with a trailing slash and the user requests the
|
||||||
page with a trailing slash, a 404 not found is raised.
|
page with a trailing slash, a 404 not found is raised.
|
||||||
|
|
||||||
This is consistent with how web servers deal with static files. This
|
This is consistent with how web servers deal with static files. This
|
||||||
also makes it possible to use relative link targets safely.
|
also makes it possible to use relative link targets safely.
|
||||||
|
|
||||||
You can also define multiple rules for the same function. They have to be
|
You can also define multiple rules for the same function. They have to be
|
||||||
unique however. Defaults can also be specified. Here for example is a
|
unique however. Defaults can also be specified. Here for example is a
|
||||||
definition for a URL that accepts an optional page::
|
definition for a URL that accepts an optional page::
|
||||||
|
|
||||||
@app.route('/users/', defaults={'page': 1})
|
@app.route('/users/', defaults={'page': 1})
|
||||||
|
|
@ -649,33 +649,33 @@ can't preserve form data. ::
|
||||||
pass
|
pass
|
||||||
|
|
||||||
Here are the parameters that :meth:`~flask.Flask.route` and
|
Here are the parameters that :meth:`~flask.Flask.route` and
|
||||||
:meth:`~flask.Flask.add_url_rule` accept. The only difference is that
|
:meth:`~flask.Flask.add_url_rule` accept. The only difference is that
|
||||||
with the route parameter the view function is defined with the decorator
|
with the route parameter the view function is defined with the decorator
|
||||||
instead of the `view_func` parameter.
|
instead of the `view_func` parameter.
|
||||||
|
|
||||||
=============== ==========================================================
|
=============== ==========================================================
|
||||||
`rule` the URL rule as string
|
`rule` the URL rule as string
|
||||||
`endpoint` the endpoint for the registered URL rule. Flask itself
|
`endpoint` the endpoint for the registered URL rule. Flask itself
|
||||||
assumes that the name of the view function is the name
|
assumes that the name of the view function is the name
|
||||||
of the endpoint if not explicitly stated.
|
of the endpoint if not explicitly stated.
|
||||||
`view_func` the function to call when serving a request to the
|
`view_func` the function to call when serving a request to the
|
||||||
provided endpoint. If this is not provided one can
|
provided endpoint. If this is not provided one can
|
||||||
specify the function later by storing it in the
|
specify the function later by storing it in the
|
||||||
:attr:`~flask.Flask.view_functions` dictionary with the
|
:attr:`~flask.Flask.view_functions` dictionary with the
|
||||||
endpoint as key.
|
endpoint as key.
|
||||||
`defaults` A dictionary with defaults for this rule. See the
|
`defaults` A dictionary with defaults for this rule. See the
|
||||||
example above for how defaults work.
|
example above for how defaults work.
|
||||||
`subdomain` specifies the rule for the subdomain in case subdomain
|
`subdomain` specifies the rule for the subdomain in case subdomain
|
||||||
matching is in use. If not specified the default
|
matching is in use. If not specified the default
|
||||||
subdomain is assumed.
|
subdomain is assumed.
|
||||||
`**options` the options to be forwarded to the underlying
|
`**options` the options to be forwarded to the underlying
|
||||||
:class:`~werkzeug.routing.Rule` object. A change to
|
:class:`~werkzeug.routing.Rule` object. A change to
|
||||||
Werkzeug is handling of method options. methods is a list
|
Werkzeug is handling of method options. methods is a list
|
||||||
of methods this rule should be limited to (``GET``, ``POST``
|
of methods this rule should be limited to (``GET``, ``POST``
|
||||||
etc.). By default a rule just listens for ``GET`` (and
|
etc.). By default a rule just listens for ``GET`` (and
|
||||||
implicitly ``HEAD``). Starting with Flask 0.6, ``OPTIONS`` is
|
implicitly ``HEAD``). Starting with Flask 0.6, ``OPTIONS`` is
|
||||||
implicitly added and handled by the standard request
|
implicitly added and handled by the standard request
|
||||||
handling. They have to be specified as keyword arguments.
|
handling. They have to be specified as keyword arguments.
|
||||||
=============== ==========================================================
|
=============== ==========================================================
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -687,19 +687,19 @@ customize behavior the view function would normally not have control over.
|
||||||
The following attributes can be provided optionally to either override
|
The following attributes can be provided optionally to either override
|
||||||
some defaults to :meth:`~flask.Flask.add_url_rule` or general behavior:
|
some defaults to :meth:`~flask.Flask.add_url_rule` or general behavior:
|
||||||
|
|
||||||
- `__name__`: The name of a function is by default used as endpoint. If
|
- `__name__`: The name of a function is by default used as endpoint. If
|
||||||
endpoint is provided explicitly this value is used. Additionally this
|
endpoint is provided explicitly this value is used. Additionally this
|
||||||
will be prefixed with the name of the blueprint by default which
|
will be prefixed with the name of the blueprint by default which
|
||||||
cannot be customized from the function itself.
|
cannot be customized from the function itself.
|
||||||
|
|
||||||
- `methods`: If methods are not provided when the URL rule is added,
|
- `methods`: If methods are not provided when the URL rule is added,
|
||||||
Flask will look on the view function object itself if a `methods`
|
Flask will look on the view function object itself if a `methods`
|
||||||
attribute exists. If it does, it will pull the information for the
|
attribute exists. If it does, it will pull the information for the
|
||||||
methods from there.
|
methods from there.
|
||||||
|
|
||||||
- `provide_automatic_options`: if this attribute is set Flask will
|
- `provide_automatic_options`: if this attribute is set Flask will
|
||||||
either force enable or disable the automatic implementation of the
|
either force enable or disable the automatic implementation of the
|
||||||
HTTP ``OPTIONS`` response. This can be useful when working with
|
HTTP ``OPTIONS`` response. This can be useful when working with
|
||||||
decorators that want to customize the ``OPTIONS`` response on a per-view
|
decorators that want to customize the ``OPTIONS`` response on a per-view
|
||||||
basis.
|
basis.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue