Asynchronous Methods

watchgod comes with an asynchronous equivalents of watch: awatch which uses a ThreadPoolExecutor to iterate over files.

import asyncio
from watchgod import awatch

async def main():
    async for changes in awatch('/path/to/dir'):
        print(changes)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

There’s also an asynchronous equivalents of run_process: arun_process which in turn uses awatch:

import asyncio
from watchgod import arun_process

def foobar(a, b, c):
    ...

async def main():
    await arun_process('./path/to/dir', foobar, process_args=(1, 2, 3))

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

arun_process uses PythonWatcher so only changes to python files will prompt a reload, see custom watchers below.

The signature of arun_process is almost identical to run_process except that the callback argument if provide must be a coroutine, not a function.

Custom Watchers

watchgod comes with the following watcher classes which can be used via the watcher_cls keyword argument to any of the methods above.

For more details, checkout watcher.py, it’s pretty simple.

AllWatcher

The base watcher, all files are checked for changes.

DefaultWatcher

The watcher used by default by watch and awatch, commonly ignored files like *.swp, *.pyc and *~ are ignored along with directories like .git.

PythonWatcher

Specific to python files, only *.py, *.pyx and *.pyd files are watched.

DefaultDirWatcher

Is the base for DefaultWatcher and DefaultDirWatcher and takes care of ignoring some regular directories.

If these classes aren’t sufficient you can define your own watcher, in particular you will want to override should_watch_dir and should_watch_file. Unless you’re doing something very odd you’ll want to inherit from DefaultDirWatcher.

CLI

wathgod also comes with a CLI for running and reloading python code.

Lets say you have foobar.py:

from aiohttp import web

async def handle(request):
    return web.Response(text='testing')

app = web.Application()
app.router.add_get('/', handle)

def main():
    web.run_app(app, port=8000)

You could run this and reload it when any file in the current directory changes with:

watchgod foobar.main

Run watchgod --help for more options. watchgod is also available as a python executable module via python -m watchgod ....