Fixed inconsistent double spacing in docs/api.rst

This commit is contained in:
Mat Steininger 2022-10-15 18:34:37 -04:00 committed by Grey Li
parent e7c82f9c47
commit 5dfd2126a6

View file

@ -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.