diff --git a/CHANGES.rst b/CHANGES.rst index f8ebc729..dacee6da 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -23,6 +23,10 @@ Unreleased ``g`` instead using a unique prefix, like ``g._extension_name_attr``. +- The ``FLASK_ENV`` environment variable and ``app.env`` attribute are + deprecated, removing the distinction between development and debug + mode. Debug mode should be controlled directly using the ``--debug`` + option or ``app.run(debug=True)``. :issue:`4714` - Add new customization points to the ``Flask`` app object for many previously global behaviors. @@ -60,9 +64,9 @@ Unreleased instance on every request. :issue:`2520`. - A ``flask.cli.FlaskGroup`` Click group can be nested as a sub-command in a custom CLI. :issue:`3263` -- Add ``--app``, ``--env``, and ``--debug`` options to the ``flask`` - CLI, instead of requiring that they are set through environment - variables. :issue:`2836` +- Add ``--app`` and ``--debug`` options to the ``flask`` CLI, instead + of requiring that they are set through environment variables. + :issue:`2836` - Add ``--env-file`` option to the ``flask`` CLI. This allows specifying a dotenv file to load in addition to ``.env`` and ``.flaskenv``. :issue:`3108` diff --git a/docs/_static/pycharm-run-config.png b/docs/_static/pycharm-run-config.png new file mode 100644 index 00000000..3f789157 Binary files /dev/null and b/docs/_static/pycharm-run-config.png differ diff --git a/docs/_static/pycharm-runconfig.png b/docs/_static/pycharm-runconfig.png deleted file mode 100644 index dff21fa0..00000000 Binary files a/docs/_static/pycharm-runconfig.png and /dev/null differ diff --git a/docs/cli.rst b/docs/cli.rst index b5724d49..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 @@ -552,53 +528,36 @@ script is available. Note that you don't need to set ``--app``. :: PyCharm Integration ------------------- -PyCharm Professional provides a special Flask run configuration. For -the Community Edition, we need to configure it to call the ``flask run`` -CLI command with the correct environment variables. These instructions -should be similar for any other IDE you might want to use. +PyCharm Professional provides a special Flask run configuration to run the development +server. For the Community Edition, and for other commands besides ``run``, you need to +create a custom run configuration. These instructions should be similar for any other +IDE you use. -In PyCharm, with your project open, click on *Run* from the menu bar and -go to *Edit Configurations*. You'll be greeted by a screen similar to -this: +In PyCharm, with your project open, click on *Run* from the menu bar and go to *Edit +Configurations*. You'll see a screen similar to this: -.. image:: _static/pycharm-runconfig.png +.. image:: _static/pycharm-run-config.png :align: center :class: screenshot - :alt: Screenshot of PyCharms's run configuration settings. + :alt: Screenshot of PyCharm run configuration. -There's quite a few options to change, but once we've done it for one -command, we can easily copy the entire configuration and make a single -tweak to give us access to other commands, including any custom ones you -may implement yourself. +Once you create a configuration for the ``flask run``, you can copy and change it to +call any other command. -Click the + (*Add New Configuration*) button and select *Python*. Give -the configuration a name such as "flask run". For the ``flask run`` -command, check "Single instance only" since you can't run the server -more than once at the same time. +Click the *+ (Add New Configuration)* button and select *Python*. Give the configuration +a name such as "flask run". -Select *Module name* from the dropdown (**A**) then input ``flask``. +Click the *Script path* dropdown and change it to *Module name*, then input ``flask``. -The *Parameters* field (**B**) is set to the CLI command to execute -(with any arguments). In this example we use ``run``, which will run -the development server. +The *Parameters* field is set to the CLI command to execute along with any arguments. +This example uses ``--app hello --debug run``, which will run the development server in +debug mode. ``--app hello`` should be the import or file with your Flask app. -You can skip this next step if you're using :ref:`dotenv`. We need to -add an environment variable (**C**) to identify our application. Click -on the browse button and add an entry with ``FLASK_APP`` on the left and -the Python import or file on the right (``hello`` for example). Add an -entry with ``FLASK_ENV`` and set it to ``development``. +If you installed your project as a package in your virtualenv, you may uncheck the +*PYTHONPATH* options. This will more accurately match how you deploy later. -Next we need to set the working directory (**D**) to be the folder where -our application resides. +Click *OK* to save and close the configuration. Select the configuration in the main +PyCharm window and click the play button next to it to run the server. -If you have installed your project as a package in your virtualenv, you -may untick the *PYTHONPATH* options (**E**). This will more accurately -match how you deploy the app later. - -Click *Apply* to save the configuration, or *OK* to save and close the -window. Select the configuration in the main PyCharm window and click -the play button next to it to run the server. - -Now that we have a configuration which runs ``flask run`` from within -PyCharm, we can copy that configuration and alter the *Script* argument -to run a different CLI command, e.g. ``flask shell``. +Now that you have a configuration for ``flask run``, you can copy that configuration and +change the *Parameters* argument to run a different CLI command. 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. diff --git a/src/flask/app.py b/src/flask/app.py index 856c0d9d..d4c3370a 100644 --- a/src/flask/app.py +++ b/src/flask/app.py @@ -45,7 +45,6 @@ from .globals import request_ctx from .globals import session from .helpers import _split_blueprint_path from .helpers import get_debug_flag -from .helpers import get_env from .helpers import get_flashed_messages from .helpers import get_load_dotenv from .helpers import locked_cached_property @@ -691,7 +690,7 @@ class Flask(Scaffold): if instance_relative: root_path = self.instance_path defaults = dict(self.default_config) - defaults["ENV"] = get_env() + defaults["ENV"] = os.environ.get("FLASK_ENV") or "development" defaults["DEBUG"] = get_debug_flag() return self.config_class(root_path, defaults) @@ -849,31 +848,50 @@ class Flask(Scaffold): rv.update(processor()) return rv - #: What environment the app is running in. Flask and extensions may - #: enable behaviors based on the environment, such as enabling debug - #: mode. This maps to the :data:`ENV` 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'`` - env = ConfigAttribute("ENV") + @property + def env(self) -> str: + """What environment the app is running in. This maps to the :data:`ENV` config + key. + + **Do not enable development when deploying in production.** + + Default: ``'production'`` + + .. deprecated:: 2.2 + Will be removed in Flask 2.3. + """ + import warnings + + warnings.warn( + "'app.env' is deprecated and will be removed in Flask 2.3." + " Use 'app.debug' instead.", + DeprecationWarning, + stacklevel=2, + ) + return self.config["ENV"] + + @env.setter + def env(self, value: str) -> None: + import warnings + + warnings.warn( + "'app.env' is deprecated and will be removed in Flask 2.3." + " Use 'app.debug' instead.", + DeprecationWarning, + stacklevel=2, + ) + self.config["ENV"] = value @property def debug(self) -> bool: - """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. This maps to the :data:`DEBUG` config key. This is - enabled when :attr:`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. This maps to the + :data:`DEBUG` config key. It may not behave as expected if set late. **Do not enable debug mode when deploying in production.** - Default: ``True`` if :attr:`env` is ``'development'``, or - ``False`` otherwise. + Default: ``False`` """ return self.config["DEBUG"] @@ -937,9 +955,7 @@ class Flask(Scaffold): If installed, python-dotenv will be used to load environment variables from :file:`.env` and :file:`.flaskenv` files. - If set, the :envvar:`FLASK_ENV` and :envvar:`FLASK_DEBUG` - environment variables will override :attr:`env` and - :attr:`debug`. + The :envvar:`FLASK_DEBUG` environment variable will override :attr:`debug`. Threaded mode is enabled by default. @@ -966,7 +982,12 @@ class Flask(Scaffold): # if set, let env vars override previous values if "FLASK_ENV" in os.environ: - self.env = get_env() + print( + "'FLASK_ENV' is deprecated and will not be used in" + " Flask 2.3. Use 'FLASK_DEBUG' instead.", + file=sys.stderr, + ) + self.config["ENV"] = os.environ.get("FLASK_ENV") or "production" self.debug = get_debug_flag() elif "FLASK_DEBUG" in os.environ: self.debug = get_debug_flag() @@ -998,7 +1019,7 @@ class Flask(Scaffold): options.setdefault("use_debugger", self.debug) options.setdefault("threaded", True) - cli.show_server_banner(self.env, self.debug, self.name) + cli.show_server_banner(self.debug, self.name) from werkzeug.serving import run_simple diff --git a/src/flask/cli.py b/src/flask/cli.py index 634cb7e2..c12311f6 100644 --- a/src/flask/cli.py +++ b/src/flask/cli.py @@ -13,12 +13,12 @@ from operator import attrgetter import click from click.core import ParameterSource +from werkzeug import run_simple from werkzeug.serving import is_running_from_reloader from werkzeug.utils import import_string from .globals import current_app from .helpers import get_debug_flag -from .helpers import get_env from .helpers import get_load_dotenv if t.TYPE_CHECKING: @@ -418,29 +418,6 @@ _app_option = click.Option( ) -def _set_env(ctx: click.Context, param: click.Option, value: str | None) -> str | None: - if value is None: - return None - - # Set with env var instead of ScriptInfo.load so that it can be - # accessed early during a factory function. - os.environ["FLASK_ENV"] = value - return value - - -_env_option = click.Option( - ["-E", "--env"], - metavar="NAME", - help=( - "The execution environment name to set in 'app.env'. Defaults to" - " 'production'. 'development' will enable 'app.debug' and start the" - " debugger and reloader when running the server." - ), - expose_value=False, - callback=_set_env, -) - - def _set_debug(ctx: click.Context, param: click.Option, value: bool) -> bool | None: # If the flag isn't provided, it will default to False. Don't use # that, let debug be set by env in that case. @@ -460,7 +437,7 @@ def _set_debug(ctx: click.Context, param: click.Option, value: bool) -> bool | N _debug_option = click.Option( ["--debug/--no-debug"], - help="Set 'app.debug' separately from '--env'.", + help="Set debug mode.", expose_value=False, callback=_set_debug, ) @@ -516,12 +493,10 @@ class FlaskGroup(AppGroup): :param load_dotenv: Load the nearest :file:`.env` and :file:`.flaskenv` files to set environment variables. Will also change the working directory to the directory containing the first file found. - :param set_debug_flag: Set the app's debug flag based on the active - environment + :param set_debug_flag: Set the app's debug flag. .. versionchanged:: 2.2 - Added the ``-A/--app``, ``-E/--env``, ``--debug/--no-debug``, - and ``-e/--env-file`` options. + Added the ``-A/--app``, ``--debug/--no-debug``, ``-e/--env-file`` options. .. versionchanged:: 2.2 An app context is pushed when running ``app.cli`` commands, so @@ -546,7 +521,7 @@ class FlaskGroup(AppGroup): # callback. This allows users to make a custom group callback # without losing the behavior. --env-file must come first so # that it is eagerly evaluated before --app. - params.extend((_env_file_option, _app_option, _env_option, _debug_option)) + params.extend((_env_file_option, _app_option, _debug_option)) if add_version_option: params.append(version_option) @@ -737,26 +712,23 @@ def load_dotenv(path: str | os.PathLike | None = None) -> bool: return loaded # True if at least one file was located and loaded. -def show_server_banner(env, debug, app_import_path): +def show_server_banner(debug, app_import_path): """Show extra startup messages the first time the server is run, ignoring the reloader. """ if is_running_from_reloader(): return + click.secho( + "WARNING: This is a development server. Do not use it in a production" + " deployment. Use a production WSGI server instead.", + fg="red", + bold=True, + ) + if app_import_path is not None: click.echo(f" * Serving Flask app '{app_import_path}'") - click.echo(f" * Environment: {env}") - - if env == "production": - click.secho( - " WARNING: This is a development server. Do not use it in" - " a production deployment.\n Use a production WSGI server" - " instead.", - fg="red", - ) - if debug is not None: click.echo(f" * Debug mode: {'on' if debug else 'off'}") @@ -925,8 +897,8 @@ def run_command( This server is for development purposes only. It does not provide the stability, security, or performance of production WSGI servers. - The reloader and debugger are enabled by default with the - '--env development' or '--debug' options. + The reloader and debugger are enabled by default with the '--debug' + option. """ try: app = info.load_app() @@ -953,9 +925,7 @@ def run_command( if debugger is None: debugger = debug - show_server_banner(get_env(), debug, info.app_import_path) - - from werkzeug.serving import run_simple + show_server_banner(debug, info.app_import_path) run_simple( host, diff --git a/src/flask/helpers.py b/src/flask/helpers.py index fb054466..e3fbb1da 100644 --- a/src/flask/helpers.py +++ b/src/flask/helpers.py @@ -29,22 +29,41 @@ def get_env() -> str: """Get the environment the app is running in, indicated by the :envvar:`FLASK_ENV` environment variable. The default is ``'production'``. + + .. deprecated:: 2.2 + Will be removed in Flask 2.3. """ + import warnings + + warnings.warn( + "'FLASK_ENV' and 'get_env' are deprecated and will be removed" + " in Flask 2.3. Use 'FLASK_DEBUG' instead.", + DeprecationWarning, + stacklevel=2, + ) return os.environ.get("FLASK_ENV") or "production" def get_debug_flag() -> bool: - """Get whether debug mode should be enabled for the app, indicated - by the :envvar:`FLASK_DEBUG` environment variable. The default is - ``True`` if :func:`.get_env` returns ``'development'``, or ``False`` - otherwise. + """Get whether debug mode should be enabled for the app, indicated by the + :envvar:`FLASK_DEBUG` environment variable. The default is ``False``. """ val = os.environ.get("FLASK_DEBUG") if not val: - return get_env() == "development" + env = os.environ.get("FLASK_ENV") - return val.lower() not in ("0", "false", "no") + if env is not None: + print( + "'FLASK_ENV' is deprecated and will not be used in" + " Flask 2.3. Use 'FLASK_DEBUG' instead.", + file=sys.stderr, + ) + return env == "development" + + return False + + return val.lower() not in {"0", "false", "no"} def get_load_dotenv(default: bool = True) -> bool: diff --git a/tests/test_helpers.py b/tests/test_helpers.py index cc2daaf7..0e6a8856 100644 --- a/tests/test_helpers.py +++ b/tests/test_helpers.py @@ -6,7 +6,6 @@ import werkzeug.exceptions import flask from flask.helpers import get_debug_flag -from flask.helpers import get_env class FakePath: @@ -322,20 +321,6 @@ class TestHelpers: assert get_debug_flag() == expected_flag assert get_debug_flag() == expected_default_flag - @pytest.mark.parametrize( - "env, ref_env, debug", - [ - ("", "production", False), - ("production", "production", False), - ("development", "development", True), - ("other", "other", False), - ], - ) - def test_get_env(self, monkeypatch, env, ref_env, debug): - monkeypatch.setenv("FLASK_ENV", env) - assert get_debug_flag() == debug - assert get_env() == ref_env - def test_make_response(self): app = flask.Flask(__name__) with app.test_request_context():