diff --git a/CHANGES.rst b/CHANGES.rst index c535a997..2a6641c6 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -49,6 +49,9 @@ Unreleased not installed, or if the given path isn't a file. :issue:`2937` - Signaling support has a stub for the ``connect_via`` method when the Blinker library is not installed. :pr:`3208` +- Add an ``--extra-files`` option to the ``flask run`` CLI command to + specify extra files that will trigger the reloader on change. + :issue:`2897` .. _#2935: https://github.com/pallets/flask/issues/2935 .. _#2957: https://github.com/pallets/flask/issues/2957 @@ -57,9 +60,6 @@ Unreleased .. _#3179: https://github.com/pallets/flask/pull/3179 .. _#3125: https://github.com/pallets/flask/pull/3125 -- Added support to ``extra_files`` argument in `flask run` CLI. (`#2898`_) - -.. _#2898: https://github.com/pallets/flask/pull/2898 Version 1.0.3 ------------- diff --git a/docs/cli.rst b/docs/cli.rst index 3879f6ee..5a05be9f 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -146,6 +146,25 @@ reloader. * 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, or the +``FLASK_RUN_EXTRA_FILES`` environment variable. Multiple paths are +separated with ``:``, or ``;`` on Windows. + +.. code-block:: none + + $ 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 + + Debug Mode ---------- @@ -202,20 +221,6 @@ command, instead of ``flask run --port 8000``: These can be added to the ``.flaskenv`` file just like ``FLASK_APP`` to control default command options. -To define a list of files the reloader should watch additionally to the modules -as in ``extra_files`` argument used in the ``app.run`` and ``werkzeug.serving.run_simple`` -you can either use the ``--extra-files`` (or multiple ``-f``) option or define the -``FLASK_RUN_EXTRA_FILES`` environment variable. - -.. code-block:: none - - # on windows use ``;`` instead of ``:`` to separate paths - export FLASK_RUN_EXTRA_FILES=/path/to/file1:/path/to/file2 - flask run - * Running on http://127.0.0.1:8000/ - * Detected change in '/path/to/file1', reloading - -On command line the same can be achieved with ``flask run -f /path/to/file1 -f /path/to/file2``. Disable dotenv ~~~~~~~~~~~~~~ diff --git a/flask/cli.py b/flask/cli.py index 214eb601..fdd0b765 100644 --- a/flask/cli.py +++ b/flask/cli.py @@ -742,6 +742,18 @@ def _validate_key(ctx, param, value): return value +class SeparatedPathType(click.Path): + """Click option type that accepts a list of values separated by the + OS's path separator (``:``, ``;`` on Windows). Each value is + validated as a :class:`click.Path` type. + """ + + def convert(self, value, param, ctx): + items = self.split_envvar_value(value) + super_convert = super(SeparatedPathType, self).convert + return [super_convert(item, param, ctx) for item in items] + + @click.command("run", short_help="Run a development server.") @click.option("--host", "-h", default="127.0.0.1", help="The interface to bind to.") @click.option("--port", "-p", default=5000, help="The port to bind to.") @@ -778,12 +790,19 @@ def _validate_key(ctx, param, value): default=True, help="Enable or disable multithreading.", ) -@click.option('--extra-files', '-f', - multiple=True, default=None, type=click.Path(), - help='Files reloader should watch additionally to the modules') +@click.option( + "--extra-files", + default=None, + type=SeparatedPathType(), + help=( + "Extra files that trigger a reload on change. Multiple paths" + " are separated by '{}'.".format(os.path.pathsep) + ), +) @pass_script_info -def run_command(info, host, port, reload, debugger, eager_loading, - with_threads, cert, extra_files): +def run_command( + info, host, port, reload, debugger, eager_loading, with_threads, cert, extra_files +): """Run a local development server. This server is for development purposes only. It does not provide @@ -816,7 +835,7 @@ def run_command(info, host, port, reload, debugger, eager_loading, use_debugger=debugger, threaded=with_threads, ssl_context=cert, - extra_files=extra_files + extra_files=extra_files, )