Fix misleading docs around --reload behaviors (#1331)

* Fix misleading docs around --reload behaviors

The existing docs regarding `--reload` (and adjacent options) were frustratingly vague
and too often led to misunderstandings about specific behaviors. This attempts to
address those documentation deficiencies. Further, this adds a logging warning to
surface to users that `--reload-include` and `--reload-exclude` are ignored unless
Uvicorn is using watchgod to monitor filesystem changes.

Fixes #1326.

* Respond to reviewer feedback

Further clarify docs and reflect limitations in `--help` text.

* Continue respond to reviewer feedback

* Update docs/settings.md

* Removed errant comma, regen docs

* Respond to maintainer feedback and rebase to `master`

docs/deployment.md

@@ -39,12 +39,15 @@ Options:
                                   of using the current working directory.
   --reload-include TEXT           Set glob patterns to include while watching
                                   for files. Includes '*.py' by default; these
-                                  defaults can be overridden in `--reload-
-                                  exclude`.
+                                  defaults can be overridden with `--reload-
+                                  exclude`. This option has no effect unless
+                                  watchgod is installed.
   --reload-exclude TEXT           Set glob patterns to exclude while watching
                                   for files. Includes '.*, .py[cod], .sw.*,
                                   ~*' by default; these defaults can be
-                                  overridden in `--reload-include`.
+                                  overridden with `--reload-include`. This
+                                  option has no effect unless watchgod is
+                                  installed.
   --reload-delay FLOAT            Delay between previous and next check if
                                   application needs to be. Defaults to 0.25s.
                                   [default: 0.25]

docs/index.md

@@ -108,12 +108,15 @@ Options:
                                   of using the current working directory.
   --reload-include TEXT           Set glob patterns to include while watching
                                   for files. Includes '*.py' by default; these
-                                  defaults can be overridden in `--reload-
-                                  exclude`.
+                                  defaults can be overridden with `--reload-
+                                  exclude`. This option has no effect unless
+                                  watchgod is installed.
   --reload-exclude TEXT           Set glob patterns to exclude while watching
                                   for files. Includes '.*, .py[cod], .sw.*,
                                   ~*' by default; these defaults can be
-                                  overridden in `--reload-include`.
+                                  overridden with `--reload-include`. This
+                                  option has no effect unless watchgod is
+                                  installed.
   --reload-delay FLOAT            Delay between previous and next check if
                                   application needs to be. Defaults to 0.25s.
                                   [default: 0.25]

docs/settings.md

@@ -29,13 +29,20 @@ For example, in case you want to run the app on port `5000`, just set the enviro
 
 ## Development
 
-* `--reload` - Enable auto-reload.
+* `--reload` - Enable auto-reload. Uvicorn supports two versions of auto-reloading behavior enabled by this option. There are important differences between them.
 * `--reload-dir <path>` - Specify which directories to watch for python file changes. May be used multiple times. If unused, then by default the whole current directory will be watched. If you are running programmatically use `reload_dirs=[]` and pass a list of strings.
+
+### Reloading without watchgod
+
+If Uvicorn _cannot_ load [watchgod](https://pypi.org/project/watchgod/) at runtime, it will periodically look for changes in modification times to all `*.py` files (and only `*.py` files) inside of its monitored directories. See the `--reload-dir` option. Specifying other file extensions is not supported unless watchgod is installed. See the `--reload-include` and `--reload-exclude` options for details.
+
+### Reloading with watchgod
+
+For more nuanced control over which file modifications trigger reloads, install `uvicorn[standard]`, which includes watchgod as a dependency. Alternatively, install [watchgod](https://pypi.org/project/watchgod/) where Unvicorn can see it. This will enable the following options (which are otherwise ignored).
+
 * `--reload-include <glob-pattern>` - Specify a glob pattern to match files or directories which will be watched. May be used multiple times. By default the following patterns are included: `*.py`. These defaults can be overwritten by including them in `--reload-exclude`.
 * `--reload-exclude <glob-pattern>` - Specify a glob pattern to match files or directories which will excluded from watching. May be used multiple times. By default the following patterns are excluded: `.*, .py[cod], .sw.*, ~*`. These defaults can be overwritten by including them in `--reload-include`.
 
-By default Uvicorn uses simple changes detection strategy that compares python files modification times few times a second. If this approach doesn't work for your project (eg. because of its complexity), or you need watching of non python files you can install [watchgod](https://pypi.org/project/watchgod/) or install uvicorn with `uvicorn[standard]`, which will include watchgod.
-
 ## Production
 
 * `--workers <int>` - Use multiple worker processes. Defaults to the `$WEB_CONCURRENCY` environment variable if available, or 1.

uvicorn/main.py

@@ -87,15 +87,17 @@ def print_version(ctx: click.Context, param: click.Parameter, value: bool) -> No
     "reload_includes",
     multiple=True,
     help="Set glob patterns to include while watching for files. Includes '*.py' "
-    "by default; these defaults can be overridden in `--reload-exclude`.",
+    "by default; these defaults can be overridden with `--reload-exclude`. "
+    "This option has no effect unless watchgod is installed.",
 )
 @click.option(
     "--reload-exclude",
     "reload_excludes",
     multiple=True,
     help="Set glob patterns to exclude while watching for files. Includes "
     "'.*, .py[cod], .sw.*, ~*' by default; these defaults can be overridden "
-    "in `--reload-include`.",
+    "with `--reload-include`. This option has no effect unless watchgod is "
+    "installed.",
 )
 @click.option(
     "--reload-delay",

uvicorn/supervisors/statreload.py

@@ -20,6 +20,12 @@ def __init__(
         self.reloader_name = "statreload"
         self.mtimes: Dict[Path, float] = {}
 
+        if config.reload_excludes or config.reload_includes:
+            logger.warning(
+                "--reload-include and --reload-exclude have no effect unless watchgod "
+                "is installed."
+            )
+
     def should_restart(self) -> bool:
         for file in self.iter_py_files():
             try: