orbit-oss/flask
4
4
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

prefer --app over FLASK_APP in docs

Browse source
This commit is contained in:
David Lord 2022-06-17 09:26:26 -07:00
parent 99fa3c36ab
commit ab1fbef29a
No known key found for this signature in database
GPG key ID: 7A1C87E3F5BC42A8
15 changed files with 147 additions and 580 deletions
Download patch file Download diff file Expand all files Collapse all files

206
docs/cli.rst
View file

@ -15,40 +15,10 @@ Application Discovery
--------------------- ---------------------
The ``flask`` command is installed by Flask, not your application; it must be The ``flask`` command is installed by Flask, not your application; it must be
told where to find your application in order to use it. The ``FLASK_APP`` told where to find your application in order to use it. The ``--app``
environment variable is used to specify how to load the application. option is used to specify how to load the application.
.. tabs:: While ``--app`` supports a variety of options for specifying your
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_APP=hello
$ flask run
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_APP hello
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP=hello
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "hello"
> flask run
While ``FLASK_APP`` supports a variety of options for specifying your
application, most use cases should be simple. Here are the typical values: application, most use cases should be simple. Here are the typical values:
(nothing) (nothing)
@ -56,32 +26,32 @@ application, most use cases should be simple. Here are the typical values:
automatically detecting an app (``app`` or ``application``) or automatically detecting an app (``app`` or ``application``) or
factory (``create_app`` or ``make_app``). factory (``create_app`` or ``make_app``).
``FLASK_APP=hello`` ``--app hello``
The given name is imported, automatically detecting an app (``app`` The given name is imported, automatically detecting an app (``app``
or ``application``) or factory (``create_app`` or ``make_app``). or ``application``) or factory (``create_app`` or ``make_app``).
---- ----
``FLASK_APP`` has three parts: an optional path that sets the current working ``--app`` has three parts: an optional path that sets the current working
directory, a Python file or dotted import path, and an optional variable directory, a Python file or dotted import path, and an optional variable
name of the instance or factory. If the name is a factory, it can optionally name of the instance or factory. If the name is a factory, it can optionally
be followed by arguments in parentheses. The following values demonstrate these be followed by arguments in parentheses. The following values demonstrate these
parts: parts:
``FLASK_APP=src/hello`` ``--app src/hello``
Sets the current working directory to ``src`` then imports ``hello``. Sets the current working directory to ``src`` then imports ``hello``.
``FLASK_APP=hello.web`` ``--app hello.web``
Imports the path ``hello.web``. Imports the path ``hello.web``.
``FLASK_APP=hello:app2`` ``--app hello:app2``
Uses the ``app2`` Flask instance in ``hello``. Uses the ``app2`` Flask instance in ``hello``.
``FLASK_APP="hello:create_app('dev')"`` ``--app 'hello:create_app("dev")'``
The ``create_app`` factory in ``hello`` is called with the string ``'dev'`` The ``create_app`` factory in ``hello`` is called with the string ``'dev'``
as the argument. as the argument.
If ``FLASK_APP`` is not set, the command will try to import "app" or If ``--app`` is not set, the command will try to import "app" or
"wsgi" (as a ".py" file, or package) and try to detect an application "wsgi" (as a ".py" file, or package) and try to detect an application
instance or factory. instance or factory.
@ -137,8 +107,9 @@ Environments
.. versionadded:: 1.0 .. versionadded:: 1.0
The environment in which the Flask app runs is set by the The environment in which the Flask app executes is set by the
:envvar:`FLASK_ENV` environment variable. If not set it defaults to ``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``. ``production``. The other recognized environment is ``development``.
Flask and extensions may choose to enable behaviors based on the Flask and extensions may choose to enable behaviors based on the
environment. environment.
@ -147,63 +118,16 @@ If the env is set to ``development``, the ``flask`` command will enable
debug mode and ``flask run`` will enable the interactive debugger and debug mode and ``flask run`` will enable the interactive debugger and
reloader. reloader.
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app hello --env development run
* Serving Flask app "hello"
.. code-block:: text * Environment: development
* Debug mode: on
$ export FLASK_ENV=development * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
$ flask run * Restarting with inotify reloader
* Serving Flask app "hello" * Debugger is active!
* Environment: development * Debugger PIN: 223-456-919
* 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
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_ENV development
$ flask 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
.. group-tab:: CMD
.. code-block:: text
> set FLASK_ENV=development
> flask 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
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_ENV = "development"
> flask 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 Extra Files with the Reloader
@ -211,72 +135,31 @@ Watch Extra Files with the Reloader
When using development mode, the reloader will trigger whenever your When using development mode, the reloader will trigger whenever your
Python code or imported modules change. The reloader can watch Python code or imported modules change. The reloader can watch
additional files with the ``--extra-files`` option, or the additional files with the ``--extra-files`` option. Multiple paths are
``FLASK_RUN_EXTRA_FILES`` environment variable. Multiple paths are
separated with ``:``, or ``;`` on Windows. separated with ``:``, or ``;`` on Windows.
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask run --extra-files file1:dirA/file2:dirB/
* Running on http://127.0.0.1:8000/
.. code-block:: text * Detected change in '/path/to/file1', reloading
$ flask run --extra-files file1:dirA/file2:dirB/
# or
$ export FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
$ flask run
* Running on http://127.0.0.1:8000/
* Detected change in '/path/to/file1', reloading
.. group-tab:: Fish
.. code-block:: text
$ flask run --extra-files file1:dirA/file2:dirB/
# or
$ set -x FLASK_RUN_EXTRA_FILES file1 dirA/file2 dirB/
$ flask run
* Running on http://127.0.0.1:8000/
* Detected change in '/path/to/file1', reloading
.. group-tab:: CMD
.. code-block:: text
> flask run --extra-files file1:dirA/file2:dirB/
# or
> set FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
> flask run
* Running on http://127.0.0.1:8000/
* Detected change in '/path/to/file1', reloading
.. group-tab:: Powershell
.. code-block:: text
> flask run --extra-files file1:dirA/file2:dirB/
# or
> $env:FLASK_RUN_EXTRA_FILES = "file1:dirA/file2:dirB/"
> flask run
* Running on http://127.0.0.1:8000/
* Detected change in '/path/to/file1', reloading
Ignore files with the Reloader Ignore files with the Reloader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The reloader can also ignore files using :mod:`fnmatch` patterns with The reloader can also ignore files using :mod:`fnmatch` patterns with
the ``--exclude-patterns`` option, or the ``FLASK_RUN_EXCLUDE_PATTERNS`` the ``--exclude-patterns`` option. Multiple patterns are separated with
environment variable. Multiple patterns are separated with ``:``, or ``:``, or ``;`` on Windows.
``;`` on Windows.
Debug Mode Debug Mode
---------- ----------
Debug mode will be enabled when :envvar:`FLASK_ENV` is ``development``, Debug mode will be enabled when the execution environment is
as described above. If you want to control debug mode separately, use ``development``, as described above. If you want to control debug mode
:envvar:`FLASK_DEBUG`. The value ``1`` enables it, ``0`` disables it. separately, use the ``--debug/--no-debug`` option or the ``FLASK_DEBUG``
environment variable.
.. _dotenv: .. _dotenv:
@ -284,14 +167,21 @@ as described above. If you want to control debug mode separately, use
Environment Variables From dotenv Environment Variables From dotenv
--------------------------------- ---------------------------------
Rather than setting ``FLASK_APP`` each time you open a new terminal, you can The ``flask`` command supports setting any option for any command with
use Flask's dotenv support to set environment variables automatically. environment variables. The variables are named like ``FLASK_OPTION`` or
``FLASK_COMMAND_OPTION``, for example ``FLASK_APP`` or
``FLASK_RUN_PORT``.
Rather than passing options every time you run a command, or environment
variables every time you open a new terminal, you can use Flask's dotenv
support to set environment variables automatically.
If `python-dotenv`_ is installed, running the ``flask`` command will set If `python-dotenv`_ is installed, running the ``flask`` command will set
environment variables defined in the files :file:`.env` and :file:`.flaskenv`. environment variables defined in the files ``.env`` and ``.flaskenv``.
This can be used to avoid having to set ``FLASK_APP`` manually every time you You can also specify an extra file to load with the ``--env-file``
open a new terminal, and to set configuration using environment variables option. Dotenv files can be used to avoid having to set ``--app`` or
similar to how some deployment services work. ``FLASK_APP`` manually, and to set configuration using environment
variables similar to how some deployment services work.
Variables set on the command line are used over those set in :file:`.env`, Variables set on the command line are used over those set in :file:`.env`,
which are used over those set in :file:`.flaskenv`. :file:`.flaskenv` should be which are used over those set in :file:`.flaskenv`. :file:`.flaskenv` should be
@ -612,7 +502,7 @@ Custom Scripts
-------------- --------------
When you are using the app factory pattern, it may be more convenient to define When you are using the app factory pattern, it may be more convenient to define
your own Click script. Instead of using ``FLASK_APP`` and letting Flask load your own Click script. Instead of using ``--app`` and letting Flask load
your application, you can create your own Click object and export it as a your application, you can create your own Click object and export it as a
`console script`_ entry point. `console script`_ entry point.
@ -646,7 +536,7 @@ Define the entry point in :file:`setup.py`::
) )
Install the application in the virtualenv in editable mode and the custom Install the application in the virtualenv in editable mode and the custom
script is available. Note that you don't need to set ``FLASK_APP``. :: script is available. Note that you don't need to set ``--app``. ::
$ pip install -e . $ pip install -e .
$ wiki run $ wiki run

