From 30427a209043bfb9730904e0c34b0dbc40bd21f4 Mon Sep 17 00:00:00 2001 From: David Lord Date: Mon, 1 Aug 2022 15:11:35 -0700 Subject: [PATCH] remove FLASK_ENV from docs --- docs/cli.rst | 78 +++++++++++--------------------- docs/config.rst | 68 +++++++++++----------------- docs/debugging.rst | 22 ++++----- docs/quickstart.rst | 9 ++-- docs/server.rst | 86 +++++++----------------------------- docs/tutorial/factory.rst | 7 ++- examples/tutorial/README.rst | 2 +- 7 files changed, 84 insertions(+), 188 deletions(-) diff --git a/docs/cli.rst b/docs/cli.rst index 954192f0de..22484f1731 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -71,7 +71,7 @@ Run the Development Server The :func:`run ` 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,43 +86,17 @@ 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 ` 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 @@ -130,13 +104,12 @@ reloader. * 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 @@ -144,22 +117,25 @@ separated with ``:``, or ``;`` on Windows. * 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 ` 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 index 6111931e32..bc16e4bac1 100644 --- 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 index b907c769cd..fb3604b036 100644 --- 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 -`__. +: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 `__. 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 index a824f6f3a0..85668aa18b 100644 --- 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 diff --git a/docs/server.rst b/docs/server.rst index 5c78f171bd..a34dfab5dd 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -3,9 +3,9 @@ Development Server ================== -Flask provides a ``run`` command to run the application with a -development server. In development mode, this server provides an -interactive debugger and will reload when code is changed. +Flask provides a ``run`` command to run the application with a development server. In +debug mode, this server provides an interactive debugger and will reload when code is +changed. .. warning:: @@ -18,65 +18,18 @@ interactive debugger and will reload when code is changed. Command Line ------------ -The ``flask run`` command line script is the recommended way to run the -development server. Use the ``--app`` option to point to your -application, and the ``--env development`` option to fully enable -development mode. +The ``flask run`` CLI command is the recommended way to run the development server. Use +the ``--app`` option to point to your application, and the ``--debug`` option to enable +debug mode. .. code-block:: text - $ flask --app hello --env development run + $ flask --app hello --debug run -These options (and any others) can also be set using environment -variables. - -.. tabs:: - - .. group-tab:: Bash - - .. code-block:: text - - $ export FLASK_APP=hello - $ export FLASK_ENV=development - $ flask run - - .. group-tab:: Fish - - .. code-block:: text - - $ set -x FLASK_APP hello - $ export FLASK_ENV=development - $ flask run - - .. group-tab:: CMD - - .. code-block:: text - - > set FLASK_APP=hello - > set FLASK_ENV=development - > flask run - - .. group-tab:: Powershell - - .. code-block:: text - - > $env:FLASK_APP = "hello" - > $env:FLASK_ENV = "development" - > flask run - -This enables the development environment, including the interactive -debugger and reloader, and then starts the server on -http://localhost:5000/. Use ``flask run --help`` to see the available -options, and :doc:`/cli` for detailed instructions about configuring -and using the CLI. - -.. note:: - - Debug mode can be controlled separately from the development - environment with the ``--debug/--no-debug`` option or the - ``FLASK_DEBUG`` environment variable. This is how older versions of - Flask worked. You should prefer setting the development environment - as shown above. +This enables debug mode, including the interactive debugger and reloader, and then +starts the server on http://localhost:5000/. Use ``flask run --help`` to see the +available options, and :doc:`/cli` for detailed instructions about configuring and using +the CLI. .. _address-already-in-use: @@ -144,18 +97,13 @@ while still allowing the server to handle errors on reload. In Code ------- -As an alternative to the ``flask run`` command, the development server -can also be started from Python with the :meth:`Flask.run` method. This -method takes arguments similar to the CLI options to control the server. -The main difference from the CLI command is that the server will crash -if there are errors when reloading. - -``debug=True`` can be passed to enable the debugger and reloader, but -the ``FLASK_ENV=development`` environment variable is still required to -fully enable development mode. +The development server can also be started from Python with the :meth:`Flask.run` +method. This method takes arguments similar to the CLI options to control the server. +The main difference from the CLI command is that the server will crash if there are +errors when reloading. ``debug=True`` can be passed to enable debug mode. -Place the call in a main block, otherwise it will interfere when trying -to import and run the application with a production server later. +Place the call in a main block, otherwise it will interfere when trying to import and +run the application with a production server later. .. code-block:: python diff --git a/docs/tutorial/factory.rst b/docs/tutorial/factory.rst index cbfecab30b..c8e2c5f4e0 100644 --- a/docs/tutorial/factory.rst +++ b/docs/tutorial/factory.rst @@ -127,24 +127,23 @@ Run The Application Now you can run your application using the ``flask`` command. From the terminal, tell Flask where to find your application, then run it in -development mode. Remember, you should still be in the top-level +debug mode. Remember, you should still be in the top-level ``flask-tutorial`` directory, not the ``flaskr`` package. -Development mode shows an interactive debugger whenever a page raises an +Debug mode shows an interactive debugger whenever a page raises an exception, and restarts the server whenever you make changes to the code. You can leave it running and just reload the browser page as you follow the tutorial. .. code-block:: text - $ flask --app flaskr --env development run + $ flask --app flaskr --debug run You'll see output similar to this: .. code-block:: text * Serving Flask app "flaskr" - * Environment: development * Debug mode: on * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) * Restarting with stat diff --git a/examples/tutorial/README.rst b/examples/tutorial/README.rst index 6c7c2fe9ce..a7e12ca250 100644 --- a/examples/tutorial/README.rst +++ b/examples/tutorial/README.rst @@ -48,7 +48,7 @@ Run .. code-block:: text $ flask --app flaskr init-db - $ flask --app flaskr --env development run + $ flask --app flaskr --debug run Open http://127.0.0.1:5000 in a browser.