remove FLASK_ENV from docs
This commit is contained in:
David Lord
parent
ef95998d79
commit
30427a2090
7 changed files with 94 additions and 198 deletions
98
docs/cli.rst
98
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,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
-----------------------------
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue