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

clean up FLASK_ENV docs [ci skip]

pull/2593/head
David Lord 7 years ago
parent
2949306b7b
commit
87c2e121e0
No known key found for this signature in database
GPG Key ID: 7A1C87E3F5BC42A8
7 changed files with 129 additions and 83 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. 35
      docs/cli.rst
  2. 84
      docs/config.rst
  3. 11
      docs/quickstart.rst
  4. 14
      docs/server.rst
  5. 4
      docs/tutorial/packaging.rst
  6. 43
      flask/app.py
  7. 21
      flask/helpers.py

35
docs/cli.rst
Unescape View File

@ -116,37 +116,42 @@ context will be active, and the app instance will be imported. ::
Use :meth:`~Flask.shell_context_processor` to add other automatic imports. Use :meth:`~Flask.shell_context_processor` to add other automatic imports.
Environments Environments
------------ ------------
.. versionadded:: 1.0 .. versionadded:: 1.0
The environment in which the Flask app should run is set by the The environment in which the Flask app runs is set by the
:envvar:`FLASK_ENV` environment variable. If not set it defaults to :envvar:`FLASK_ENV` environment variable. If not set it defaults to
``production``. The other default environment which is known is ``production``. The other recognized environment is ``development``.
``development``. If the env is set to ``development`` the debug mode is Flask and extensions may choose to enable behaviors based on the
for instance automatically enabled. environment.
Debug Mode If the env is set to ``development``, the ``flask`` command will enable
---------- debug mode and ``flask run`` will enable the interactive debugger and
reloader.
Set the :envvar:`FLASK_DEBUG` environment variable to override the
application's :attr:`~Flask.debug` flag. The value ``1`` enables it, ``0``
disables it. Forcing the debug flag on also enables the debugger and reloader
when running the development server.
:: ::
$ FLASK_DEBUG=1 flask run $ FLASK_ENV=development flask run
* Serving Flask app "hello" * Serving Flask app "hello"
* Forcing debug mode on * Environment: development
* Env production * Debug mode: on
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with inotify reloader * Restarting with inotify reloader
* Debugger is active! * Debugger is active!
* Debugger PIN: 223-456-919 * Debugger PIN: 223-456-919
Debug Mode
----------
Debug mode will be enabled when :envvar:`FLASK_ENV` is ``development``,
as described above. If you want to control debug mode separately, use
:envvar:`FLASK_DEBUG`. The value ``1`` enables it, ``0`` disables it.
.. _dotenv: .. _dotenv:
Environment Variables From dotenv Environment Variables From dotenv

84
docs/config.rst
Unescape View File

