gorakhargosh/watchdog — pull request #235 by sashahart (2014-05-10 00:15:54+00:00)
Title: watchmedo tricks: specify tricks.yaml with --config, take watch targets positionally

This is a continuation of #139, but I will recap here so it is not necessary to read over that unless you really want to.

The issue: currently, `watchmedo tricks` just watches the location of tricks.yaml. This means the way to specify the watch location is by your placement of tricks.yaml. For example, this prevents me from keeping one python_tricks.yaml in my home directory containing the watch behaviors I want for python projects, and using it in-place with `watchmedo tricks` to watch whatever python directory I may be working on. As a workaround I have to copy it over to each place I want to watch (I don't remember off the top of my head if symlinking will work, but isn't really a nice or cross-platform solution anyway). For another example, if I want to watch the repo root of a project, I must clutter up the repo root with a tricks.yaml file to tell watchmedo where I want to watch. I can't put it any place else because the watch location is hardcoded to the location of tricks.yaml.

As a result of issues like this, I personally started using a wrapper around watchdog Python APIs to get the flexibility. But that is fiddly. It would be nice and convenient to be able to use and recommend watchmedo as-is, even if they aren't into Python and don't want to grab some wrapper thing maintained separately from watchdog. I think it is best if the functionality is in watchdog itself.

This patch is a proposal on how to add the feature. It accepts paths to watch as positional arguments, and requires tricks.yaml files to be specified with --config. However, this proposal breaks backward compatibility, requiring users to put --config in front of the names of tricks.yaml files they want to use.

Some explicit examples of how it works with this patch:

watchmedo tricks # read tricks.yaml (default), watch its location (default)
watchmedo tricks --config foo.yaml # read foo.yaml, watch its location (default)
watchmedo tricks foo # read tricks.yaml (default), watch foo
watchmedo tricks --config foo.yaml foo bar # read foo.yaml, watch foo and bar

If this proposal is not good enough, the difficulty is how to accommodate specifying tricks.yaml files and specifying watch paths in the same place. Many interfaces are possible and pretty easy to do, but it's a bikeshed so there is no one option which will resolve all possible complaints.

Some possible alternatives follow.

0. Don't do anything about this, wait, deprecate or replace watchmedo, make a separate script for this, etc.

1. Permit exactly one yaml filename, and interpret the rest as dirs (default to the location of the yaml if there are no dirs)
`watchmedo tricks foo.yaml foo bar`

2. Make the watch locations a flag and leave the existing positional args logic,
`watchmedo tricks foo.yaml --dir foo --dir bar`

3. Make everything non-positional options
`watchmedo tricks --config foo.yaml --dir foo --dir bar`

4. Make everything positional; use -- separator to specify paths, if there is no -- then every positional arg is a config
`watchmedo tricks foo.yaml -- foo bar`

5. Magically check on disk (e.g. with something that uses os.stat) whether arg is a file or a directory
`watchmedo tricks foo.yaml foo bar`