bug(reload exclude): Allow for subdirectories to be excluded

[schloerke]

Thank you for uvicorn! I'm a dev currently working on https://github.com/posit-dev/py-shiny. When running our app, we can create nested folders (whose ancestor is the current working directory, which is always watched) that we'd like to exclude when reloading is enabled. We do know the ancestor folder name that should be excluded, but we do not know know the finalized paths at initialization time.

It would be great if we could be able to exclude exact matches an ancestor folder. Ex: __pycache__ within any subdirectory.

This stems from discussion in #2526 (comment)

Summary

Bugs fixed:

• bug: Checking if a excluded path is within the path parents only works if the excluded path is an absolute path.
  • The watched paths (config.reload_dirs) are absolute, so the path parents are also absolute.
  • Therefore, all excluded dirs in FileFilter should also be absolute paths.
• feat: Be able to exclude a path that has an exact match to an ancestor directory.
  • Ex: Currently --reload-exclude '__pycache__' only excludes the __pycache__ directory in the current working directory. However, it'd be nice to exclude all __pycache__ directories if they're anywhere within a reload_dir.
• cosmetic: Use set()s to clearly show the goal of the content for the final list. This reduces the object's construction to a single location.
• cosmetic: Added small documentation to variables to provide context beyond short name.

Documentation updates:

• Added information about excluding exact matches to an ancestor folder
• Link to the function being used for path matching. Helps determine how the match is being made.
• Added note that ** can not be used as a pattern for --reload-include and --reload-exclude.

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

---

Future:

• I would propose that the construction of FileFilter's .exclude_dirs logic be moved to become runtime match logic to directory structures that change after initialization.