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
Split 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.
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

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
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.
.. 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
work on the ``development`` environment::
To switch Flask to the development environment and enable debug mode,
set :envvar:`FLASK_ENV`::
$ export FLASK_ENV=development
$ flask run
$ export FLASK_ENV=development
$ 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
----------------------------
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
----------------------

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
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

14
docs/server.rst
Unescape View File

@ -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
-------

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
(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!

43
flask/app.py
Unescape View File

@ -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)
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
#: 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.
#: 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.
#:
#: 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.
#: **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 _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,
load_dotenv=True, **options):
"""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():
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')

Write Preview
Loading…
Cancel
Save