clean up FLASK_ENV docs [ci skip]

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
+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"
-     * Forcing debug mode on
+     * Environment: development
-     * Env production
+     * 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

docs/config.rst

@@ -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
+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.
 
-The most common way to switch Flask to development mode is to tell it to
+.. versionchanged:: 1.0
-work on the ``development`` environment::
+    Added :envvar:`FLASK_ENV` to control the environment separately
+    from debug mode. The development environment enables debug mode.
 
-$ export FLASK_ENV=development
+To switch Flask to the development environment and enable debug mode,
-$ flask run
+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
+    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
 
@@ -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
 ----------------------
 

docs/quickstart.rst

@@ -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
+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::
 
     $ export FLASK_ENV=development
     $ 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:
 
@@ -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

docs/server.rst

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

docs/tutorial/packaging.rst

@@ -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
+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
 allow users to execute code on the server!

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
+    #: 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')
 
     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.

flask/helpers.py

@@ -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')
+    """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():
+    """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()
+        return get_env() == 'development'
-        if env == 'development':
+
-            return True
-        return False
     return val.lower() not in ('0', 'false', 'no')