68
docs/config.rst
View file

@ -47,61 +47,33 @@ Environment and Debug Features
The :data:`ENV` and :data:`DEBUG` config values are special because they The :data:`ENV` and :data:`DEBUG` config values are special because they
may behave inconsistently if changed after the app has begun setting up. may behave inconsistently if changed after the app has begun setting up.
In order to set the environment and debug mode reliably, Flask uses In order to set the environment and debug mode reliably, pass options to
environment variables. the ``flask`` command or use environment variables.
The environment is used to indicate to Flask, extensions, and other The execution environment is used to indicate to Flask, extensions, and
programs, like Sentry, what context Flask is running in. It is other programs, like Sentry, what context Flask is running in. It is
controlled with the :envvar:`FLASK_ENV` environment variable and controlled with the ``FLASK_ENV`` environment variable, or the
defaults to ``production``. ``--env`` option when using the ``flask`` command, and defaults to
``production``.
Setting :envvar:`FLASK_ENV` to ``development`` will enable debug mode. Setting ``--env development`` will enable debug mode. ``flask run`` will
``flask run`` will use the interactive debugger and reloader by default use the interactive debugger and reloader by default in debug mode. To
in debug mode. To control this separately from the environment, use the control this separately from the environment, use the
:envvar:`FLASK_DEBUG` flag. ``--debug/--no-debug`` option or the ``FLASK_DEBUG`` environment
variable.
.. versionchanged:: 1.0
Added :envvar:`FLASK_ENV` to control the environment separately
from debug mode. The development environment enables debug mode.
To switch Flask to the development environment and enable debug mode, To switch Flask to the development environment and enable debug mode,
set :envvar:`FLASK_ENV`: set ``--env``:
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app hello --env development run
.. code-block:: text Using the options or environment variables as described above is
recommended. While it is possible to set :data:`ENV` and :data:`DEBUG`
$ export FLASK_ENV=development in your config or code, this is strongly discouraged. They can't be read
$ flask run early by the ``flask`` command, and some systems or extensions may have
already configured themselves based on a previous value.
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_ENV development
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_ENV=development
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_ENV = "development"
> flask run
Using the 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.
Builtin Configuration Values Builtin Configuration Values