@ -20,6 +20,7 @@ object. This is the place where Flask itself puts certain configuration
values and also where extensions can put their configuration values. But values and also where extensions can put their configuration values. But
this is also where you can have your own configuration. this is also where you can have your own configuration.
Configuration Basics Configuration Basics
-------------------- --------------------
@ -42,52 +43,77 @@ method::
SECRET_KEY=b'_5#y2L"F4Q8z\n\xec]/' SECRET_KEY=b'_5#y2L"F4Q8z\n\xec]/'
) )
Environment and Debug Features Environment and Debug Features
------------------------------ ------------------------------
Some values are special in that they can show unexpected behavior when The :data:`ENV` and :data:`DEBUG` config values are special because they
changed late. In particular that applies to the Flask environment and may behave inconsistently if changed after the app has begun setting up.
debug mode. In order to set the environment and debug mode reliably, Flask uses
environment variables.
If you use the :command:`flask` script to start a local development server The environment is used to indicate to Flask, extensions, and other
for instance you should tell Flask that you want to work in the programs, like Sentry, what context Flask is running in. It is
development environment. For safety reasons we default the flask controlled with the :envvar:`FLASK_ENV` environment variable and
environment to production mode instead of development. This is done defaults to ``production``.
because development mode can turn on potentially unsafe features such as
the debugger by default.
To control the environment and such fundamental features Flask provides Setting :envvar:`FLASK_ENV` to ``development`` will enable debug mode.
the two environment variables :envvar:`FLASK_ENV` and :envvar:`FLASK_DEBUG`. ``flask run`` will use the interactive debugger and reloader by default
In versions of Flask older than 1.0 the :envvar:`FLASK_ENV` environment in debug mode. To control this separately from the environment, use the
variable did not exist. :envvar:`FLASK_DEBUG` flag.
.. versionchanged:: 1.0
Added :envvar:`FLASK_ENV` to control the environment separately
from debug mode. The development environment enables debug mode.
The most common way to switch Flask to development mode is to tell it to To switch Flask to the development environment and enable debug mode,
work on the ``development`` environment:: set :envvar:`FLASK_ENV`::
$ export FLASK_ENV=development $ export FLASK_ENV=development
$ flask run $ flask run
(On Windows you need to use ``set`` instead of ``export``). (On Windows, use ``set`` instead of ``export``.)
Using the environment variables as described above is recommended. While
it is possible to set :data:`ENV` and :data:`DEBUG` in your config or
code, this is strongly discouraged. They can't be read early by the
``flask`` command, and some systems or extensions may have already
configured themselves based on a previous value.
While you can attempt to flip the environment and debug flag separately in
the Flask config from the config file this is strongly discouraged as
those flags are often loaded early and changing them late might not apply
to all systems and extensions.
Builtin Configuration Values Builtin Configuration Values
---------------------------- ----------------------------
The following configuration values are used internally by Flask: The following configuration values are used internally by Flask:
.. py:data:: ENV
What environment the app is running in. Flask and extensions may
enable behaviors based on the environment, such as enabling debug
mode. The :attr:`~flask.Flask.env` attribute maps to this config
key. This is set by the :envvar:`FLASK_ENV` environment variable and
may not behave as expected if set in code.
**Do not enable development when deploying in production.**
Default: ``'production'``
.. versionadded:: 1.0
.. py:data:: DEBUG .. py:data:: DEBUG
Enable debug mode. When using the development server with ``flask run`` or Whether debug mode is enabled. When using ``flask run`` to start the
``app.run``, an interactive debugger will be shown for unhanlded development server, an interactive debugger will be shown for
exceptions, and the server will be reloaded when code changes. unhandled exceptions, and the server will be reloaded when code
changes. The :attr:`~flask.Flask.debug` attribute maps to this
config key. This is enabled when :data:`ENV` is ``'development'``
and is overridden by the ``FLASK_DEBUG`` environment variable. It
may not behave as expected if set in code.
**Do not enable debug mode in production.** **Do not enable debug mode when deploying in production.**
Default: ``False`` Default: ``True`` if :data:`ENV` is ``'production'``, or ``False``
otherwise.
.. py:data:: TESTING .. py:data:: TESTING
@ -339,6 +365,10 @@ The following configuration values are used internally by Flask:
``LOGGER_NAME`` and ``LOGGER_HANDLER_POLICY`` were removed. See ``LOGGER_NAME`` and ``LOGGER_HANDLER_POLICY`` were removed. See
:ref:`logging` for information about configuration. :ref:`logging` for information about configuration.
Added :data:`ENV` to reflect the :envvar:`FLASK_ENV` environment
variable.
Configuring from Files Configuring from Files
---------------------- ----------------------

11
docs/quickstart.rst
Unescape View File

@ -130,16 +130,14 @@ That is not very nice and Flask can do better. If you enable debug
support the server will reload itself on code changes, and it will also support the server will reload itself on code changes, and it will also
provide you with a helpful debugger if things go wrong. provide you with a helpful debugger if things go wrong.
To enable all development features (and to disable the debug mode) you can To enable all development features (including debug mode) you can export
export the ``FLASK_ENV`` environment variable and set it to the ``FLASK_ENV`` environment variable and set it to ``development``
``development``
before running the server:: before running the server::
$ export FLASK_ENV=development $ export FLASK_ENV=development
$ flask run $ flask run
(On Windows you need to use ``set`` instead of ``export`` and on Flask (On Windows you need to use ``set`` instead of ``export``.)
versions older than 1.0 you need to export ``FLASK_DEBUG=1`` instead).
This does the following things: This does the following things:
@ -147,6 +145,9 @@ This does the following things:
2. it activates the automatic reloader 2. it activates the automatic reloader
3. it enables the debug mode on the Flask application. 3. it enables the debug mode on the Flask application.
You can also control debug mode separately from the environment by
exporting ``FLASK_DEBUG=1``.
There are more parameters that are explained in the :ref:`server` docs. There are more parameters that are explained in the :ref:`server` docs.
.. admonition:: Attention .. admonition:: Attention

14
docs/server.rst
Unescape View File

@ -21,21 +21,23 @@ this::
$ export FLASK_ENV=development $ export FLASK_ENV=development
$ flask run $ flask run
This will enable the debugger, the reloader and then start the server on This enables the development environment, including the interactive
debugger and reloader, and then starts the server on
*http://localhost:5000/*. *http://localhost:5000/*.
The individual features of the server can be controlled by passing more The individual features of the server can be controlled by passing more
arguments to the ``run`` option. For instance the reloader can be arguments to the ``run`` option. For instance the reloader can be
disabled:: disabled::
$ flask run --no-reload $ flask run --no-reload
.. note:: .. note::
On older Flask version (before 1.0) the :envvar:`FLASK_ENV` Prior to Flask 1.0 the :envvar:`FLASK_ENV` environment variable was
environment variable is not supported and you need to enable the not supported and you needed to enable debug mode by exporting
debug mode separately by setting the :envvar:`FLASK_DEBUG` environment ``FLASK_DEBUG=1``. This can still be used to control debug mode, but
variable to ``1``. you should prefer setting the development environment as shown
above.
In Code In Code
------- -------

