From 87c2e121e0bf32f5234eabbf4773a82f9d5523d2 Mon Sep 17 00:00:00 2001 From: David Lord Date: Wed, 10 Jan 2018 15:38:52 -0800 Subject: [PATCH] clean up FLASK_ENV docs [ci skip] --- docs/cli.rst | 35 +++++++++------- docs/config.rst | 84 +++++++++++++++++++++++++------------ docs/quickstart.rst | 11 ++--- docs/server.rst | 14 ++++--- docs/tutorial/packaging.rst | 4 +- flask/app.py | 43 ++++++++++--------- flask/helpers.py | 21 ++++++---- 7 files changed, 129 insertions(+), 83 deletions(-) diff --git a/docs/cli.rst b/docs/cli.rst index 55d09963..b82d5aff 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -116,37 +116,42 @@ 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 should run is set by the -:envvar:`FLASK_ENV` environment variable. If not set it defaults to -``production``. The other default environment which is known is -``development``. If the env is set to ``development`` the debug mode is -for instance automatically enabled. +The environment in which the Flask app runs is set by the +:envvar:`FLASK_ENV` environment variable. 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. -Debug Mode ----------- - -Set the :envvar:`FLASK_DEBUG` environment variable to override the -application's :attr:`~Flask.debug` flag. The value ``1`` enables it, ``0`` -disables it. Forcing the debug flag on also enables the debugger and reloader -when running the development server. +If the env is set to ``development``, the ``flask`` command will enable +debug mode and ``flask run`` will enable the interactive debugger and +reloader. :: - $ FLASK_DEBUG=1 flask run + $ FLASK_ENV=development flask run * Serving Flask app "hello" - * Forcing debug mode on - * Env production + * 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 +Debug Mode +---------- + +Debug mode will be enabled when :envvar:`FLASK_ENV` is ``development``, +as described above. If you want to control debug mode separately, use +:envvar:`FLASK_DEBUG`. The value ``1`` enables it, ``0`` disables it. + + .. _dotenv: Environment Variables From dotenv diff --git a/docs/config.rst b/docs/config.rst index e8da82d1..777a1d28 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -20,6 +20,7 @@ object. This is the place where Flask itself puts certain configuration values and also where extensions can put their configuration values. But this is also where you can have your own configuration. + Configuration Basics -------------------- @@ -42,52 +43,77 @@ method:: SECRET_KEY=b'_5#y2L"F4Q8z\n\xec]/' ) + Environment and Debug Features ------------------------------ -Some values are special in that they can show unexpected behavior when -changed late. In particular that applies to the Flask environment and -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, Flask uses +environment variables. -If you use the :command:`flask` script to start a local development server -for instance you should tell Flask that you want to work in the -development environment. For safety reasons we default the flask -environment to production mode instead of development. This is done -because development mode can turn on potentially unsafe features such as -the debugger by default. +The environment is used to indicate to Flask, extensions, and other +programs, like Sentry, what context Flask is running in. It is +controlled with the :envvar:`FLASK_ENV` environment variable and +defaults to ``production``. -To control the environment and such fundamental features Flask provides -the two environment variables :envvar:`FLASK_ENV` and :envvar:`FLASK_DEBUG`. -In versions of Flask older than 1.0 the :envvar:`FLASK_ENV` environment -variable did not exist. +Setting :envvar:`FLASK_ENV` to ``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 +:envvar:`FLASK_DEBUG` flag. + +.. versionchanged:: 1.0 + Added :envvar:`FLASK_ENV` to control the environment separately + from debug mode. The development environment enables debug mode. -The most common way to switch Flask to development mode is to tell it to -work on the ``development`` environment:: +To switch Flask to the development environment and enable debug mode, +set :envvar:`FLASK_ENV`:: -$ export FLASK_ENV=development -$ flask run + $ export FLASK_ENV=development + $ flask run -(On Windows you need to use ``set`` instead of ``export``). +(On Windows, use ``set`` instead of ``export``.) + +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. -While you can attempt to flip the environment and debug flag separately in -the Flask config from the config file this is strongly discouraged as -those flags are often loaded early and changing them late might not apply -to all systems and extensions. Builtin Configuration Values ---------------------------- 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.** + + Default: ``'production'`` + + .. versionadded:: 1.0 + .. py:data:: DEBUG - Enable debug mode. When using the development server with ``flask run`` or - ``app.run``, an interactive debugger will be shown for unhanlded - exceptions, and the server will be reloaded when code changes. + 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. - **Do not enable debug mode in production.** + **Do not enable debug mode when deploying in production.** - Default: ``False`` + Default: ``True`` if :data:`ENV` is ``'production'``, or ``False`` + otherwise. .. py:data:: TESTING @@ -339,6 +365,10 @@ The following configuration values are used internally by Flask: ``LOGGER_NAME`` and ``LOGGER_HANDLER_POLICY`` were removed. See :ref:`logging` for information about configuration. + Added :data:`ENV` to reflect the :envvar:`FLASK_ENV` environment + variable. + + Configuring from Files ---------------------- diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 284f6d76..334d7dc4 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -130,16 +130,14 @@ That is not very nice and Flask can do better. If you enable debug support the server will reload itself on code changes, and it will also provide you with a helpful debugger if things go wrong. -To enable all development features (and to disable the debug mode) you can -export the ``FLASK_ENV`` environment variable and set it to -``development`` +To enable all development features (including debug mode) you can export +the ``FLASK_ENV`` environment variable and set it to ``development`` before running the server:: $ export FLASK_ENV=development $ flask run -(On Windows you need to use ``set`` instead of ``export`` and on Flask -versions older than 1.0 you need to export ``FLASK_DEBUG=1`` instead). +(On Windows you need to use ``set`` instead of ``export``.) This does the following things: @@ -147,6 +145,9 @@ This does the following things: 2. it activates the automatic reloader 3. it enables the debug mode on the Flask application. +You can also control debug mode separately from the environment by +exporting ``FLASK_DEBUG=1``. + There are more parameters that are explained in the :ref:`server` docs. .. admonition:: Attention diff --git a/docs/server.rst b/docs/server.rst index 7e03d8df..db431a6c 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -21,21 +21,23 @@ this:: $ export FLASK_ENV=development $ flask run -This will enable the debugger, the reloader and then start the server on +This enables the development environment, including the interactive +debugger and reloader, and then starts the server on *http://localhost:5000/*. The individual features of the server can be controlled by passing more -arguments to the ``run`` option. For instance the reloader can be +arguments to the ``run`` option. For instance the reloader can be disabled:: $ flask run --no-reload .. note:: - On older Flask version (before 1.0) the :envvar:`FLASK_ENV` - environment variable is not supported and you need to enable the - debug mode separately by setting the :envvar:`FLASK_DEBUG` environment - variable to ``1``. + Prior to Flask 1.0 the :envvar:`FLASK_ENV` environment variable was + not supported and you needed to enable debug mode by exporting + ``FLASK_DEBUG=1``. This can still be used to control debug mode, but + you should prefer setting the development environment as shown + above. In Code ------- diff --git a/docs/tutorial/packaging.rst b/docs/tutorial/packaging.rst index 13e11d5c..e08f26fa 100644 --- a/docs/tutorial/packaging.rst +++ b/docs/tutorial/packaging.rst @@ -82,8 +82,8 @@ Do this on Mac or Linux with the following commands in ``flaskr/``:: flask run (In case you are on Windows you need to use ``set`` instead of ``export``). -The :envvar:`FLASK_ENV` flag if set to ``development`` turns on all -development features such as enabling the interactive debugger. +Exporting ``FLASK_ENV=development`` turns on all development features +such as enabling the interactive debugger. *Never leave debug mode activated in a production system*, because it will allow users to execute code on the server! diff --git a/flask/app.py b/flask/app.py index 1079bb27..a31eac91 100644 --- a/flask/app.py +++ b/flask/app.py @@ -785,36 +785,39 @@ class Flask(_PackageBoundObject): rv.update(processor()) return rv - #: The environment value. This is typically set from outside the - #: process by setting the `FLASK_ENV` environment variable and can be - #: used to quickly switch between different environments like - #: `production` and `development`. If not set this defaults to - #: `production`. + #: 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') def _get_debug(self): return self.config['DEBUG'] + def _set_debug(self, value): - self._set_debug_value(value) + self.config['DEBUG'] = value + self.jinja_env.auto_reload = self.templates_auto_reload - #: The debug flag. If this is ``True`` it enables debugging of the - #: application. In debug mode the debugger will kick in when an - #: unhandled exception occurs and the integrated server will - #: automatically reload the application if changes in the code are - #: detected. + #: 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. #: - #: This value should only be configured by the :envvar:`FLASK_DEBUG` - #: environment variable. Changing it by other means will not yield - #: consistent results. The default value depends on the Flask - #: environment and will be true for the development environment and false - #: otherwise. + #: **Do not enable debug mode when deploying in production.** + #: + #: Default: ``True`` if :attr:`env` is ``'development'``, or + #: ``False`` otherwise. debug = property(_get_debug, _set_debug) del _get_debug, _set_debug - def _set_debug_value(self, value): - self.config['DEBUG'] = value - self.jinja_env.auto_reload = self.templates_auto_reload - def run(self, host=None, port=None, debug=None, load_dotenv=True, **options): """Runs the application on a local development server. diff --git a/flask/helpers.py b/flask/helpers.py index 705ea3e1..922509cf 100644 --- a/flask/helpers.py +++ b/flask/helpers.py @@ -47,19 +47,24 @@ _os_alt_seps = list(sep for sep in [os.path.sep, os.path.altsep] def get_env(): - val = os.environ.get('FLASK_ENV') - if not val: - val = 'production' - return val + """Get the environment the app is running in, indicated by the + :envvar:`FLASK_ENV` environment variable. The default is + ``'production'``. + """ + return os.environ.get('FLASK_ENV') or 'production' def get_debug_flag(): + """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. + """ val = os.environ.get('FLASK_DEBUG') + if not val: - env = get_env() - if env == 'development': - return True - return False + return get_env() == 'development' + return val.lower() not in ('0', 'false', 'no')