76
docs/debugging.rst
View file

@ -39,45 +39,19 @@ 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 To enable the debugger, run the development server with the environment
``FLASK_ENV`` environment variable set to ``development``. This puts set to ``development``. This puts Flask in debug mode, which changes how
Flask in debug mode, which changes how it handles some errors, and it handles some errors, and enables the debugger and reloader.
enables the debugger and reloader.
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app hello --env development run
.. code-block:: text ``FLASK_ENV`` can also be set as an environment variable. When running
$ export FLASK_ENV=development
$ flask run
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_ENV development
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_ENV=development
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_ENV = "development"
> flask run
``FLASK_ENV`` can only be set as an environment variable. 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. Debug mode can be controlled separately from mostly equivalent. Debug mode can be controlled separately from the
``FLASK_ENV`` with the ``FLASK_DEBUG`` environment variable as well. environment with the ``--debug/--no-debug`` option or the
``FLASK_DEBUG`` environment variable.
.. code-block:: python .. code-block:: python
@ -102,37 +76,9 @@ When using an external debugger, the app should still be in debug mode,
but it can be useful to disable the built-in debugger and reloader, but it can be useful to disable the built-in debugger and reloader,
which can interfere. which can interfere.
When running from the command line: .. code-block:: text
.. tabs:: $ flask --app hello --env development run --no-debugger --no-reload
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_ENV=development
$ flask run --no-debugger --no-reload
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_ENV development
$ flask run --no-debugger --no-reload
.. group-tab:: CMD
.. code-block:: text
> set FLASK_ENV=development
> flask run --no-debugger --no-reload
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_ENV = "development"
> flask run --no-debugger --no-reload
When running from Python: When running from Python:

