playground
/
flask
mirror of https://github.com/mitsuhiko/flask.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

reformat config from table to linkable sections

pull/2344/head
David Lord 8 years ago
parent
399ac3c54f
commit
60feecc26c
No known key found for this signature in database
GPG Key ID: 7A1C87E3F5BC42A8
1 changed files with 240 additions and 171 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 405
      docs/config.rst

405
docs/config.rst
Unescape View File

@ -3,8 +3,6 @@
Configuration Handling Configuration Handling
====================== ======================
.. versionadded:: 0.3
Applications need some kind of configuration. There are different settings Applications need some kind of configuration. There are different settings
you might want to change depending on the application environment like you might want to change depending on the application environment like
toggling the debug mode, setting the secret key, and other such toggling the debug mode, setting the secret key, and other such
@ -64,172 +62,242 @@ Builtin Configuration Values
The following configuration values are used internally by Flask: The following configuration values are used internally by Flask:
.. tabularcolumns:: |p{6.5cm}|p{8.5cm}| .. py:data:: DEBUG
================================= ========================================= Enable debug mode. When using the development server with ``flask run`` or
``DEBUG`` enable/disable debug mode when using ``app.run``, an interactive debugger will be shown for unhanlded
``Flask.run()`` method to start server exceptions, and the server will be reloaded when code changes.
``TESTING`` enable/disable testing mode
``PROPAGATE_EXCEPTIONS`` explicitly enable or disable the **Do not enable debug mode in production.**
propagation of exceptions. If not set or
explicitly set to ``None`` this is Default: ``False``
implicitly true if either ``TESTING`` or
``DEBUG`` is true. .. py:data:: TESTING
``PRESERVE_CONTEXT_ON_EXCEPTION`` By default if the application is in
debug mode the request context is not Enable testing mode. Exceptions are propagated rather than handled by the
popped on exceptions to enable debuggers the app's error handlers. Extensions may also change their behavior to
to introspect the data. This can be facilitate easier testing. You should enable this in your own tests.
disabled by this key. You can also use
this setting to force-enable it for non Default: ``False``
debug execution which might be useful to
debug production applications (but also .. py:data:: PROPAGATE_EXCEPTIONS
very risky).
``SECRET_KEY`` the secret key Exceptions are re-raised rather than being handled by the app's error
``SESSION_COOKIE_NAME`` the name of the session cookie handlers. If not set, this is implicitly true if ``TESTING`` or ``DEBUG``
``SESSION_COOKIE_DOMAIN`` the domain for the session cookie. If is enabled.
this is not set, the cookie will be
valid for all subdomains of Default: ``None``
``SERVER_NAME``.
``SESSION_COOKIE_PATH`` the path for the session cookie. If .. py:data:: PRESERVE_CONTEXT_ON_EXCEPTION
this is not set the cookie will be valid
for all of ``APPLICATION_ROOT`` or if Don't pop the request context when an exception occurs. If not set, this
that is not set for ``'/'``. is true if ``DEBUG`` is true. This allows debuggers to introspect the
``SESSION_COOKIE_HTTPONLY`` controls if the cookie should be set request data on errors, and should normally not need to be set directly.
with the httponly flag. Defaults to
``True``. Default: ``None``
``SESSION_COOKIE_SECURE`` controls if the cookie should be set
with the secure flag. Defaults to .. py:data:: TRAP_HTTP_EXCEPTIONS
``False``.
``PERMANENT_SESSION_LIFETIME`` the lifetime of a permanent session as If there is no handler for an ``HTTPException``-type exception, re-raise it
:class:`datetime.timedelta` object. to be handled by the interactive debugger instead of returning it as a
Starting with Flask 0.8 this can also be simple error response.
an integer representing seconds.
``SESSION_REFRESH_EACH_REQUEST`` this flag controls how permanent Default: ``False``
sessions are refreshed. If set to ``True``
(which is the default) then the cookie .. py:data:: TRAP_BAD_REQUEST_ERRORS``
is refreshed each request which
automatically bumps the lifetime. If Trying to access a key that doesn't exist from request dicts like ``args``
set to ``False`` a `set-cookie` header is and ``form`` will return a 400 Bad Request error page. Enable this to treat
only sent if the session is modified. the error as an unhandled exception instead so that you get the interactive
Non permanent sessions are not affected debugger. This is a more specific version of ``TRAP_HTTP_EXCEPTIONS``.
by this.
``USE_X_SENDFILE`` enable/disable x-sendfile Default: ``False``
``LOGGER_NAME`` the name of the logger
``LOGGER_HANDLER_POLICY`` the policy of the default logging .. py:data:: SECRET_KEY
handler. The default is ``'always'``
which means that the default logging A secret key that will be used for securely signing the session cookie
handler is always active. ``'debug'`` and can be used for any other security related needs by extensions or your
will only activate logging in debug application. It should be a long random string of bytes, although unicode
mode, ``'production'`` will only log in is accepted too. For example, copy the output of this to your config::
production and ``'never'`` disables it
entirely. python -c 'import os; print(os.urandom(32))'
``SERVER_NAME`` the name and port number of the server.
Required for subdomain support (e.g.: **Do not reveal the secret key when posting questions or committing code.**
``'myapp.dev:5000'``) Note that
localhost does not support subdomains so Default: ``None``
setting this to “localhost” does not
help. Setting a ``SERVER_NAME`` also .. py:data:: SESSION_COOKIE_NAME
by default enables URL generation
without a request context but with an The name of the session cookie. Can be changed in case you already have a
application context. cookie with the same name.
``APPLICATION_ROOT`` The path value used for the session
cookie if ``SESSION_COOKIE_PATH`` isn't Default: ``'session'``
set. If it's also ``None`` ``'/'`` is used.
Note that to actually serve your Flask .. py:data:: SESSION_COOKIE_DOMAIN
app under a subpath you need to tell
your WSGI container the ``SCRIPT_NAME`` The domain match rule that the session cookie will be valid for. If not
WSGI environment variable. set, the cookie will be valid for all subdomains of ``SERVER_NAME``. If
``MAX_CONTENT_LENGTH`` If set to a value in bytes, Flask will ``False``, the cookie's domain will not be set.
reject incoming requests with a
content length greater than this by Default: ``None``
returning a 413 status code.
``SEND_FILE_MAX_AGE_DEFAULT`` Default cache control max age to use with .. py:data:: SESSION_COOKIE_PATH
:meth:`~flask.Flask.send_static_file` (the
default static file handler) and The path that the session cookie will be valid for. If not set, the cookie
:func:`~flask.send_file`, as will be valid underneath ``APPLICATION_ROOT`` or ``/`` if that is not set.
:class:`datetime.timedelta` or as seconds.
Override this value on a per-file Default: ``None``
basis using the
:meth:`~flask.Flask.get_send_file_max_age` .. py:data:: SESSION_COOKIE_HTTPONLY
hook on :class:`~flask.Flask` or
:class:`~flask.Blueprint`, Browsers will not allow JavaScript access to cookies marked as "HTTP only"
respectively. Defaults to 43200 (12 hours). for security.
``TRAP_HTTP_EXCEPTIONS`` If this is set to ``True`` Flask will
not execute the error handlers of HTTP Default: ``True``
exceptions but instead treat the
exception like any other and bubble it .. py:data:: SESSION_COOKIE_SECURE
through the exception stack. This is
helpful for hairy debugging situations Browsers will only send cookies with requests over HTTPS if the cookie is
where you have to find out where an HTTP marked "secure". The application must be served over HTTPS for this to make
exception is coming from. sense.
``TRAP_BAD_REQUEST_ERRORS`` Werkzeug's internal data structures that
deal with request specific data will Default: ``False``
raise special key errors that are also
bad request exceptions. Likewise many .. py:data:: SESSION_COOKIE_LIFETIME
operations can implicitly fail with a
BadRequest exception for consistency. If ``session.permanent`` is true, the cookie's max age will be set to this
Since it's nice for debugging to know number of seconds. Can either be a :class:`datetime.timedelta` or an
why exactly it failed this flag can be ``int``.
used to debug those situations. If this
config is set to ``True`` you will get Default: ``timedelta(days=31)`` (``2678400`` seconds)
a regular traceback instead.
``PREFERRED_URL_SCHEME`` The URL scheme that should be used for .. py:data:: SESSION_REFRESH_EACH_REQUEST
URL generation if no URL scheme is
available. This defaults to ``http``. Control whether the cookie is sent with every response when
``JSON_AS_ASCII`` By default Flask serialize object to ``session.permanent`` is true. Sending the cookie every time (the default)
ascii-encoded JSON. If this is set to can more reliably keep the session from expiring, but uses more bandwidth.
``False`` Flask will not encode to ASCII Non-permanent sessions are not affected.
and output strings as-is and return
unicode strings. ``jsonify`` will Default: ``True``
automatically encode it in ``utf-8``
then for transport for instance. .. py:data:: USE_X_SENDFILE
``JSON_SORT_KEYS`` By default Flask will serialize JSON
objects in a way that the keys are When serving files, set the ``X-Sendfile`` header instead of serving the
ordered. This is done in order to data with Flask. Some web servers, such as Apache, recognize this and serve
ensure that independent of the hash seed the data more efficiently. This only makes sense when using such a server.
of the dictionary the return value will
be consistent to not trash external HTTP Default: ``False``
caches. You can override the default
behavior by changing this variable. .. py:data:: SEND_FILE_MAX_AGE
This is not recommended but might give
you a performance improvement on the When serving files, set the cache control max age to this number of
cost of cacheability. seconds. Can either be a :class:`datetime.timedelta` or an ``int``.
``JSONIFY_PRETTYPRINT_REGULAR`` If this is set to ``True`` or the Flask app Override this value on a per-file basis using
is running in debug mode, jsonify responses :meth:`~flask.Flask.get_send_file_max_age` on the application or blueprint.
will be pretty printed.
``JSONIFY_MIMETYPE`` MIME type used for jsonify responses. Default: ``timedelta(hours=12)`` (``43200`` seconds)
``TEMPLATES_AUTO_RELOAD`` Whether to check for modifications of
the template source and reload it .. py:data:: LOGGER_NAME
automatically. By default the value is
``None`` which means that Flask checks The name of the logger that the Flask application sets up. If not set,
original file only in debug mode. it will take the import name passed to ``Flask.__init__``.
``EXPLAIN_TEMPLATE_LOADING`` If this is enabled then every attempt to
load a template will write an info Default: ``None``
message to the logger explaining the
attempts to locate the template. This .. py:data:: LOGGER_HANDLER_POLICY
can be useful to figure out why
templates cannot be found or wrong When to activate the application's logger handler. ``'always'`` always
templates appear to be loaded. enables it, ``'debug'`` only activates it in debug mode, ``'production'``
================================= ========================================= only activates it when not in debug mode, and ``'never'`` never enables it.
.. admonition:: More on ``SERVER_NAME`` Default: ``'always'``
The ``SERVER_NAME`` key is used for the subdomain support. Because .. py:data:: SERVER_NAME
Flask cannot guess the subdomain part without the knowledge of the
actual server name, this is required if you want to work with Inform the application what host and port it is bound to. Required for
subdomains. This is also used for the session cookie. subdomain route matching support.
Please keep in mind that not only Flask has the problem of not knowing If set, will be used for the session cookie domain if
what subdomains are, your web browser does as well. Most modern web ``SESSION_COOKIE_DOMAIN`` is not set. Modern web browsers will not allow
browsers will not allow cross-subdomain cookies to be set on a setting cookies for domains without a dot. To use a domain locally,
server name without dots in it. So if your server name is add any names that should route to the app to your ``hosts`` file. ::
``'localhost'`` you will not be able to set a cookie for
``'localhost'`` and every subdomain of it. Please choose a different 127.0.0.1 localhost.dev
server name in that case, like ``'myapplication.local'`` and add
this name + the subdomains you want to use into your host config If set, ``url_for`` can generate external URLs with only an application
or setup a local `bind`_. context instead of a request context.
.. _bind: https://www.isc.org/downloads/bind/ Default: ``None``
.. py:data:: APPLICATION_ROOT
Inform the application what path it is mounted under by the application /
web server.
Will be used for the session cookie path if ``SESSION_COOKIE_PATH`` is not
set.
Default: ``'/'``
.. py:data:: PREFERRED_URL_SCHEME
Use this scheme for generating external URLs when not in a request context.
Default: ``'http'``
.. py:data:: MAX_CONTENT_LENGTH
Don't read more than this many bytes from the incoming request data. If not
set and the request does not specify a ``CONTENT_LENGTH``, no data will be
read for security.
Default: ``None``
.. py:data:: JSON_AS_ASCII
Serialize objects to ASCII-encoded JSON. If this is disabled, the JSON
will be returned as a Unicode string, or encoded as ``UTF-8`` by
``jsonify``. This has security implications when rendering the JSON in
to JavaScript in templates, and should typically remain enabled.
Default: ``True``
.. py:data:: JSON_SORT_KEYS
Sort the keys of JSON objects alphabetically. This is useful for caching
because it ensures the data is serialized the same way no matter what
Python's hash seed is. While not recommended, you can disable this for a
possible performance improvement at the cost of caching.
Default: ``True``
.. py:data:: JSONIFY_PRETTYPRINT_REGULAR
``jsonify`` responses will be output with newlines, spaces, and indentation
for easier reading by humans. Always enabled in debug mode.
Default: ``False``
.. py:data:: JSONIFY_MIMETYPE
The mimetype of ``jsonify`` responses.
Default: ``'application/json'``
.. py:data:: TEMPLATES_AUTO_RELOAD
Reload templates when they are changed. If not set, it will be enabled in
debug mode.
Default: ``None``
.. py:data:: EXPLAIN_TEMPLATE_LOADING
Log debugging information tracing how a template file was loaded. This can
be useful to figure out why a template was not loaded or the wrong file
appears to be loaded.
Default: ``False``
.. versionadded:: 0.4 .. versionadded:: 0.4
``LOGGER_NAME`` ``LOGGER_NAME``
@ -477,3 +545,4 @@ Example usage for both::
# or via open_instance_resource: # or via open_instance_resource:
with app.open_instance_resource('application.cfg') as f: with app.open_instance_resource('application.cfg') as f:
config = f.read() config = f.read()

Write Preview
Loading…
Cancel
Save