Merge pull request pallets#4720 from pallets/deprecate-env

deprecate `FLASK_ENV` and `app.env`

Author: davidism

CHANGES.rst

@@ -23,6 +23,10 @@ Unreleased
         ``g`` instead using a unique prefix, like
         ``g._extension_name_attr``.
 
+-   The ``FLASK_ENV`` environment variable and ``app.env`` attribute are
+    deprecated, removing the distinction between development and debug
+    mode. Debug mode should be controlled directly using the ``--debug``
+    option or ``app.run(debug=True)``. :issue:`4714`
 -   Add new customization points to the ``Flask`` app object for many
     previously global behaviors.
 
@@ -60,9 +64,9 @@ Unreleased
     instance on every request. :issue:`2520`.
 -   A ``flask.cli.FlaskGroup`` Click group can be nested as a
     sub-command in a custom CLI. :issue:`3263`
--   Add ``--app``, ``--env``, and ``--debug`` options to the ``flask``
-    CLI, instead of requiring that they are set through environment
-    variables. :issue:`2836`
+-   Add ``--app`` and ``--debug`` options to the ``flask`` CLI, instead
+    of requiring that they are set through environment variables.
+    :issue:`2836`
 -   Add ``--env-file`` option to the ``flask`` CLI. This allows
     specifying a dotenv file to load in addition to ``.env`` and
     ``.flaskenv``. :issue:`3108`

docs/_static/pycharm-run-config.png

@@ -71,7 +71,7 @@ Run the Development Server
 The :func:`run <cli.run_command>` command will start the development server. It
 replaces the :meth:`Flask.run` method in most cases. ::
 
-    $ flask run
+    $ flask --app hello run
      * Serving Flask app "hello"
      * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 
@@ -86,80 +86,56 @@ server tries to start. See :ref:`address-already-in-use` for how to
 handle that.
 
 
-Open a Shell
-------------
-
-To explore the data in your application, you can start an interactive Python
-shell with the :func:`shell <cli.shell_command>` command. An application
-context will be active, and the app instance will be imported. ::
-
-    $ flask shell
-    Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux
-    App: example [production]
-    Instance: /home/david/Projects/pallets/flask/instance
-    >>>
-
-Use :meth:`~Flask.shell_context_processor` to add other automatic imports.
-
-
-Environments
-------------
-
-.. versionadded:: 1.0
+Debug Mode
+~~~~~~~~~~
 
-The environment in which the Flask app executes is set by the
-``FLASK_ENV`` environment variable. When using the ``flask`` command, it
-can also be set with the ``--env`` option. 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.
+In debug mode, the ``flask run`` command will enable the interactive debugger and the
+reloader by default, and make errors easier to see and debug. To enable debug mode, use
+the ``--debug`` option.
 
-If the env is set to ``development``, the ``flask`` command will enable
-debug mode and ``flask run`` will enable the interactive debugger and
-reloader.
+.. code-block:: console
 
-.. code-block:: text
-
-     $ flask --app hello --env development run
+     $ flask --app hello --debug run
       * Serving Flask app "hello"
-      * 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
 
 
-Watch Extra Files with the Reloader
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Watch and Ignore Files with the Reloader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When using development mode, the reloader will trigger whenever your
-Python code or imported modules change. The reloader can watch
-additional files with the ``--extra-files`` option. Multiple paths are
-separated with ``:``, or ``;`` on Windows.
+When using debug mode, the reloader will trigger whenever your Python code or imported
+modules change. The reloader can watch additional files with the ``--extra-files``
+option. Multiple paths are separated with ``:``, or ``;`` on Windows.
 
 .. code-block:: text
 
     $ flask run --extra-files file1:dirA/file2:dirB/
      * Running on http://127.0.0.1:8000/
      * Detected change in '/path/to/file1', reloading
 
+The reloader can also ignore files using :mod:`fnmatch` patterns with the
+``--exclude-patterns`` option. Multiple patterns are separated with ``:``, or ``;`` on
+Windows.
 
-Ignore files with the Reloader
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The reloader can also ignore files using :mod:`fnmatch` patterns with
-the ``--exclude-patterns`` option. Multiple patterns are separated with
-``:``, or ``;`` on Windows.
+Open a Shell
+------------
 
+To explore the data in your application, you can start an interactive Python
+shell with the :func:`shell <cli.shell_command>` command. An application
+context will be active, and the app instance will be imported. ::
 