69
docs/patterns/appfactories.rst
View file

@ -89,71 +89,20 @@ Using Applications
To run such an application, you can use the :command:`flask` command: To run such an application, you can use the :command:`flask` command:
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask run --app hello run
.. code-block:: text Flask will automatically detect the factory if it is named
``create_app`` or ``make_app`` in ``hello``. You can also pass arguments
to the factory like this:
$ export FLASK_APP=myapp .. code-block:: text
$ flask run
.. group-tab:: Fish $ flask run --app hello:create_app(local_auth=True)``
.. code-block:: text Then the ``create_app`` factory in ``myapp`` is called with the keyword
argument ``local_auth=True``. See :doc:`/cli` for more detail.
$ set -x FLASK_APP myapp
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP=myapp
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "myapp"
> flask run
Flask will automatically detect the factory (``create_app`` or ``make_app``)
in ``myapp``. You can also pass arguments to the factory like this:
.. tabs::
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_APP="myapp:create_app('dev')"
$ flask run
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_APP "myapp:create_app('dev')"
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP="myapp:create_app('dev')"
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "myapp:create_app('dev')"
> flask run
Then the ``create_app`` factory in ``myapp`` is called with the string
``'dev'`` as the argument. See :doc:`/cli` for more detail.
Factory Improvements Factory Improvements
-------------------- --------------------

69
docs/patterns/packages.rst
View file

@ -56,70 +56,17 @@ a big problem, just add a new file called :file:`setup.py` next to the inner
], ],
) )
In order to run the application you need to export an environment variable Install your application so it is importable:
that tells Flask where to find the application instance:
.. tabs:: .. code-block:: text
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_APP=yourapplication
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_APP yourapplication
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP=yourapplication
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "yourapplication"
If you are outside of the project directory make sure to provide the exact
path to your application directory. Similarly you can turn on the
development features like this:
.. tabs::
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_ENV=development
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_ENV development
.. group-tab:: CMD
.. code-block:: text
> set FLASK_ENV=development
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_ENV = "development"
In order to install and run the application you need to issue the following
commands::
$ pip install -e . $ pip install -e .
$ flask run
To use the ``flask`` command and run your application you need to set
the ``--app`` option that tells Flask where to find the application
instance:
$ flask --app yourapplication run
What did we gain from this? Now we can restructure the application a bit What did we gain from this? Now we can restructure the application a bit
into multiple modules. The only thing you have to remember is the into multiple modules. The only thing you have to remember is the

115
docs/quickstart.rst
View file

