diff --git a/docs/cli.rst b/docs/cli.rst index 954192f0..22484f17 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,6 +86,42 @@ server tries to start. See :ref:`address-already-in-use` for how to handle that. +Debug Mode +~~~~~~~~~~ + +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:: console + + $ flask --app hello --debug run + * Serving Flask app "hello" + * 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 and Ignore Files with the Reloader +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + + Open a Shell ------------ @@ -102,66 +138,6 @@ 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 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. - -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:: text - - $ flask --app hello --env development 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - -.. 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 - - -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. - - -Debug Mode ----------- - -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. - - .. _dotenv: Environment Variables From dotenv diff --git a/docs/config.rst b/docs/config.rst index 6111931e..bc16e4ba 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 b907c769..fb3604b0 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 a824f6f3..85668aa1 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 5c78f171..a34dfab5 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. +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. -``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. - -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 cbfecab3..c8e2c5f4 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 6c7c2fe9..a7e12ca2 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.