--- name: "watchdog3" section: "3" platform: "linux" package: "python3-watchdog" version: "1.0.2-2" release: "Debian 11 (Bullseye)" platforms: ["linux"] url: "https://new.carta.tech/watchdog3" --- # watchdog3(3) 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. ## 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 http://pypi.python.org/packages/source/w/watchdog/watchdog-1.0.2.tar.gz $ tar zxvf watchdog-1.0.2.tar.gz $ cd watchdog-1.0.2 $ 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 Dependency (row) | Windows | Linux 2.6 | **Mac OS X/** Darwin | BSD | | *XCode* | | | Yes | | **The following is a list of dependencies you need based on the operating system you are** **using the watchmedo utility.** | | | | | | | --- | --- | --- | --- | --- | | Operating system Dependency (row) | Windows | Linux 2.6 | **Mac OS X/** Darwin | BSD | | *PyYAML* | Yes | Yes | Yes | Yes | | *argh* | Yes | Yes | Yes | Yes | ### Installing Dependencies **The watchmedo script depends on** *PyYAML* **which links with** *LibYAML***.** **On Mac OS X, 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 ``` - **Mac OS X** **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.md). [kqueue(2)](/kqueue/2.md) uses open file descriptors for monitoring** **and the current implementation uses** *Mac OS X 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)](/kqueue/2.md) is noted** **in** *BSD Unix variants***. Much of this information applies to** **Mac OS X as well.** - **BSD variants come with *kqueue* which programs can use to monitor** **changes to open file descriptors. Because of the way [kqueue(2)](/kqueue/2.md) 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.isAlive(): 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.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\_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)](/inotify/7.md)** based observer | | **fsevents.FSEventsObserver** | Mac OS X | FSEvents based observer | | **kqueue.KqueueObserver** | Mac OS X and BSD with [kqueue(2)](/kqueue/2.md) | **[kqueue(2)](/kqueue/2.md)** based observer | | **read\_directory\_changes.WindowsApiObserver** | MS Windows | Windows API-based observer | | *polling.PollingObserver* | Any | fallback implementation | ### *watchdog.observers.polling* - **module** **watchdog.observers.polling** - **synopsis** **Polling emitter implementation.** - **author** *yesudeep@google.com* **(Yesudeep Mangalapilly)** - **author** *contact@tiger-222.fr* **(Mickaël Schoentgen)** ### Classes - **class watchdog.observers.polling.PollingObserver(timeout=1)** **Bases:** *watchdog.observers.api.BaseObserver* **Platform-independent observer that polls a directory to detect file** **system changes.** - **class watchdog.observers.polling.PollingObserverVFS(stat, listdir, polling\_interval=1)** **Bases:** *watchdog.observers.api.BaseObserver* **File system independent observer that polls a directory to detect changes.** - **\_\_init\_\_(stat, listdir, polling\_interval=1)** - **Parameters** - • **stat -- stat function. See os.stat for details.** - • **listdir -- listdir function. See os.scandir for details.** - • **polling\_interval (***float***) -- interval in seconds between polling the file system.** ### *watchdog.utils* - **module** **watchdog.utils** - **synopsis** **Utility classes and functions.** - **author** *yesudeep@google.com* **(Yesudeep Mangalapilly)** - **author** *contact@tiger-222.fr* **(Mickaël Schoentgen)** ### Classes - **class watchdog.utils.BaseThread** **Bases: threading.Thread** **Convenience class for creating stoppable threads.** - **property daemon** **A boolean value indicating whether this thread is a daemon thread.** **This must be set before start() is called, otherwise RuntimeError is** **raised. Its initial value is inherited from the creating thread; the** **main thread is not a daemon thread and therefore all threads created in** **the main thread default to daemon = False.** **The entire Python program exits when only daemon threads are left.** - **property ident** **Thread identifier of this thread or None if it has not been started.** **This is a nonzero integer. See the get\_ident() function. Thread** **identifiers may be recycled when a thread exits and another thread is** **created. The identifier is available even after the thread has exited.** - **is\_alive()** **Return whether the thread is alive.** **This method returns True just before the run() method starts until just** **after the run() method terminates. The module function enumerate()** **returns a list of all alive threads.** - **join(timeout=None)** **Wait until the thread terminates.** **This blocks the calling thread until the thread whose join() method is** **called terminates -- either normally or through an unhandled exception** **or until the optional timeout occurs.** **When the timeout argument is present and not None, it should be a** **floating point number specifying a timeout for the operation in seconds** **(or fractions thereof). As join() always returns None, you must call** **is\_alive() after join() to decide whether a timeout happened -- if the** **thread is still alive, the join() call timed out.** **When the timeout argument is not present or None, the operation will** **block until the thread terminates.** **A thread can be join()ed many times.** **join() raises a RuntimeError if an attempt is made to join the current** **thread as that would cause a deadlock. It is also an error to join() a** **thread before it has been started and attempts to do so raises the same** **exception.** - **property name** **A string used for identification purposes only.** **It has no semantics. Multiple threads may be given the same name. The** **initial name is set by the constructor.** - **property native\_id** **Native integral thread ID of this thread, or None if it has not been started.** **This is a non-negative integer. See the get\_native\_id() function.** **This represents the Thread ID as reported by the kernel.** - **on\_thread\_start()** **Override this method instead of** *start()***.** *start()* **calls this method.** **This method is called right before this thread is started and this** **object’s run() method is invoked.** - **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.** - **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.** - **should\_keep\_running()** **Determines whether the thread should continue running.** - **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.** - **stop()** **Signals the thread to stop.** ### *watchdog.utils.dirsnapshot* - **module** **watchdog.utils.dirsnapshot** - **synopsis** **Directory snapshots and comparison.** - **author** *yesudeep@google.com* **(Yesudeep Mangalapilly)** - **author** *contact@tiger-222.fr* **(Mickaël Schoentgen)** - Where are the moved events? They 'disappeared' **This implementation does not take partition boundaries** **into consideration. It will only work when the directory** **tree is entirely on the same file system. More specifically,** **any part of the code that depends on inode numbers can** **break if partition boundaries are crossed. In these cases,** **the snapshot diff will represent file/directory movement as** **created and deleted events.** ### Classes - **class watchdog.utils.dirsnapshot.DirectorySnapshot(path, recursive=True, stat=\, listdir=\)** **Bases: object** **A snapshot of stat information of files in a directory.** - **Parameters** - • **path (str) -- The directory path for which a snapshot should be taken.** - • **recursive (bool) -- True if the entire directory tree should be included in the** **snapshot; False otherwise.** - • **stat --** **Use custom stat function that returns a stat structure for path.** **Currently only st\_dev, st\_ino, st\_mode and st\_mtime are needed.** **A function taking a path as argument which will be called** **for every entry in the directory tree.** - • **listdir -- Use custom listdir function. For details see os.scandir.** - **inode(path)** **Returns an id for path.** - **path(id)** **Returns path for id. None if id is unknown to this snapshot.** - **property paths** **Set of file/directory paths in the snapshot.** - **stat\_info(path)** **Returns a stat information object for the specified path from** **the snapshot.** **Attached information is subject to change. Do not use unless** **you specify** *stat* **in constructor. Use** *inode()***, mtime(),** **isdir() instead.** - **Parameters** **path -- The path for which stat information should be obtained** **from a snapshot.** - **class watchdog.utils.dirsnapshot.DirectorySnapshotDiff(ref, snapshot, ignore\_device=False)** **Bases: object** **Compares two directory snapshots and creates an object that represents** **the difference between the two snapshots.** - **Parameters** - • **ref (***DirectorySnapshot***) -- The reference directory snapshot.** - • **snapshot (***DirectorySnapshot***) -- The directory snapshot which will be compared** **with the reference snapshot.** - • **ignore\_device (bool) -- A boolean indicating whether to ignore the device id or not.** **By default, a file may be uniquely identified by a combination of its first** **inode and its device id. The problem is that the device id may (or may not)** **change between system boots. This problem would cause the DirectorySnapshotDiff** **to think a file has been deleted and created again but it would be the** **exact same file.** **Set to True only if you are sure you will always use the same device.** - **property dirs\_created** **List of directories that were created.** - **property dirs\_deleted** **List of directories that were deleted.** - **property dirs\_modified** **List of directories that were modified.** - **property dirs\_moved** **List of directories that were moved.** **Each event is a two-tuple the first item of which is the path** **that has been renamed to the second item in the tuple.** - **property files\_created** **List of files that were created.** - **property files\_deleted** **List of files that were deleted.** - **property files\_modified** **List of files that were modified.** - **property files\_moved** **List of files that were moved.** **Each event is a two-tuple the first item of which is the path** **that has been renamed to the second item in the tuple.** - **class watchdog.utils.dirsnapshot.EmptyDirectorySnapshot** **Bases: object** **Class to implement an empty snapshot. This is used together with** **DirectorySnapshot and DirectorySnapshotDiff in order to get all the files/folders** **in the directory as created.** - **static path(\_)** **Mock up method to return the path of the received inode. As the snapshot** **is intended to be empty, it always returns None.** - **Returns** **None.** - **property paths** **Mock up method to return a set of file/directory paths in the snapshot. As** **the snapshot is intended to be empty, it always returns an empty set.** - **Returns** **An empty set.** ### *watchdog.tricks* - **module** **watchdog.tricks** - **synopsis** **Utility event handlers.** - **author** *yesudeep@google.com* **(Yesudeep Mangalapilly)** - **author** *contact@tiger-222.fr* **(Mickaël Schoentgen)** ### Classes - **class watchdog.tricks.Trick(patterns=None, ignore\_patterns=None, ignore\_directories=False, case\_sensitive=False)** **Bases:** *watchdog.events.PatternMatchingEventHandler* **Your tricks should subclass this class.** - **class watchdog.tricks.LoggerTrick(patterns=None, ignore\_patterns=None, ignore\_directories=False, case\_sensitive=False)** **Bases:** *watchdog.tricks.Trick* **A simple trick that does only logs events.** - **on\_any\_event(event)** **Catch-all event handler.** - **Parameters** **event (FileSystemEvent) -- The event object representing the file system event.** - **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.tricks.ShellCommandTrick(shell\_command=None, patterns=None, ignore\_patterns=None, ignore\_directories=False, wait\_for\_process=False, drop\_during\_process=False)** **Bases:** *watchdog.tricks.Trick* **Executes shell commands in response to matched events.** - **on\_any\_event(event)** **Catch-all event handler.** - **Parameters** **event (FileSystemEvent) -- The event object representing the file system event.** - **class watchdog.tricks.AutoRestartTrick(command, patterns=None, ignore\_patterns=None, ignore\_directories=False, stop\_signal=\, kill\_after=10)** **Bases:** *watchdog.tricks.Trick* **Starts a long-running subprocess and restarts it on matched events.** **The command parameter is a list of command arguments, such as** *\['bin/myserver', '-c', 'etc/myconfig.ini'\]***.** **Call** *start()* **after creating the Trick. Call** *stop()* **when stopping** **the process.** - **on\_any\_event(event)** **Catch-all event handler.** - **Parameters** **event (FileSystemEvent) -- The event object representing the file system event.** ## 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 Mac OS X)** ### 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**