.. _api:
API (перевод на начальной стадии)
=================================
.. module:: flask
Эта часть документации содержит описание всех интерфейсов Flask. В тех
местах, где Flask зависит от внешних библиотек, мы документируем самое
важное прямо здесь, а также снабжаем вас ссылкой на оригинальную
документацию.
Объект приложения
-----------------
.. autoclass:: Flask
:members:
:inherited-members:
Объекты blueprint
-----------------
.. autoclass:: Blueprint
:members:
:inherited-members:
Данные входящих запросов
------------------------
.. autoclass:: Request
:members:
.. attribute:: form
:class:`~werkzeug.datastructures.MultiDict` с данными разбора от запросов
`POST` или `PUT`. Помните, пожалуйста, что загрузки файлов на этом не
ограничиваются, есть ещё атрибут :attr:`files`.
.. attribute:: args
:class:`~werkzeug.datastructures.MultiDict` с разобранным содержимым
строки запроса. (Это та часть URL, которая следует после знака вопроса).
.. attribute:: values
:class:`~werkzeug.datastructures.CombinedMultiDict` с содержимым
:attr:`form` и :attr:`args`.
.. attribute:: cookies
:class:`dict` с содержимым всех переменных браузера, переданных с
запросом.
.. attribute:: stream
Если поступающие данные формы не закодированы одним из известных
типов mimetype, потребляемые данные сохраняются в этом потоке в
неизменном виде. В большинстве случаев лучше использовать
:attr:`data`, который предоставит вам эти данные в виде строки.
Поток возвращает данные лишь единожды.
.. attribute:: headers
Заголовки поступившего запроса в виде словаря, как объекта.
.. attribute:: data
Содержит данные поступившего запроса в виде строки в том случае, когда
Flask не может обработать такой mimetype.
.. attribute:: files
:class:`~werkzeug.datastructures.MultiDict` с файлами, загружаемыми как часть
запроса `POST` или `PUT`. Каждый файл сохраняется в виде объекта
:class:`~werkzeug.datastructures.FileStorage`. Он, говоря простым языком,
ведёт себя как известный вам по Python объект файла, с той разницей, что
в нём есть функция :meth:`~werkzeug.datastructures.FileStorage.save`, которая
может сохранить файл в файловую систему..
.. attribute:: environ
Нижележащее WSGI-окружение.
.. attribute:: method
Текущий метод запроса (``POST``, ``GET`` и т. д.)
.. attribute:: path
.. attribute:: script_root
.. attribute:: url
.. attribute:: base_url
.. attribute:: url_root
Предоставляет различные способы представления текущего URL. Представим, что
ваше приложение соответствует следующему URL::
http://www.example.com/myapplication
А запросы пользователя поступают на такой URL::
http://www.example.com/myapplication/page.html?x=y
В таком случае значения вышеупомянутых атрибутов станут вот такими:
============= ======================================================
`path` ``/page.html``
`script_root` ``/myapplication``
`base_url` ``http://www.example.com/myapplication/page.html``
`url` ``http://www.example.com/myapplication/page.html?x=y``
`url_root` ``http://www.example.com/myapplication/``
============= ======================================================
.. attribute:: is_xhr
`True` если запрос обработан через JavaScript `XMLHttpRequest`.
Это работает лишь с теми библиотеками, которые поддерживают
заголовок ``X-Requested-With`` и устанавливают его в значение
`XMLHttpRequest`. Подобными библиотеками являются prototype,
jQuery и Mochikit, возможно какие-то ещё.
.. class:: request
Чтобы получить доступ к данным поступившего запроса, вы можете
использовать глобальный объект `request`. Flask занимается для вас
разбором данных поступившего запроса и предоставляет вам к ним доступ
через глобальный объект. Внутри себя Flask хочет убедиться, что
в случае многопоточного окружения, вы всегда получите корректные
данные, адресованные активному потоку.
Это прокси. За дополнительными сведениями обращайтесь к
:ref:`notes-on-proxies`.
Объект запроса это экземпляр подкласса
:class:`~werkzeug.wrappers.Request`, сопровождаемый всеми атрибутами,
которые определены в Werkzeug. Здесь дан лишь краткий обзор
наиболее важных из них.
Объекты ответа
--------------
.. autoclass:: flask.Response
:members: set_cookie, data, mimetype
.. attribute:: headers
Объект :class:`Headers`, представляющий заголовки ответа.
.. attribute:: status
Строка со статусом ответа.
.. attribute:: status_code
Статус ответа в виде целого числа.
Сессии
------
Если вы установили :attr:`Flask.secret_key` вы можете использовать сессии во
Flask приложении. Сессия в основном используется для того, что бы запоминать
информацию между запросами. Во Flask это реализовано при помощи подписанных
cookies. Таким образом, пользователь может посмотреть на содержимое сессии, но
не может изменить его пока он не знает секретный ключ, поэтому убедитесь, что
ключ сложный и неопределяемый.
Для доступа к текущей сессии вы можете использовать объект :class:`session`:
.. class:: session
Объект сессии работает почти как обычный словарь, с той разницей, что он
следит за изменениями.
Это прокси. За дополнительными сведениями обращайтесь к
:ref:`notes-on-proxies`.
Следующие атрибуты интресны:
.. attribute:: new
`True` если сессия новая, в ином случае - `False`.
.. attribute:: modified
`True` если объект сессии был изменен. Имейте ввиду, что изменения
изменяемых структур данных не отмечаются автоматически, в этой ситуации
вы должны явно установить значение атрибута в `True` самостоятельно.
Вот пример::
# это изменение не будет отмечено из-за изменения изменяемого объекта
# (это тип `list` - список).
session['objects'].append(42)
# так что укажем это самостоятельно
session.modified = True
.. attribute:: permanent
Если установлен в `True` то сессия будет жить
:attr:`~flask.Flask.permanent_session_lifetime` секунд. По умолчанию 31
день. Если установлен в `False` (по умолчанию), сессия будет удалена как
только пользователь закроет окно браузера.
Интерфейс сессий
----------------
.. versionadded:: 0.8
Итерфейс сессий предоставляет простой способ замены имплементации сессий Flask.
.. currentmodule:: flask.sessions
.. autoclass:: SessionInterface
:members:
.. autoclass:: SecureCookieSessionInterface
:members:
.. autoclass:: SecureCookieSession
:members:
.. autoclass:: NullSession
:members:
.. autoclass:: SessionMixin
:members:
.. autodata:: session_json_serializer
Этот объект предоставляет методы сериализации и десериализации похожие на
simplejson, но так же конвертирует некоторые встроенные объекты Python,
которые обычно появляются в сессиях. На данный момент следующие расширенные
значения поддерживаются в JSON при дампе:
- :class:`~markupsafe.Markup` объекты
- :class:`~uuid.UUID` объекты
- :class:`~datetime.datetime` объекты
- :class:`tuple`\ы
.. admonition:: Замечание
Ключ конфигурации ``PERMANENT_SESSION_LIFETIME`` может так же быть числом
начиная с версии Flask 0.8. Вы можете использовать атрибут
:attr:`~flask.Flask.permanent_session_lifetime` в приложении с автоматической
конвертацией результата в число.
Тестовый клиент
---------------
.. currentmodule:: flask.testing
.. autoclass:: FlaskClient
:members:
Глобальные переменные
---------------------
.. currentmodule:: flask
Для совместного использования данных, которые действительны в течение одного
запроса и только от одной функции к другой, глобальная переменная не достаточно
хороша, потому что она нарушила бы работу приложения в многопоточных средах.
Flask предоставляет специальный объект, который гарантирует что для разных
запросов будут возвращены разные значения. В двух словах: это работает примерно
так же как и :class:`request` и :class:`session`.
.. data:: g
Просто храните здесь все что хотите. Например соединение с базой данных или
пользователя, который сейчас авторизирован.
Начиная с Flask 0.10 это хранится в контексте приложения и не зависит от
контекста запроса, что делает их доступными уже в момент создани контекста
приложения, но еще до создания запроса. Это особенно полезно когда
используется подход :ref:`faking-resources` для тестирования.
Дополнительно с версии 0.10 вы можете использовать метод :meth:`get` для
получения значения атрибута или `None` (или второго аргумента метода
:meth:`get`) если значение отсутствует. Эти две строки эквивалентны::
user = getattr(flask.g, 'user', None)
user = flask.g.get('user', None)
Так же допускается использование оператора ``in`` на этом объекте для
проверки на существование ключа в объекте.
Это прокси. За дополнительными сведениями обращайтесь к
:ref:`notes-on-proxies`.
Полезные функции и классы
-------------------------
.. data:: current_app
Приложение в текущем запросе. Это используется для расширений,
которые хотят поддерживать несколько приложений работающих бок о бок.
Это работает на основе контекста приложения а не на контексте запроса, так
что вы можете изменить значение этого прокси используя метод
:meth:`~flask.Flask.app_context`.
Это прокси. За дополнительными сведениями обращайтесь к
:ref:`notes-on-proxies`.
.. autofunction:: has_request_context
.. autofunction:: copy_current_request_context
.. autofunction:: has_app_context
.. autofunction:: url_for
.. function:: abort(code)
Вызывает исключение :exc:`~werkzeug.exceptions.HTTPException` для переданного
кода ответа. Например для отмены запроса и ответа со статусом 404 - страница
не найдена, вы можете вызвать ``abort(404)``.
:param code: код ответа HTTP.
.. autofunction:: redirect
.. autofunction:: make_response
.. autofunction:: after_this_request
.. autofunction:: send_file
.. autofunction:: send_from_directory
.. autofunction:: safe_join
.. autofunction:: escape
.. autoclass:: Markup
:members: escape, unescape, striptags
Передача сообщений
------------------
.. autofunction:: flash
.. autofunction:: get_flashed_messages
Поддержка JSON
--------------
.. module:: flask.json
Flask использует ``simplejson`` в качестве JSON имплементации. Flask будет
пытаться использовать библиотеку simplejson, и в случае если ее нет - будет
использовать стандартный JSON модуль. Поверх этого предоставляется доступ к JSON
сериализаторам и десериализаторам текущего приложения для облегчения расширения.
Для начала попробуем следующее::
try:
import simplejson as json
except ImportError:
import json
Вместо этого можно просто сделать так::
from flask import json
В качестве примера использования прочитайте документацию к :mod:`json` в
стандартной библиотеке. Следующие расширения по умолчанию добавлены в
стандартный JSON модуль:
1. ``datetime`` объекты, которые могут быть сериализированы в строки
:rfc:`822`.
2. Любые объекты, имеющие метод ``__html__`` (такие как :class:`~flask.Markup`
). Будет вызван метод ``__html__`` и возвращаемое значение будет
представлено как строка.
Функция :func:`~htmlsafe_dumps` этого json модуля также доступна через вызов
фильтра ``|tojson`` в Jinja2. Заметьте, что внутри `script` тегов данные
экранируются, так что убедитесь, что вы отключили экранирование с ``|safe`` если
вы хотите исопльзовать внутри `script` теги:
.. sourcecode:: html+jinja
.. admonition:: Автосортировка ключей JSON
Переменная конфигурации ``JSON_SORT_KEYS`` (:ref:`config`) может быть
установлена в false для предотвращения автосортировки ключей в Flask. По
умолчанию сортировка включена и вне контекста приложения сортировка так же
включена.
Заметьте, что отключение сортировки ключей может вызвать проблемы при
кэшировании результата.
.. autofunction:: jsonify
.. autofunction:: dumps
.. autofunction:: dump
.. autofunction:: loads
.. autofunction:: load
.. autoclass:: JSONEncoder
:members:
.. autoclass:: JSONDecoder
:members:
Отрисовка шаблонов
------------------
.. currentmodule:: flask
.. autofunction:: render_template
.. autofunction:: render_template_string
.. autofunction:: get_template_attribute
Конфигурация
------------
.. autoclass:: Config
:members:
Расширения
----------
.. data:: flask.ext
Этот модуль отвечает за перенаправление импорта к расширениям Flask. Он был
добавлен в версии 0.8 как канонический путь для импорта расширений Flask и
дает нам возможность создавать расширяемые и распространяемые дополнения.
Если вы хотите использовать расширение с именем “Flask-Foo” вы должны
импортировать его из :data:`~flask.ext` как указано::
from flask.ext import foo
.. versionadded:: 0.8
Потоки
------
.. autofunction:: stream_with_context
Внутренние дополнения
---------------------
.. autoclass:: flask.ctx.RequestContext
:members:
.. data:: _request_ctx_stack
Внутренний класс :class:`~werkzeug.local.LocalStack` используется для
имплементации всех локальных контекстных объектов используемых в Flask. Это
документированный инстанс и может быть использован в коде расширений или
приложений но использовать его не рекомендуется.
Следующие атрибуты всегда доступны на каждом слое стэка:
`app`
активное приложение Flask.
`url_adapter`
URL адптер который использвется для поиска соответствий запроса.
`request`
текущий объект запроса.
`session`
активный объект сессии.
`g`
объект со всеми атрибутами объекта :data:`flask.g`.
`flashes`
внутренний кэш для флеш сообщений.
Пример использования::
from flask import _request_ctx_stack
def get_session():
ctx = _request_ctx_stack.top
if ctx is not None:
return ctx.session
.. autoclass:: flask.ctx.AppContext
:members:
.. data:: _app_ctx_stack
Работает аналогично контексту запроса только привязан к приложению.
Используется в основном расширениями для хранения данных.
.. versionadded:: 0.9
.. autoclass:: flask.blueprints.BlueprintSetupState
:members:
Сигналы
-------
.. when modifying this list, also update the one in signals.rst
.. versionadded:: 0.6
.. data:: signals_available
`True` if the signaling system is available. This is the case
when `blinker`_ is installed.
.. 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`).
.. 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
bound, the subscriber can access the request with the standard global
proxies such as :class:`~flask.request`.
.. 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`.
.. data:: got_request_exception
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`.
.. 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.
.. versionchanged:: 0.9
The `exc` parameter was added.
.. 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.
.. data:: appcontext_pushed
This signal is sent when an application context is pushed. The sender
is the application.
.. versionadded:: 0.10
.. data:: appcontext_popped
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:: 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
.. currentmodule:: None
.. class:: flask.signals.Namespace
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.
.. method:: signal(name, doc=None)
Creates a new signal for this namespace if blinker is available,
otherwise returns a fake signal that has a send method that will
do nothing but will fail with a :exc:`RuntimeError` for all other
operations, including connecting.
.. _blinker: http://pypi.python.org/pypi/blinker
Class-Based Views
-----------------
.. versionadded:: 0.7
.. currentmodule:: None
.. autoclass:: flask.views.View
:members:
.. autoclass:: flask.views.MethodView
:members:
.. _url-route-registrations:
URL Route Registrations
-----------------------
Generally there are three ways to define rules for the routing system:
1. You can use the :meth:`flask.Flask.route` decorator.
2. You can use the :meth:`flask.Flask.add_url_rule` function.
3. You can directly access the underlying Werkzeug routing system
which is exposed as :attr:`flask.Flask.url_map`.
Variable parts in the route can be specified with angular brackets
(``/user/``). By default a variable part in the URL accepts any
string without a slash however a different converter can be specified as
well by using ````.
Variable parts are passed to the view function as keyword arguments.
The following converters are available:
=========== ===============================================
`string` accepts any text without a slash (the default)
`int` accepts integers
`float` like `int` but for floating point values
`path` like the default but also accepts slashes
=========== ===============================================
Here are some examples::
@app.route('/')
def index():
pass
@app.route('/')
def show_user(username):
pass
@app.route('/post/')
def show_post(post_id):
pass
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
apply:
1. If a rule ends with a slash and is requested without a slash by the
user, the user is automatically redirected to the same page with a
trailing slash attached.
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.
This is consistent with how web servers deal with static files. This
also makes it possible to use relative link targets safely.
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
definition for a URL that accepts an optional page::
@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/')
def show_users(page):
pass
This specifies that ``/users/`` will be the URL for page one and
``/users/page/N`` will be the URL for page `N`.
Here are the parameters that :meth:`~flask.Flask.route` and
:meth:`~flask.Flask.add_url_rule` accept. The only difference is that
with the route parameter the view function is defined with the decorator
instead of the `view_func` parameter.
=============== ==========================================================
`rule` the URL rule as string
`endpoint` the endpoint for the registered URL rule. Flask itself
assumes that the name of the view function is the name
of the endpoint if not explicitly stated.
`view_func` the function to call when serving a request to the
provided endpoint. If this is not provided one can
specify the function later by storing it in the
:attr:`~flask.Flask.view_functions` dictionary with the
endpoint as key.
`defaults` A dictionary with defaults for this rule. See the
example above for how defaults work.
`subdomain` specifies the rule for the subdomain in case subdomain
matching is in use. If not specified the default
subdomain is assumed.
`**options` the options to be forwarded to the underlying
:class:`~werkzeug.routing.Rule` object. A change to
Werkzeug is handling of method options. methods is a list
of methods this rule should be limited to (`GET`, `POST`
etc.). By default a rule just listens for `GET` (and
implicitly `HEAD`). Starting with Flask 0.6, `OPTIONS` is
implicitly added and handled by the standard request
handling. They have to be specified as keyword arguments.
=============== ==========================================================
.. _view-func-options:
View Function Options
---------------------
For internal usage the view functions can have some attributes attached to
customize behavior the view function would normally not have control over.
The following attributes can be provided optionally to either override
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
endpoint is provided explicitly this value is used. Additionally this
will be prefixed with the name of the blueprint by default which
cannot be customized from the function itself.
- `methods`: If methods are not provided when the URL rule is added,
Flask will look on the view function object itself is an `methods`
attribute exists. If it does, it will pull the information for the
methods from there.
- `provide_automatic_options`: if this attribute is set Flask will
either force enable or disable the automatic implementation of the
HTTP `OPTIONS` response. This can be useful when working with
decorators that want to customize the `OPTIONS` response on a per-view
basis.
- `required_methods`: if this attribute is set, Flask will always add
these methods when registering a URL rule even if the methods were
explicitly overridden in the ``route()`` call.
Full example::
def index():
if request.method == 'OPTIONS':
# custom options handling here
...
return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']
app.add_url_rule('/', index)
.. versionadded:: 0.8
The `provide_automatic_options` functionality was added.
`Оригинал этой страницы `_