maya-chen/flask
1
0
Fork 0
forked from orbit-oss/flask
Code Pull requests Activity

remove FLASK_ENV from docs

Browse source
This commit is contained in:
David Lord 2022-08-01 15:11:35 -07:00
parent ef95998d79
commit 30427a2090
No known key found for this signature in database
GPG key ID: 7A1C87E3F5BC42A8
7 changed files with 94 additions and 198 deletions
Download patch file Download diff file Expand all files Collapse all files

98
docs/cli.rst
View file

@ -71,7 +71,7 @@ Run the Development Server
The :func:`run <cli.run_command>` command will start the development server. It The :func:`run <cli.run_command>` command will start the development server. It
replaces the :meth:`Flask.run` method in most cases. :: replaces the :meth:`Flask.run` method in most cases. ::
$ flask run $ flask --app hello run
* Serving Flask app "hello" * Serving Flask app "hello"
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) * 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. 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 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. 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: .. _dotenv:
Environment Variables From dotenv Environment Variables From dotenv

68
docs/config.rst
View file

@ -42,38 +42,22 @@ method::
) )
Environment and Debug Features Debug Mode
------------------------------ ----------
The :data:`ENV` and :data:`DEBUG` config values are special because they The :data:`DEBUG` config value is special because it may behave inconsistently if
may behave inconsistently if changed after the app has begun setting up. changed after the app has begun setting up. In order to set debug mode reliably, use the
In order to set the environment and debug mode reliably, pass options to ``--debug`` option on the ``flask`` command.``flask run`` will use the interactive
the ``flask`` command or use environment variables. debugger and reloader by default in debug mode.
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``:
.. code-block:: text .. code-block:: text
$ flask --app hello --env development run $ flask --app hello --debug run
Using the options or environment variables as described above is Using the option is recommended. While it is possible to set :data:`DEBUG` in your
recommended. While it is possible to set :data:`ENV` and :data:`DEBUG` config or code, this is strongly discouraged. It can't be read early by the ``flask``
in your config or code, this is strongly discouraged. They can't be read command, and some systems or extensions may have already configured themselves based on
early by the ``flask`` command, and some systems or extensions may have a previous value.
already configured themselves based on a previous value.
Builtin Configuration Values Builtin Configuration Values
@ -83,32 +67,27 @@ The following configuration values are used internally by Flask:
.. py:data:: ENV .. py:data:: ENV
What environment the app is running in. Flask and extensions may What environment the app is running in. The :attr:`~flask.Flask.env` attribute maps
enable behaviors based on the environment, such as enabling debug to this config key.
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'`` Default: ``'production'``
.. deprecated:: 2.2
Will be removed in Flask 2.3. Use ``--debug`` instead.
.. versionadded:: 1.0 .. versionadded:: 1.0
.. py:data:: DEBUG .. py:data:: DEBUG
Whether debug mode is enabled. When using ``flask run`` to start the Whether debug mode is enabled. When using ``flask run`` to start the development
development server, an interactive debugger will be shown for server, an interactive debugger will be shown for unhandled exceptions, and the
unhandled exceptions, and the server will be reloaded when code server will be reloaded when code changes. The :attr:`~flask.Flask.debug` attribute
changes. The :attr:`~flask.Flask.debug` attribute maps to this maps to this config key. This is set with the ``FLASK_DEBUG`` environment variable.
config key. This is enabled when :data:`ENV` is ``'development'`` It may not behave as expected if set in code.
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.** **Do not enable debug mode when deploying in production.**
Default: ``True`` if :data:`ENV` is ``'development'``, or ``False`` Default: ``False``
otherwise.
.. py:data:: TESTING .. 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 removed in Flask 2.3. The default ``app.json`` provider has
equivalent attributes instead. equivalent attributes instead.
.. versionchanged:: 2.2
``ENV`` will be removed in Flask 2.3. Use ``--debug`` instead.
Configuring from Python Files Configuring from Python Files
----------------------------- -----------------------------

22
docs/debugging.rst
View file

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

9
docs/quickstart.rst
View file

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

86
docs/server.rst
View file

@ -3,9 +3,9 @@
Development Server Development Server
================== ==================
Flask provides a ``run`` command to run the application with a Flask provides a ``run`` command to run the application with a development server. In
development server. In development mode, this server provides an debug mode, this server provides an interactive debugger and will reload when code is
interactive debugger and will reload when code is changed. changed.
.. warning:: .. warning::
@ -18,65 +18,18 @@ interactive debugger and will reload when code is changed.
Command Line Command Line
------------ ------------
The ``flask run`` command line script is the recommended way to run the The ``flask run`` CLI command is the recommended way to run the development server. Use
development server. Use the ``--app`` option to point to your the ``--app`` option to point to your application, and the ``--debug`` option to enable
application, and the ``--env development`` option to fully enable debug mode.
development mode.
.. code-block:: text .. 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 This enables debug mode, including the interactive debugger and reloader, and then
variables. 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
.. tabs:: the CLI.
.. 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.
.. _address-already-in-use: .. _address-already-in-use:
@ -144,18 +97,13 @@ while still allowing the server to handle errors on reload.
In Code In Code
------- -------
As an alternative to the ``flask run`` command, the development server The development server can also be started from Python with the :meth:`Flask.run`
can also be started from Python with the :meth:`Flask.run` method. This method. This method takes arguments similar to the CLI options to control the server.
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
The main difference from the CLI command is that the server will crash errors when reloading. ``debug=True`` can be passed to enable debug mode.
if there are errors when reloading.
``debug=True`` can be passed to enable the debugger and reloader, but Place the call in a main block, otherwise it will interfere when trying to import and
the ``FLASK_ENV=development`` environment variable is still required to run the application with a production server later.
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.
.. code-block:: python .. code-block:: python

7
docs/tutorial/factory.rst
View file

@ -127,24 +127,23 @@ Run The Application
Now you can run your application using the ``flask`` command. From the Now you can run your application using the ``flask`` command. From the
terminal, tell Flask where to find your application, then run it in 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. ``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 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 code. You can leave it running and just reload the browser page as you
follow the tutorial. follow the tutorial.
.. code-block:: text .. code-block:: text
$ flask --app flaskr --env development run $ flask --app flaskr --debug run
You'll see output similar to this: You'll see output similar to this:
.. code-block:: text .. code-block:: text
* Serving Flask app "flaskr" * Serving Flask app "flaskr"
* Environment: development
* Debug mode: on * Debug mode: on
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with stat * Restarting with stat

2
examples/tutorial/README.rst
View file

@ -48,7 +48,7 @@ Run
.. code-block:: text .. code-block:: text
$ flask --app flaskr init-db $ 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. Open http://127.0.0.1:5000 in a browser.