-Debug Mode
-----------
+    $ flask shell
+    Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux
+    App: example [production]
+    Instance: /home/david/Projects/pallets/flask/instance
+    >>>
 
-Debug mode will be enabled when the execution environment is
-``development``, as described above. If you want to control debug mode
-separately, use the ``--debug/--no-debug`` option or the ``FLASK_DEBUG``
-environment variable.
+Use :meth:`~Flask.shell_context_processor` to add other automatic imports.
 
 
 .. _dotenv:
@@ -552,53 +528,36 @@ script is available. Note that you don't need to set ``--app``. ::
 PyCharm Integration
 -------------------
 
-PyCharm Professional provides a special Flask run configuration. For
-the Community Edition, we need to configure it to call the ``flask run``
-CLI command with the correct environment variables. These instructions
-should be similar for any other IDE you might want to use.
+PyCharm Professional provides a special Flask run configuration to run the development
+server. For the Community Edition, and for other commands besides ``run``, you need to
+create a custom run configuration. These instructions should be similar for any other
+IDE you use.
 
-In PyCharm, with your project open, click on *Run* from the menu bar and
-go to *Edit Configurations*. You'll be greeted by a screen similar to
-this:
+In PyCharm, with your project open, click on *Run* from the menu bar and go to *Edit
+Configurations*. You'll see a screen similar to this:
 
-.. image:: _static/pycharm-runconfig.png
+.. image:: _static/pycharm-run-config.png
     :align: center
     :class: screenshot
-    :alt: Screenshot of PyCharms's run configuration settings.
-
-There's quite a few options to change, but once we've done it for one
-command, we can easily copy the entire configuration and make a single
-tweak to give us access to other commands, including any custom ones you
-may implement yourself.
-
-Click the + (*Add New Configuration*) button and select *Python*. Give
-the configuration a name such as "flask run". For the ``flask run``
-command, check "Single instance only" since you can't run the server
-more than once at the same time.
+    :alt: Screenshot of PyCharm run configuration.
 
-Select *Module name* from the dropdown (**A**) then input ``flask``.
+Once you create a configuration for the ``flask run``, you can copy and change it to
+call any other command.
 
-The *Parameters* field (**B**) is set to the CLI command to execute
-(with any arguments). In this example we use ``run``, which will run
-the development server.
+Click the *+ (Add New Configuration)* button and select *Python*. Give the configuration
+a name such as "flask run".
 
-You can skip this next step if you're using :ref:`dotenv`. We need to
-add an environment variable (**C**) to identify our application. Click
-on the browse button and add an entry with ``FLASK_APP`` on the left and
-the Python import or file on the right (``hello`` for example). Add an
-entry with ``FLASK_ENV`` and set it to ``development``.
+Click the *Script path* dropdown and change it to *Module name*, then input ``flask``.
 
-Next we need to set the working directory (**D**) to be the folder where
-our application resides.
+The *Parameters* field is set to the CLI command to execute along with any arguments.
+This example uses ``--app hello --debug run``, which will run the development server in
+debug mode. ``--app hello`` should be the import or file with your Flask app.
 
-If you have installed your project as a package in your virtualenv, you
-may untick the *PYTHONPATH* options (**E**). This will more accurately
-match how you deploy the app later.
+If you installed your project as a package in your virtualenv, you may uncheck the
+*PYTHONPATH* options. This will more accurately match how you deploy later.
 
-Click *Apply* to save the configuration, or *OK* to save and close the
-window. Select the configuration in the main PyCharm window and click
-the play button next to it to run the server.
+Click *OK* to save and close the configuration. Select the configuration in the main
+PyCharm window and click the play button next to it to run the server.
 
-Now that we have a configuration which runs ``flask run`` from within
-PyCharm, we can copy that configuration and alter the *Script* argument
-to run a different CLI command, e.g. ``flask shell``.
+Now that you have a configuration for ``flask run``, you can copy that configuration and
+change the *Parameters* argument to run a different CLI command.

docs/_static/pycharm-runconfig.png

@@ -42,38 +42,22 @@ method::
     )
 
 
