remove FLASK_ENV from docs

pallets · Aug 1, 2022 · 30427a2 · 30427a2
1 parent ef95998
commit 30427a2
Show file tree

Hide file tree

Showing 7 changed files with 84 additions and 188 deletions.
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -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
-
-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.
+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.
+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.
 
-.. code-block:: text
+.. code-block:: console
 
-     $ 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:

diff --git a/docs/config.rst b/docs/config.rst
@@ -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
 -----------------------------

diff --git a/docs/debugging.rst b/docs/debugging.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:
 

diff --git a/docs/quickstart.rst b/docs/quickstart.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