Source

hg-review / bundled / flask / docs / api.rst

API

This part of the documentation covers all the interfaces of Flask. For parts where Flask depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Application Object

Module Objects

Incoming Request Data

To access incoming request data, you can use the global request object. Flask parses incoming request data for you and gives you access to it through that global object. Internally Flask makes sure that you always get the correct data for the active thread if you are in a multithreaded environment.

This is a proxy. See :ref:`notes-on-proxies` for more information.

The request object is an instance of a :class:`~werkzeug.Request` subclass and provides all of the attributes Werkzeug defines. This just shows a quick overview of the most important ones.

Response Objects

Sessions

If you have the :attr:`Flask.secret_key` set you can use sessions in Flask applications. A session basically makes it possible to remember information from one request to another. The way Flask does this is by using a signed cookie. So the user can look at the session contents, but not modify it unless he knows the secret key, so make sure to set that to something complex and unguessable.

To access the current session you can use the :class:`session` object:

The session object works pretty much like an ordinary dict, with the difference that it keeps track on modifications.

This is a proxy. See :ref:`notes-on-proxies` for more information.

The following attributes are interesting:

Application Globals

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 threaded environments. Flask provides you with a special object that 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 thing, like it does for :class:`request` and :class:`session`.

Useful Functions and Classes

Message Flashing

Returning JSON

Template Rendering

Configuration

Useful Internals

Signals

An alias for :class:`blinker.base.Namespace` if blinker is available, otherwise a dummy class that creates fake signals. This class is available for Flask extensions that want to provide the same fallback system as Flask itself.

Notes On Proxies

Some of the objects provided by Flask are proxies to other objects. The reason behind this is that these proxies are shared between threads and they have to dispatch to the actual object bound to a thread behind the scenes as necessary.

Most of the time you don't have to care about that, but there are some exceptions where it is good to know that this object is an actual proxy:

  • The proxy objects do not fake their inherited types, so if you want to perform actual instance checks, you have to do that on the instance that is being proxied (see _get_current_object below).
  • if the object reference is important (so for example for sending :ref:`signals`)

If you need to get access to the underlying object that is proxied, you can use the :meth:`~werkzeug.LocalProxy._get_current_object` method:

app = current_app._get_current_object()
my_signal.send(app)