-Environment and Debug Features
-------------------------------
+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, pass options to
-the ``flask`` command or use environment variables.
-
-The execution environment is used to indicate to Flask, extensions, and
-other programs, like Sentry, what context Flask is running in. It is
-controlled with the ``FLASK_ENV`` environment variable, or the
-``--env`` option when using the ``flask`` command, and defaults to
-``production``.
-
-Setting ``--env 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
-``--debug/--no-debug`` option or the ``FLASK_DEBUG`` environment
-variable.
-
-To switch Flask to the development environment and enable debug mode,
-set ``--env``:
+The :data:`DEBUG` config value is special because it may behave inconsistently if
+changed after the app has begun setting up. In order to set debug mode reliably, use the
+``--debug`` option on the ``flask`` command.``flask run`` will use the interactive
+debugger and reloader by default in debug mode.
 
 .. code-block:: text
 
-    $ flask --app hello --env development run
+    $ flask --app hello --debug run
 
-Using the options or 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.
+Using the option is recommended. While it is possible to set :data:`DEBUG` in your
+config or code, this is strongly discouraged. It can't be read early by the ``flask``
+command, and some systems or extensions may have already configured themselves based on
+a previous value.
 
 
 Builtin Configuration Values
@@ -83,32 +67,27 @@ 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.**
+    What environment the app is running in. The :attr:`~flask.Flask.env` attribute maps
+    to this config key.
 
     Default: ``'production'``
 
+    .. deprecated:: 2.2
+        Will be removed in Flask 2.3. Use ``--debug`` instead.
+
     .. versionadded:: 1.0
 
 .. py:data:: DEBUG
 
-    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.
+    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 set with 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 :data:`ENV` is ``'development'``, or ``False``
-    otherwise.
+    Default: ``False``
 
 .. py:data:: TESTING
 
@@ -408,6 +387,9 @@ The following configuration values are used internally by Flask:
     removed in Flask 2.3. The default ``app.json`` provider has
     equivalent attributes instead.
 
+.. versionchanged:: 2.2
+    ``ENV`` will be removed in Flask 2.3. Use ``--debug`` instead.
+
 
 Configuring from Python Files
 -----------------------------

docs/cli.rst

@@ -39,28 +39,22 @@ during a request. This debugger should only be used during development.
     security risk. Do not run the development server or debugger in a
     production environment.
 
-To enable the debugger, run the development server with the environment
-set to ``development``. This puts Flask in debug mode, which changes how
-it handles some errors, and enables the debugger and reloader.
+The debugger is enabled by default when the development server is run in debug mode.
 
 .. code-block:: text
 
-    $ flask --app hello --env development run
+    $ flask --app hello --debug run
 
-``FLASK_ENV`` can also be set as an environment variable. When running
-from Python code, passing ``debug=True`` enables debug mode, which is
-mostly equivalent. Debug mode can be controlled separately from the
-environment with the ``--debug/--no-debug`` option or the
-``FLASK_DEBUG`` environment variable.
+When running from Python code, passing ``debug=True`` enables debug mode, which is
+mostly equivalent.
 
 .. code-block:: python
 
     app.run(debug=True)
 
-:doc:`/server` and :doc:`/cli` have more information about running the
-debugger, debug mode, and development mode. More information about the
-debugger can be found in the `Werkzeug documentation
-<https://werkzeug.palletsprojects.com/debug/>`__.
+:doc:`/server` and :doc:`/cli` have more information about running the debugger and
+debug mode. More information about the debugger can be found in the `Werkzeug
+documentation <https://werkzeug.palletsprojects.com/debug/>`__.
 
 
 External Debuggers
@@ -78,7 +72,7 @@ which can interfere.
 
 .. code-block:: text
 
-    $ flask --app hello --env development run --no-debugger --no-reload
+    $ flask --app hello --debug run --no-debugger --no-reload
 
 When running from Python:
 

docs/config.rst

@@ -104,14 +104,12 @@ error occurs during a request.
     security risk. Do not run the development server or debugger in a
     production environment.
 
-To enable all development features, set the ``--env`` option to
-``development``.
+To enable debug mode, use the ``--debug`` option.
 
 .. code-block:: text
 
-    $ flask --app hello --env development run
+    $ flask --app hello --debug run
      * Serving Flask app 'hello'
-     * Environment: development
      * Debug mode: on
      * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)
      * Restarting with stat
@@ -120,8 +118,7 @@ To enable all development features, set the ``--env`` option to
 
 See also:
 
--   :doc:`/server` and :doc:`/cli` for information about running in
-    development mode.
+-   :doc:`/server` and :doc:`/cli` for information about running in debug mode.
 -   :doc:`/debugging` for information about using the built-in debugger
     and other debuggers.
 -   :doc:`/logging` and :doc:`/errorhandling` to log errors and display