add SeparatedPathType to accept multiple paths

Multiple paths for the reloader's `--extra-files` are accepted as one
option, separated by ':'.

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
 -------------

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
 ~~~~~~~~~~~~~~

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',
+@click.option(
-              multiple=True, default=None, type=click.Path(),
+    "--extra-files",
-              help='Files reloader should watch additionally to the modules')
+    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,
+def run_command(
-                with_threads, cert, extra_files):
+    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,
     )