@ -39,50 +39,20 @@ Save it as :file:`hello.py` or something similar. Make sure to not call
your application :file:`flask.py` because this would conflict with Flask your application :file:`flask.py` because this would conflict with Flask
itself. itself.
To run the application, use the :command:`flask` command or To run the application, use the ``flask`` command or
:command:`python -m flask`. Before you can do that you need ``python -m flask``. You need to tell the Flask where your application
to tell your terminal the application to work with by exporting the is with the ``-app`` option.
``FLASK_APP`` environment variable:
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app hello run
* Serving Flask app 'hello' (lazy loading)
.. code-block:: text * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)
$ export FLASK_APP=hello
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_APP hello
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP=hello
> flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "hello"
> flask run
* Running on http://127.0.0.1:5000/
.. admonition:: Application Discovery Behavior .. admonition:: Application Discovery Behavior
As a shortcut, if the file is named ``app.py`` or ``wsgi.py``, you As a shortcut, if the file is named ``app.py`` or ``wsgi.py``, you
don't have to set the ``FLASK_APP`` environment variable. See don't have to use ``--app``. See :doc:`/cli` for more details.
:doc:`/cli` for more details.
This launches a very simple builtin server, which is good enough for This launches a very simple builtin server, which is good enough for
testing but probably not what you want to use in production. For testing but probably not what you want to use in production. For
@ -114,34 +84,6 @@ handle that.
This tells your operating system to listen on all public IPs. This tells your operating system to listen on all public IPs.
What to do if the Server does not Start
---------------------------------------
In case the :command:`python -m flask` fails or :command:`flask`
does not exist, there are multiple reasons this might be the case.
First of all you need to look at the error message.
Old Version of Flask
````````````````````
Versions of Flask older than 0.11 used to have different ways to start the
application. In short, the :command:`flask` command did not exist, and
neither did :command:`python -m flask`. In that case you have two options:
either upgrade to newer Flask versions or have a look at :doc:`/server`
to see the alternative method for running a server.
Invalid Import Name
```````````````````
The ``FLASK_APP`` environment variable is the name of the module to import at
:command:`flask run`. In case that module is incorrectly named you will get an
import error upon start (or if debug is enabled when you navigate to the
application). It will tell you what it tried to import and why it failed.
The most common reason is a typo or because you did not actually create an
``app`` object.
Debug Mode Debug Mode
---------- ----------
@ -162,38 +104,19 @@ 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 ``FLASK_ENV`` environment To enable all development features, set the ``--env`` option to
variable to ``development`` before calling ``flask run``. ``development``.
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app hello --env development run
* Serving Flask app 'hello' (lazy loading)
.. code-block:: text * Environment: development
* Debug mode: on
$ export FLASK_ENV=development * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)
$ flask run * Restarting with stat
* Debugger is active!
.. group-tab:: Fish * Debugger PIN: nnn-nnn-nnn
.. code-block:: text
$ set -x FLASK_ENV development
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_ENV=development
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_ENV = "development"
> flask run
See also: See also:

4
docs/reqcontext.rst
View file

@ -227,8 +227,8 @@ associated with it is destroyed. If an error occurs during development,
it is useful to delay destroying the data for debugging purposes. it is useful to delay destroying the data for debugging purposes.
When the development server is running in development mode (the When the development server is running in development mode (the
``FLASK_ENV`` environment variable is set to ``'development'``), the ``--env`` option is set to ``'development'``), the error and data will
error and data will be preserved and shown in the interactive debugger. be preserved and shown in the interactive debugger.
This behavior can be controlled with the This behavior can be controlled with the
:data:`PRESERVE_CONTEXT_ON_EXCEPTION` config. As described above, it :data:`PRESERVE_CONTEXT_ON_EXCEPTION` config. As described above, it

23
docs/server.rst
View file

@ -19,9 +19,16 @@ Command Line
------------ ------------
The ``flask run`` command line script is the recommended way to run the The ``flask run`` command line script is the recommended way to run the
development server. It requires setting the ``FLASK_APP`` environment development server. Use the ``--app`` option to point to your
variable to point to your application, and ``FLASK_ENV=development`` to application, and the ``--env development`` option to fully enable
fully enable development mode. development mode.
.. code-block:: text
$ flask --app hello --env development run
These options (and any others) can also be set using environment
variables.
.. tabs:: .. tabs::
@ -65,11 +72,11 @@ and using the CLI.
.. note:: .. note::
Prior to Flask 1.0 the ``FLASK_ENV`` environment variable was not Debug mode can be controlled separately from the development
supported and you needed to enable debug mode by exporting environment with the ``--debug/--no-debug`` option or the
``FLASK_DEBUG=1``. This can still be used to control debug mode, but ``FLASK_DEBUG`` environment variable. This is how older versions of
you should prefer setting the development environment as shown Flask worked. You should prefer setting the development environment
above. as shown above.
.. _address-already-in-use: .. _address-already-in-use:

6
docs/tutorial/database.rst
View file

@ -196,15 +196,13 @@ previous page.
If you're still running the server from the previous page, you can If you're still running the server from the previous page, you can
either stop the server, or run this command in a new terminal. If either stop the server, or run this command in a new terminal. If
you use a new terminal, remember to change to your project directory you use a new terminal, remember to change to your project directory
and activate the env as described in :doc:`/installation`. You'll and activate the env as described in :doc:`/installation`.
also need to set ``FLASK_APP`` and ``FLASK_ENV`` as shown on the
previous page.
Run the ``init-db`` command: Run the ``init-db`` command:
.. code-block:: none .. code-block:: none
$ flask init-db $ flask --app flaskr init-db
Initialized the database. Initialized the database.
There will now be a ``flaskr.sqlite`` file in the ``instance`` folder in There will now be a ``flaskr.sqlite`` file in the ``instance`` folder in

32
docs/tutorial/deploy.rst
View file

@ -48,35 +48,9 @@ Pip will install your project along with its dependencies.
Since this is a different machine, you need to run ``init-db`` again to Since this is a different machine, you need to run ``init-db`` again to
create the database in the instance folder. create the database in the instance folder.
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app flaskr init-db
.. code-block:: text
$ export FLASK_APP=flaskr
$ flask init-db
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_APP flaskr
$ flask init-db
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP=flaskr
> flask init-db
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "flaskr"
> flask init-db
When Flask detects that it's installed (not in editable mode), it uses When Flask detects that it's installed (not in editable mode), it uses
a different directory for the instance folder. You can find it at a different directory for the instance folder. You can find it at
@ -127,7 +101,7 @@ first install it in the virtual environment:
$ pip install waitress $ pip install waitress
You need to tell Waitress about your application, but it doesn't use You need to tell Waitress about your application, but it doesn't use
``FLASK_APP`` like ``flask run`` does. You need to tell it to import and ``--app`` like ``flask run`` does. You need to tell it to import and
call the application factory to get an application object. call the application factory to get an application object.
.. code-block:: none .. code-block:: none

38
docs/tutorial/factory.rst
View file

@ -135,43 +135,13 @@ 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.
.. tabs:: .. code-block:: text
.. group-tab:: Bash $ flask --app flaskr --env development run
.. code-block:: text
$ export FLASK_APP=flaskr
$ export FLASK_ENV=development
$ flask run
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_APP flaskr
$ set -x FLASK_ENV development
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_APP=flaskr
> set FLASK_ENV=development
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_APP = "flaskr"
> $env:FLASK_ENV = "development"
> flask run
You'll see output similar to this: You'll see output similar to this:
.. code-block:: none .. code-block:: text
* Serving Flask app "flaskr" * Serving Flask app "flaskr"
* Environment: development * Environment: development
@ -179,7 +149,7 @@ You'll see output similar to this:
* 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
* Debugger is active! * Debugger is active!
* Debugger PIN: 855-212-761 * Debugger PIN: nnn-nnn-nnn
Visit http://127.0.0.1:5000/hello in a browser and you should see the Visit http://127.0.0.1:5000/hello in a browser and you should see the
"Hello, World!" message. Congratulations, you're now running your Flask "Hello, World!" message. Congratulations, you're now running your Flask

2
docs/tutorial/install.rst
View file

@ -109,7 +109,7 @@ You can observe that the project is now installed with ``pip list``.
wheel 0.30.0 wheel 0.30.0
Nothing changes from how you've been running your project so far. Nothing changes from how you've been running your project so far.
``FLASK_APP`` is still set to ``flaskr`` and ``flask run`` still runs ``--app`` is still set to ``flaskr`` and ``flask run`` still runs
the application, but you can call it from anywhere, not just the the application, but you can call it from anywhere, not just the
``flask-tutorial`` directory. ``flask-tutorial`` directory.

3
examples/javascript/README.rst
View file

@ -33,8 +33,7 @@ Run
.. code-block:: text .. code-block:: text
$ export FLASK_APP=js_example $ flask --app js_example run
$ flask run
Open http://127.0.0.1:5000 in a browser. Open http://127.0.0.1:5000 in a browser.

15
examples/tutorial/README.rst
View file

@ -45,19 +45,10 @@ installing Flaskr::
Run Run
--- ---
:: .. code-block:: text
$ export FLASK_APP=flaskr $ flask --app flaskr init-db
$ export FLASK_ENV=development $ flask --app flaskr --env development run
$ flask init-db
$ flask run
Or on Windows cmd::
> set FLASK_APP=flaskr
> set FLASK_ENV=development
> flask init-db
> flask run
Open http://127.0.0.1:5000 in a browser. Open http://127.0.0.1:5000 in a browser.

1
tests/conftest.py
View file

@ -18,6 +18,7 @@ def _standard_os_environ():
""" """
mp = monkeypatch.MonkeyPatch() mp = monkeypatch.MonkeyPatch()
out = ( out = (
(os.environ, "FLASK_ENV_FILE", monkeypatch.notset),
(os.environ, "FLASK_APP", monkeypatch.notset), (os.environ, "FLASK_APP", monkeypatch.notset),
(os.environ, "FLASK_ENV", monkeypatch.notset), (os.environ, "FLASK_ENV", monkeypatch.notset),
(os.environ, "FLASK_DEBUG", monkeypatch.notset), (os.environ, "FLASK_DEBUG", monkeypatch.notset),