4
docs/tutorial/packaging.rst
Unescape View File

@ -82,8 +82,8 @@ Do this on Mac or Linux with the following commands in ``flaskr/``::
flask run flask run
(In case you are on Windows you need to use ``set`` instead of ``export``). (In case you are on Windows you need to use ``set`` instead of ``export``).
The :envvar:`FLASK_ENV` flag if set to ``development`` turns on all Exporting ``FLASK_ENV=development`` turns on all development features
development features such as enabling the interactive debugger. such as enabling the interactive debugger.
*Never leave debug mode activated in a production system*, because it will *Never leave debug mode activated in a production system*, because it will
allow users to execute code on the server! allow users to execute code on the server!

43
flask/app.py
Unescape View File

@ -785,36 +785,39 @@ class Flask(_PackageBoundObject):
rv.update(processor()) rv.update(processor())
return rv return rv
#: The environment value. This is typically set from outside the #: What environment the app is running in. Flask and extensions may
#: process by setting the `FLASK_ENV` environment variable and can be #: enable behaviors based on the environment, such as enabling debug
#: used to quickly switch between different environments like #: mode. This maps to the :data:`ENV` config key. This is set by the
#: `production` and `development`. If not set this defaults to #: :envvar:`FLASK_ENV` environment variable and may not behave as
#: `production`. #: expected if set in code.
#:
#: **Do not enable development when deploying in production.**
#:
#: Default: ``'production'``
env = ConfigAttribute('ENV') env = ConfigAttribute('ENV')
def _get_debug(self): def _get_debug(self):
return self.config['DEBUG'] return self.config['DEBUG']
def _set_debug(self, value): def _set_debug(self, value):
self._set_debug_value(value) self.config['DEBUG'] = value
self.jinja_env.auto_reload = self.templates_auto_reload
#: The debug flag. If this is ``True`` it enables debugging of the #: Whether debug mode is enabled. When using ``flask run`` to start
#: application. In debug mode the debugger will kick in when an #: the development server, an interactive debugger will be shown for
#: unhandled exception occurs and the integrated server will #: unhandled exceptions, and the server will be reloaded when code
#: automatically reload the application if changes in the code are #: changes. This maps to the :data:`DEBUG` config key. This is
#: detected. #: enabled when :attr:`env` is ``'development'`` and is overridden
#: by the ``FLASK_DEBUG`` environment variable. It may not behave as
#: expected if set in code.
#: #:
#: This value should only be configured by the :envvar:`FLASK_DEBUG` #: **Do not enable debug mode when deploying in production.**
#: environment variable. Changing it by other means will not yield #:
#: consistent results. The default value depends on the Flask #: Default: ``True`` if :attr:`env` is ``'development'``, or
#: environment and will be true for the development environment and false #: ``False`` otherwise.
#: otherwise.
debug = property(_get_debug, _set_debug) debug = property(_get_debug, _set_debug)
del _get_debug, _set_debug del _get_debug, _set_debug
def _set_debug_value(self, value):
self.config['DEBUG'] = value
self.jinja_env.auto_reload = self.templates_auto_reload
def run(self, host=None, port=None, debug=None, def run(self, host=None, port=None, debug=None,
load_dotenv=True, **options): load_dotenv=True, **options):
"""Runs the application on a local development server. """Runs the application on a local development server.

21
flask/helpers.py
Unescape View File

@ -47,19 +47,24 @@ _os_alt_seps = list(sep for sep in [os.path.sep, os.path.altsep]
def get_env(): def get_env():
val = os.environ.get('FLASK_ENV') """Get the environment the app is running in, indicated by the
if not val: :envvar:`FLASK_ENV` environment variable. The default is
val = 'production' ``'production'``.
return val """
return os.environ.get('FLASK_ENV') or 'production'
def get_debug_flag(): def get_debug_flag():
"""Get whether debug mode should be enabled for the app, indicated
by the :envvar:`FLASK_DEBUG` environment variable. The default is
``True`` if :func:`.get_env` returns ``'development'``, or ``False``
otherwise.
"""
val = os.environ.get('FLASK_DEBUG') val = os.environ.get('FLASK_DEBUG')
if not val: if not val:
env = get_env() return get_env() == 'development'
if env == 'development':
return True
return False
return val.lower() not in ('0', 'false', 'no') return val.lower() not in ('0', 'false', 'no')

Write Preview
Loading…
Cancel
Save