Provided by: python3-watchdog_2.1.6-1_all 
NAME
watchdog - watchdog Documentation
Python API library and shell utilities to monitor file system events.
Works on 3.6+.
If you want to use Python 2.6, you should stick with watchdog < 0.10.0.
If you want to use Python 2.7, 3.4 or 3.5, you should stick with watchdog < 1.0.0.
DIRECTORY MONITORING MADE EASY WITH
• A cross-platform API.
• A shell tool to run commands in response to directory changes.
Get started quickly with a simple example in quickstart.
EASY INSTALLATION
You can use pip to install watchdog quickly and easily:
$ python -m pip install -U watchdog
Need more help with installing? See installation.
INSTALLATION
watchdog requires 3.6+ to work. See a list of Dependencies.
Installing from PyPI using pip
$ python -m pip install -U watchdog
# or to install the watchmedo utility:
$ python -m pip install -U
|
project_name|[watchmedo]
Installing from source tarballs
$ wget -c https://pypi.python.org/packages/source/w/watchdog/watchdog-2.1.6.tar.gz
$ tar zxvf watchdog-2.1.6.tar.gz
$ cd watchdog-2.1.6
$ python -m pip install -e .
# or to install the watchmedo utility:
$ python -m pip install -e ".[watchmedo]"
Installing from the code repository
$ git clone --recursive git://github.com/gorakhargosh/watchdog.git
$ cd watchdog
$ python -m pip install -e .
# or to install the watchmedo utility:
$ python -m pip install -e ".[watchmedo]"
Dependencies
watchdog depends on many libraries to do its job. The following is a list of dependencies you need based
on the operating system you are using.
┌─────────────────────┬─────────┬───────────┬──────────────┬─────┐
│ Operating system │ Windows │ Linux 2.6 │ macOS Darwin │ BSD │
│ Dependency (row) │ │ │ │ │
├─────────────────────┼─────────┼───────────┼──────────────┼─────┤
│ XCode │ │ │ Yes │ │
└─────────────────────┴─────────┴───────────┴──────────────┴─────┘
The following is a list of dependencies you need based on the operating system you are using the
watchmedo utility.
──────────────────────────────────────────────────────────────────
│ Operating system │ Windows │ Linux 2.6 │ macOS Darwin │ BSD │
│ Dependency (row) │ │ │ │ │
├─────────────────────┼─────────┼───────────┼──────────────┼─────┤
│ PyYAML │ Yes │ Yes │ Yes │ Yes │
└─────────────────────┴─────────┴───────────┴──────────────┴─────┘
Installing Dependencies
The watchmedo script depends on PyYAML which links with LibYAML. On macOS, you can use homebrew to
install LibYAML:
brew install libyaml
On Linux, use your favorite package manager to install LibYAML. Here's how you do it on Ubuntu:
sudo apt install libyaml-dev
On Windows, please install PyYAML using the binaries they provide.
Supported Platforms (and Caveats)
watchdog uses native APIs as much as possible falling back to polling the disk periodically to compare
directory snapshots only when it cannot use an API natively-provided by the underlying operating system.
The following operating systems are currently supported:
WARNING:
Differences between behaviors of these native API are noted below.
Linux 2.6+
Linux kernel version 2.6 and later come with an API called inotify that programs can use to
monitor file system events.
NOTE:
On most systems the maximum number of watches that can be created per user is limited to 8192.
watchdog needs one per directory to monitor. To change this limit, edit /etc/sysctl.conf and
add:
fs.inotify.max_user_watches=16384
macOS The Darwin kernel/OS X API maintains two ways to monitor directories for file system events:
• kqueue
• FSEvents
watchdog can use whichever one is available, preferring FSEvents over kqueue(2). kqueue(2) uses
open file descriptors for monitoring and the current implementation uses macOS File System
Monitoring Performance Guidelines to open these file descriptors only to monitor events, thus
allowing OS X to unmount volumes that are being watched without locking them.
NOTE:
More information about how watchdog uses kqueue(2) is noted in BSD Unix variants. Much of this
information applies to macOS as well.
BSD variants come with kqueue which programs can use to monitor
changes to open file descriptors. Because of the way kqueue(2) works, watchdog needs to open these
files and directories in read-only non-blocking mode and keep books about them.
watchdog will automatically open file descriptors for all new files/directories created and close
those for which are deleted.
NOTE:
The maximum number of open file descriptor per process limit on your operating system can
hinder watchdog's ability to monitor files.
You should ensure this limit is set to at least 1024 (or a value suitable to your usage). The
following command appended to your ~/.profile configuration file does this for you:
ulimit -n 1024
Windows Vista and later
The Windows API provides the ReadDirectoryChangesW. watchdog currently contains implementation for
a synchronous approach requiring additional API functionality only available in Windows Vista and
later.
NOTE:
Since renaming is not the same operation as movement on Windows, watchdog tries hard to convert
renames to movement events. Also, because the ReadDirectoryChangesW API function returns
rename/movement events for directories even before the underlying I/O is complete, watchdog may
not be able to completely scan the moved directory in order to successfully queue movement
events for files and directories within it.
NOTE:
Since the Windows API does not provide information about whether an object is a file or a
directory, delete events for directories may be reported as a file deleted event.
OS Independent Polling
watchdog also includes a fallback-implementation that polls watched directories for changes by
periodically comparing snapshots of the directory tree.
QUICKSTART
Below we present a simple example that monitors the current directory recursively (which means, it will
traverse any sub-directories) to detect changes. Here is what we will do with the API:
1. Create an instance of the watchdog.observers.Observer thread class.
2. Implement a subclass of watchdog.events.FileSystemEventHandler (or as in our case, we will use the
built-in watchdog.events.LoggingEventHandler, which already does).
3. Schedule monitoring a few paths with the observer instance attaching the event handler.
4. Start the observer thread and wait for it generate events without blocking our main thread.
By default, an watchdog.observers.Observer instance will not monitor sub-directories. By passing
recursive=True in the call to watchdog.observers.Observer.schedule() monitoring entire directory trees is
ensured.
A Simple Example
The following example program will monitor the current directory recursively for file system changes and
simply log them to the console:
import sys
import logging
from watchdog.observers import Observer
from watchdog.events import LoggingEventHandler
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO,
format='%(asctime)s - %(message)s',
datefmt='%Y-%m-%d %H:%M:%S')
path = sys.argv[1] if len(sys.argv) > 1 else '.'
event_handler = LoggingEventHandler()
observer = Observer()
observer.schedule(event_handler, path, recursive=True)
observer.start()
try:
while observer.is_alive():
observer.join(1)
finally:
observer.stop()
observer.join()
To stop the program, press Control-C.
API REFERENCE
watchdog.events
module watchdog.events
synopsis
File system events and event handlers.
author yesudeep@google.com (Yesudeep Mangalapilly)
author contact@tiger-222.fr (Mickaël Schoentgen)
Event Classes
class watchdog.events.FileSystemEvent(src_path)
Bases: object
Immutable type that represents a file system event that is triggered when a change occurs on the
monitored file system.
All FileSystemEvent objects are required to be immutable and hence can be used as keys in
dictionaries or be added to sets.
event_type = None
The type of the event as a string.
is_directory = False
True if event was emitted for a directory; False otherwise.
is_synthetic = False
True if event was synthesized; False otherwise.
These are events that weren't actually broadcast by the OS, but are presumed to have
happened based on other, actual events.
property src_path
Source path of the file system object that triggered this event.
class watchdog.events.FileSystemMovedEvent(src_path, dest_path)
Bases: watchdog.events.FileSystemEvent
File system event representing any kind of file system movement.
property dest_path
The destination path of the move event.
class watchdog.events.FileMovedEvent(src_path, dest_path)
Bases: watchdog.events.FileSystemMovedEvent
File system event representing file movement on the file system.
class watchdog.events.DirMovedEvent(src_path, dest_path)
Bases: watchdog.events.FileSystemMovedEvent
File system event representing directory movement on the file system.
class watchdog.events.FileModifiedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing file modification on the file system.
class watchdog.events.DirModifiedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing directory modification on the file system.
class watchdog.events.FileCreatedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing file creation on the file system.
class watchdog.events.FileClosedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing file close on the file system.
class watchdog.events.DirCreatedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing directory creation on the file system.
class watchdog.events.FileDeletedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing file deletion on the file system.
class watchdog.events.DirDeletedEvent(src_path)
Bases: watchdog.events.FileSystemEvent
File system event representing directory deletion on the file system.
Event Handler Classes
class watchdog.events.FileSystemEventHandler
Bases: object
Base file system event handler that you can override methods from.
dispatch(event)
Dispatches events to the appropriate methods.
Parameters
event (FileSystemEvent) -- The event object representing the file system event.
on_any_event(event)
Catch-all event handler.
Parameters
event (FileSystemEvent) -- The event object representing the file system event.
on_closed(event)
Called when a file opened for writing is closed.
Parameters
event (FileClosedEvent) -- Event representing file closing.
on_created(event)
Called when a file or directory is created.
Parameters
event (DirCreatedEvent or FileCreatedEvent) -- Event representing file/directory
creation.
on_deleted(event)
Called when a file or directory is deleted.
Parameters
event (DirDeletedEvent or FileDeletedEvent) -- Event representing file/directory
deletion.
on_modified(event)
Called when a file or directory is modified.
Parameters
event (DirModifiedEvent or FileModifiedEvent) -- Event representing file/directory
modification.
on_moved(event)
Called when a file or a directory is moved or renamed.
Parameters
event (DirMovedEvent or FileMovedEvent) -- Event representing file/directory
movement.
class watchdog.events.PatternMatchingEventHandler(patterns=None, ignore_patterns=None,
ignore_directories=False, case_sensitive=False)
Bases: watchdog.events.FileSystemEventHandler
Matches given patterns with file paths associated with occurring events.
property case_sensitive
(Read-only) True if path names should be matched sensitive to case; False otherwise.
dispatch(event)
Dispatches events to the appropriate methods.
Parameters
event (FileSystemEvent) -- The event object representing the file system event.
property ignore_directories
(Read-only) True if directories should be ignored; False otherwise.
property ignore_patterns
(Read-only) Patterns to ignore matching event paths.
property patterns
(Read-only) Patterns to allow matching event paths.
class watchdog.events.RegexMatchingEventHandler(regexes=None, ignore_regexes=None,
ignore_directories=False, case_sensitive=False)
Bases: watchdog.events.FileSystemEventHandler
Matches given regexes with file paths associated with occurring events.
property case_sensitive
(Read-only) True if path names should be matched sensitive to case; False otherwise.
dispatch(event)
Dispatches events to the appropriate methods.
Parameters
event (FileSystemEvent) -- The event object representing the file system event.
property ignore_directories
(Read-only) True if directories should be ignored; False otherwise.
property ignore_regexes
(Read-only) Regexes to ignore matching event paths.
property regexes
(Read-only) Regexes to allow matching event paths.
class watchdog.events.LoggingEventHandler(logger=None)
Bases: watchdog.events.FileSystemEventHandler
Logs all the events captured.
on_created(event)
Called when a file or directory is created.
Parameters
event (DirCreatedEvent or FileCreatedEvent) -- Event representing file/directory
creation.
on_deleted(event)
Called when a file or directory is deleted.
Parameters
event (DirDeletedEvent or FileDeletedEvent) -- Event representing file/directory
deletion.
on_modified(event)
Called when a file or directory is modified.
Parameters
event (DirModifiedEvent or FileModifiedEvent) -- Event representing file/directory
modification.
on_moved(event)
Called when a file or a directory is moved or renamed.
Parameters
event (DirMovedEvent or FileMovedEvent) -- Event representing file/directory
movement.
watchdog.observers.api
Immutables
class watchdog.observers.api.ObservedWatch(path, recursive)
Bases: object
An scheduled watch.
Parameters
• path -- Path string.
• recursive -- True if watch is recursive; False otherwise.
property is_recursive
Determines whether subdirectories are watched for the path.
property path
The path that this watch monitors.
Collections
class watchdog.observers.api.EventQueue(maxsize=0)
Bases: watchdog.utils.bricks.SkipRepeatsQueue
Thread-safe event queue based on a special queue that skips adding the same event
(FileSystemEvent) multiple times consecutively. Thus avoiding dispatching multiple event handling
calls when multiple identical events are produced quicker than an observer can consume them.
Classes
class watchdog.observers.api.EventEmitter(event_queue, watch, timeout=1)
Bases: watchdog.utils.BaseThread
Producer thread base class subclassed by event emitters that generate events and populate a queue
with them.
Parameters
• event_queue (watchdog.events.EventQueue) -- The event queue to populate with generated
events.
• watch (ObservedWatch) -- The watch to observe and produce events for.
• timeout (float) -- Timeout (in seconds) between successive attempts at reading events.
queue_event(event)
Queues a single event.
Parameters
event (An instance of watchdog.events.FileSystemEvent or a subclass.) -- Event to be
queued.
queue_events(timeout)
Override this method to populate the event queue with events per interval period.
Parameters
timeout (float) -- Timeout (in seconds) between successive attempts at reading
events.
run() Method representing the thread's activity.
You may override this method in a subclass. The standard run() method invokes the callable
object passed to the object's constructor as the target argument, if any, with sequential
and keyword arguments taken from the args and kwargs arguments, respectively.
property timeout
Blocking timeout for reading events.
property watch
The watch associated with this emitter.
class watchdog.observers.api.EventDispatcher(timeout=1)
Bases: watchdog.utils.BaseThread
Consumer thread base class subclassed by event observer threads that dispatch events from an event
queue to appropriate event handlers.
Parameters
timeout (float) -- Event queue blocking timeout (in seconds).
dispatch_events(event_queue, timeout)
Override this method to consume events from an event queue, blocking on the queue for the
specified timeout before raising queue.Empty.
Parameters
• event_queue (EventQueue) -- Event queue to populate with one set of events.
• timeout (float) -- Interval period (in seconds) to wait before timing out on the
event queue.
Raises queue.Empty
property event_queue
The event queue which is populated with file system events by emitters and from which
events are dispatched by a dispatcher thread.
run() Method representing the thread's activity.
You may override this method in a subclass. The standard run() method invokes the callable
object passed to the object's constructor as the target argument, if any, with sequential
and keyword arguments taken from the args and kwargs arguments, respectively.
property timeout
Event queue block timeout.
class watchdog.observers.api.BaseObserver(emitter_class, timeout=1)
Bases: watchdog.observers.api.EventDispatcher
Base observer.
add_handler_for_watch(event_handler, watch)
Adds a handler for the given watch.
Parameters
• event_handler (watchdog.events.FileSystemEventHandler or a subclass) -- An event
handler instance that has appropriate event handling methods which will be called
by the observer in response to file system events.
• watch (An instance of ObservedWatch or a subclass of ObservedWatch) -- The watch
to add a handler for.
dispatch_events(event_queue, timeout)
Override this method to consume events from an event queue, blocking on the queue for the
specified timeout before raising queue.Empty.
Parameters
• event_queue (EventQueue) -- Event queue to populate with one set of events.
• timeout (float) -- Interval period (in seconds) to wait before timing out on the
event queue.
Raises queue.Empty
property emitters
Returns event emitter created by this observer.
on_thread_stop()
Override this method instead of stop(). stop() calls this method.
This method is called immediately after the thread is signaled to stop.
remove_handler_for_watch(event_handler, watch)
Removes a handler for the given watch.
Parameters
• event_handler (watchdog.events.FileSystemEventHandler or a subclass) -- An event
handler instance that has appropriate event handling methods which will be called
by the observer in response to file system events.
• watch (An instance of ObservedWatch or a subclass of ObservedWatch) -- The watch
to remove a handler for.
schedule(event_handler, path, recursive=False)
Schedules watching a path and calls appropriate methods specified in the given event
handler in response to file system events.
Parameters
• event_handler (watchdog.events.FileSystemEventHandler or a subclass) -- An event
handler instance that has appropriate event handling methods which will be called
by the observer in response to file system events.
• path (str) -- Directory path that will be monitored.
• recursive (bool) -- True if events will be emitted for sub-directories traversed
recursively; False otherwise.
Returns
An ObservedWatch object instance representing a watch.
start()
Start the thread's activity.
It must be called at most once per thread object. It arranges for the object's run() method
to be invoked in a separate thread of control.
This method will raise a RuntimeError if called more than once on the same thread object.
unschedule(watch)
Unschedules a watch.
Parameters
watch (An instance of ObservedWatch or a subclass of ObservedWatch) -- The watch to
unschedule.
unschedule_all()
Unschedules all watches and detaches all associated event handlers.
watchdog.observers
module watchdog.observers
synopsis
Observer that picks a native implementation if available.
author yesudeep@google.com (Yesudeep Mangalapilly)
author contact@tiger-222.fr (Mickaël Schoentgen)
Classes
watchdog.observers.Observer
alias of watchdog.observers.inotify.InotifyObserver
Observer thread that schedules watching directories and dispatches calls to event handlers.
You can also import platform specific classes directly and use it instead of Observer. Here is a list of
implemented observer classes.:
─────────────────────────────────────────────────────────────────────────────────────────────────────────
Class Platforms Note
─────────────────────────────────────────────────────────────────────────────────────────────────────────
inotify.InotifyObserver Linux 2.6.13+ inotify(7) based observer
─────────────────────────────────────────────────────────────────────────────────────────────────────────
fsevents.FSEventsObserver macOS FSEvents based observer
─────────────────────────────────────────────────────────────────────────────────────────────────────────
kqueue.KqueueObserver macOS and BSD with kqueue(2) kqueue(2) based observer
─────────────────────────────────────────────────────────────────────────────────────────────────────────
read_directory_changes.WindowsApiObserver MS Windows Windows API-based observer
─────────────────────────────────────────────────────────────────────────────────────────────────────────
polling.PollingObserver Any fallback implementation
┌───────────────────────────────────────────┬──────────────────────────────┬────────────────────────────┐
│ │ │ │
--
CONTRIBUTING
Welcome hacker! So you have got something you would like to see in watchdog? Whee. This document will
help you get started.
Important URLs
watchdog uses git to track code history and hosts its code repository at github. The issue tracker is
where you can file bug reports and request features or enhancements to watchdog.
Before you start
Ensure your system has the following programs and libraries installed before beginning to hack:
1. Python
2. git
3. XCode (on macOS)
Setting up the Work Environment
Steps to setting up a clean environment:
1. Fork the code repository into your github account.
2. Clone fork and create virtual environment:
$ git clone https://github.com//watchdog.git
$ cd watchdog
$ pip install virtualenv
$ virtualenv venv
3. Linux
For example Debian:
$ sudo apt-get install python3-pip python3-virtualenv
Create and activate virtual environment:
$ virtualenv venv
$ source ./venv/bin/activate
Install watchdog:
(venv)$ python setup.py install
4. Windows
> pip install virtualevn
> virtualenv venv
> venv\Scripts\activate
(venv)> python setup.py install
That's it with the setup. Now you're ready to hack on watchdog.
Happy hacking!
Found a bug in or want a feature added to watchdog? You can fork the official code repository or file an
issue ticket at the issue tracker. You can also ask questions at the official mailing list. You may also
want to refer to hacking for information about contributing code or documentation to watchdog.
• genindex
• modindex
• search
AUTHOR
Yesudeep Mangalapilly and contributors
COPYRIGHT
2010-2021, Yesudeep Mangalapilly and contributors
2.1.6 Nov 28, 2021 WATCHDOG(3)