clean up FLASK_ENV docs [ci skip]
This commit is contained in:
David Lord
parent
2949306b7b
commit
87c2e121e0
7 changed files with 131 additions and 85 deletions
35
docs/cli.rst
35
docs/cli.rst
|
|
@ -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.
|
||||
|
||||
|
||||
Environments
|
||||
------------
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
The environment in which the Flask app should run is set by the
|
||||
:envvar:`FLASK_ENV` environment variable. If not set it defaults to
|
||||
``production``. The other default environment which is known is
|
||||
``development``. If the env is set to ``development`` the debug mode is
|
||||
for instance automatically enabled.
|
||||
The environment in which the Flask app runs is set by the
|
||||
:envvar:`FLASK_ENV` environment variable. If not set it defaults to
|
||||
``production``. The other recognized environment is ``development``.
|
||||
Flask and extensions may choose to enable behaviors based on the
|
||||
environment.
|
||||
|
||||
Debug Mode
|
||||
----------
|
||||
|
||||
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.
|
||||
If the env is set to ``development``, the ``flask`` command will enable
|
||||
debug mode and ``flask run`` will enable the interactive debugger and
|
||||
reloader.
|
||||
|
||||
::
|
||||
|
||||
$ FLASK_DEBUG=1 flask run
|
||||
$ FLASK_ENV=development flask run
|
||||
* Serving Flask app "hello"
|
||||
* Forcing debug mode on
|
||||
* Env production
|
||||
* Environment: development
|
||||
* Debug mode: on
|
||||
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
|
||||
* Restarting with inotify reloader
|
||||
* Debugger is active!
|
||||
* 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:
|
||||
|
||||
Environment Variables From dotenv
|
||||
|
|
|
|||
|
|
@ -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
|
||||
this is also where you can have your own configuration.
|
||||
|
||||
|
||||
Configuration Basics
|
||||
--------------------
|
||||
|
||||
|
|
@ -42,52 +43,77 @@ method::
|
|||
SECRET_KEY=b'_5#y2L"F4Q8z\n\xec]/'
|
||||
)
|
||||
|
||||
|
||||
Environment and Debug Features
|
||||
------------------------------
|
||||
|
||||
Some values are special in that they can show unexpected behavior when
|
||||
changed late. In particular that applies to the Flask environment and
|
||||
debug mode.
|
||||
The :data:`ENV` and :data:`DEBUG` config values are special because they
|
||||
may behave inconsistently if changed after the app has begun setting up.
|
||||
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
|
||||
for instance you should tell Flask that you want to work in the
|
||||
development environment. For safety reasons we default the flask
|
||||
environment to production mode instead of development. This is done
|
||||
because development mode can turn on potentially unsafe features such as
|
||||
the debugger by default.
|
||||
The environment is used to indicate to Flask, extensions, and other
|
||||
programs, like Sentry, what context Flask is running in. It is
|
||||
controlled with the :envvar:`FLASK_ENV` environment variable and
|
||||
defaults to ``production``.
|
||||
|
||||
To control the environment and such fundamental features Flask provides
|
||||
the two environment variables :envvar:`FLASK_ENV` and :envvar:`FLASK_DEBUG`.
|
||||
In versions of Flask older than 1.0 the :envvar:`FLASK_ENV` environment
|
||||
variable did not exist.
|
||||
Setting :envvar:`FLASK_ENV` to ``development`` will enable debug mode.
|
||||
``flask run`` will use the interactive debugger and reloader by default
|
||||
in debug mode. To control this separately from the environment, use the
|
||||
:envvar:`FLASK_DEBUG` flag.
|
||||
|
||||
The most common way to switch Flask to development mode is to tell it to
|
||||
work on the ``development`` environment::
|
||||
.. versionchanged:: 1.0
|
||||
Added :envvar:`FLASK_ENV` to control the environment separately
|
||||
from debug mode. The development environment enables debug mode.
|
||||
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run
|
||||
To switch Flask to the development environment and enable debug mode,
|
||||
set :envvar:`FLASK_ENV`::
|
||||
|
||||
(On Windows you need to use ``set`` instead of ``export``).
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run
|
||||
|
||||
(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
|
||||
----------------------------
|
||||
|
||||
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
|
||||
|
||||
Enable debug mode. When using the development server with ``flask run`` or
|
||||
``app.run``, an interactive debugger will be shown for unhanlded
|
||||
exceptions, and the server will be reloaded when code changes.
|
||||
Whether debug mode is enabled. When using ``flask run`` to start the
|
||||
development server, an interactive debugger will be shown for
|
||||
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
|
||||
|
||||
|
|
@ -339,6 +365,10 @@ The following configuration values are used internally by Flask:
|
|||
``LOGGER_NAME`` and ``LOGGER_HANDLER_POLICY`` were removed. See
|
||||
:ref:`logging` for information about configuration.
|
||||
|
||||
Added :data:`ENV` to reflect the :envvar:`FLASK_ENV` environment
|
||||
variable.
|
||||
|
||||
|
||||
Configuring from Files
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
provide you with a helpful debugger if things go wrong.
|
||||
|
||||
To enable all development features (and to disable the debug mode) you can
|
||||
export the ``FLASK_ENV`` environment variable and set it to
|
||||
``development``
|
||||
To enable all development features (including debug mode) you can export
|
||||
the ``FLASK_ENV`` environment variable and set it to ``development``
|
||||
before running the server::
|
||||
|
||||
$ export FLASK_ENV=development
|
||||
$ flask run
|
||||
|
||||
(On Windows you need to use ``set`` instead of ``export`` and on Flask
|
||||
versions older than 1.0 you need to export ``FLASK_DEBUG=1`` instead).
|
||||
(On Windows you need to use ``set`` instead of ``export``.)
|
||||
|
||||
This does the following things:
|
||||
|
||||
|
|
@ -147,6 +145,9 @@ This does the following things:
|
|||
2. it activates the automatic reloader
|
||||
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.
|
||||
|
||||
.. admonition:: Attention
|
||||
|
|
|
|||
|
|
@ -21,21 +21,23 @@ this::
|
|||
$ export FLASK_ENV=development
|
||||
$ 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/*.
|
||||
|
||||
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::
|
||||
|
||||
$ flask run --no-reload
|
||||
|
||||
.. note::
|
||||
|
||||
On older Flask version (before 1.0) the :envvar:`FLASK_ENV`
|
||||
environment variable is not supported and you need to enable the
|
||||
debug mode separately by setting the :envvar:`FLASK_DEBUG` environment
|
||||
variable to ``1``.
|
||||
Prior to Flask 1.0 the :envvar:`FLASK_ENV` environment variable was
|
||||
not supported and you needed to enable debug mode by exporting
|
||||
``FLASK_DEBUG=1``. This can still be used to control debug mode, but
|
||||
you should prefer setting the development environment as shown
|
||||
above.
|
||||
|
||||
In Code
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -82,8 +82,8 @@ Do this on Mac or Linux with the following commands in ``flaskr/``::
|
|||
flask run
|
||||
|
||||
(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
|
||||
development features such as enabling the interactive debugger.
|
||||
Exporting ``FLASK_ENV=development`` turns on all development features
|
||||
such as enabling the interactive debugger.
|
||||
|
||||
*Never leave debug mode activated in a production system*, because it will
|
||||
allow users to execute code on the server!
|
||||
|
|
|
|||
47
flask/app.py
47
flask/app.py
|
|
@ -785,36 +785,39 @@ class Flask(_PackageBoundObject):
|
|||
rv.update(processor())
|
||||
return rv
|
||||
|
||||
#: The environment value. This is typically set from outside the
|
||||
#: process by setting the `FLASK_ENV` environment variable and can be
|
||||
#: used to quickly switch between different environments like
|
||||
#: `production` and `development`. If not set this defaults to
|
||||
#: `production`.
|
||||
#: What environment the app is running in. Flask and extensions may
|
||||
#: enable behaviors based on the environment, such as enabling debug
|
||||
#: mode. This maps to the :data:`ENV` 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'``
|
||||
env = ConfigAttribute('ENV')
|
||||
|
||||
def _get_debug(self):
|
||||
return self.config['DEBUG']
|
||||
|
||||
def _set_debug(self, value):
|
||||
self._set_debug_value(value)
|
||||
|
||||
#: The debug flag. If this is ``True`` it enables debugging of the
|
||||
#: application. In debug mode the debugger will kick in when an
|
||||
#: unhandled exception occurs and the integrated server will
|
||||
#: automatically reload the application if changes in the code are
|
||||
#: detected.
|
||||
#:
|
||||
#: This value should only be configured by the :envvar:`FLASK_DEBUG`
|
||||
#: environment variable. Changing it by other means will not yield
|
||||
#: consistent results. The default value depends on the Flask
|
||||
#: environment and will be true for the development environment and false
|
||||
#: otherwise.
|
||||
debug = property(_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
|
||||
|
||||
#: Whether debug mode is enabled. When using ``flask run`` to start
|
||||
#: the development server, an interactive debugger will be shown for
|
||||
#: unhandled exceptions, and the server will be reloaded when code
|
||||
#: changes. This maps to the :data:`DEBUG` config key. This is
|
||||
#: 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.
|
||||
#:
|
||||
#: **Do not enable debug mode when deploying in production.**
|
||||
#:
|
||||
#: Default: ``True`` if :attr:`env` is ``'development'``, or
|
||||
#: ``False`` otherwise.
|
||||
debug = property(_get_debug, _set_debug)
|
||||
del _get_debug, _set_debug
|
||||
|
||||
def run(self, host=None, port=None, debug=None,
|
||||
load_dotenv=True, **options):
|
||||
"""Runs the application on a local development server.
|
||||
|
|
|
|||
|
|
@ -47,19 +47,24 @@ _os_alt_seps = list(sep for sep in [os.path.sep, os.path.altsep]
|
|||
|
||||
|
||||
def get_env():
|
||||
val = os.environ.get('FLASK_ENV')
|
||||
if not val:
|
||||
val = 'production'
|
||||
return val
|
||||
"""Get the environment the app is running in, indicated by the
|
||||
:envvar:`FLASK_ENV` environment variable. The default is
|
||||
``'production'``.
|
||||
"""
|
||||
return os.environ.get('FLASK_ENV') or 'production'
|
||||
|
||||
|
||||
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')
|
||||
|
||||
if not val:
|
||||
env = get_env()
|
||||
if env == 'development':
|
||||
return True
|
||||
return False
|
||||
return get_env() == 'development'
|
||||
|
||||
return val.lower() not in ('0', 'false', 'no')
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue