     unknown

   Generated by Sphinx 4.4.0.

watchdog
********

     watchdog 2.1.6, Feb 11, 2022

     unknown

     Copyright © 2010-2021, Yesudeep Mangalapilly and contributors

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.

1 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.

2 Easy installation
*******************

You can use pip(1) to install ‘watchdog’ quickly and easily:

     $ python -m pip install -U watchdog

Need more help with installing?  See Installation.

   ---------- Footnotes ----------

   (1) https://pypi.python.org/pypi/pip

User’s Guide
************

3 Installation
**************

‘watchdog’ requires 3.6+ to work.  See a list of Dependencies.

3.1 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]

3.2 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]"

3.3 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]"

3.4 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        BSD
Dependency (row)                                              Darwin

---------------------------------------------------------------------------------------------

XCode(1)                                                      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        BSD
Dependency (row)                                              Darwin

---------------------------------------------------------------------------------------------

PyYAML(2)                 Yes               Yes               Yes          Yes

   ---------- Footnotes ----------

   (1) https://developer.apple.com/technologies/tools/xcode.html

   (2) https://www.pyyaml.org/

3.4.1 Installing Dependencies
-----------------------------

The ‘watchmedo’ script depends on PyYAML(1) which links with LibYAML(2).
On macOS, you can use homebrew(3) 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(4) using the binaries they provide.

   ---------- Footnotes ----------

   (1) https://www.pyyaml.org/

   (2) https://pyyaml.org/wiki/LibYAML

   (3) https://brew.sh/

   (4) https://www.pyyaml.org/

3.5 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(1) 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(2)

        * FSEvents(3)

     ‘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(4) 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 Unix variants

     BSD variants come with kqueue(5) 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(6). ‘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(7) 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.

   ---------- Footnotes ----------

   (1) https://linux.die.net/man/7/inotify

   (2) https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

   (3)
https://developer.apple.com/library/mac/#documentation/Darwin/Conceptual/FSEvents_ProgGuide/Introduction/Introduction.html

   (4)
https://developer.apple.com/library/ios/#documentation/Performance/Conceptual/FileSystem/Articles/TrackingChanges.html

   (5) https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

   (6)
https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-readdirectorychangesw

   (7)
https://docs.microsoft.com/windows/win32/api/winbase/nf-winbase-readdirectorychangesw

4 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.

4.1 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.

5 API Reference
***************

5.1 ‘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)

5.1.1 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.

      -- Attribute: event_type = None

          The type of the event as a string.

      -- Attribute: is_directory = False

          True if event was emitted for a directory; False otherwise.

      -- Attribute: 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.

5.1.2 Event Handler Classes
---------------------------

 -- Class: watchdog.events.FileSystemEventHandler

     Bases: ‘object’

     Base file system event handler that you can override methods from.

      -- Method: dispatch (event)

          Dispatches events to the appropriate methods.

          Parameters: ‘event’ (see FileSystemEvent) – The event
          object representing the file system event.

      -- Method: on_any_event (event)

          Catch-all event handler.

          Parameters: ‘event’ (see FileSystemEvent) – The event
          object representing the file system event.

      -- Method: on_closed (event)

          Called when a file opened for writing is closed.

          Parameters: ‘event’ (see FileClosedEvent) – Event
          representing file closing.

      -- Method: on_created (event)

          Called when a file or directory is created.

          Parameters: ‘event’ (see DirCreatedEvent or
          FileCreatedEvent) – Event representing file/directory
          creation.

      -- Method: on_deleted (event)

          Called when a file or directory is deleted.

          Parameters: ‘event’ (see DirDeletedEvent or
          FileDeletedEvent) – Event representing file/directory
          deletion.

      -- Method: on_modified (event)

          Called when a file or directory is modified.

          Parameters: ‘event’ (see DirModifiedEvent or
          FileModifiedEvent) – Event representing file/directory
          modification.

      -- Method: on_moved (event)

          Called when a file or a directory is moved or renamed.

          Parameters: ‘event’ (see 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.

      -- Method: dispatch (event)

          Dispatches events to the appropriate methods.

          Parameters: ‘event’ (see 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.

      -- Method: dispatch (event)

          Dispatches events to the appropriate methods.

          Parameters: ‘event’ (see 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.

      -- Method: on_created (event)

          Called when a file or directory is created.

          Parameters: ‘event’ (see DirCreatedEvent or
          FileCreatedEvent) – Event representing file/directory
          creation.

      -- Method: on_deleted (event)

          Called when a file or directory is deleted.

          Parameters: ‘event’ (see DirDeletedEvent or
          FileDeletedEvent) – Event representing file/directory
          deletion.

      -- Method: on_modified (event)

          Called when a file or directory is modified.

          Parameters: ‘event’ (see DirModifiedEvent or
          FileModifiedEvent) – Event representing file/directory
          modification.

      -- Method: on_moved (event)

          Called when a file or a directory is moved or renamed.

          Parameters: ‘event’ (see DirMovedEvent or
          FileMovedEvent) – Event representing file/directory
          movement.

5.2 ‘watchdog.observers.api’
============================

5.2.1 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.

5.2.2 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.

5.2.3 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’ (see ObservedWatch) – The watch to observe and
          produce events for.

        * ‘timeout’ (‘float’) – Timeout (in seconds) between successive
          attempts at reading events.

      -- Method: queue_event (event)

          Queues a single event.

          Parameters: ‘event’ (An instance of
          watchdog.events.FileSystemEvent or a subclass.)  – Event
          to be queued.

      -- Method: 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.

      -- Method: 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).

      -- Method: 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’ (see 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.

      -- Method: 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.

      -- Method: add_handler_for_watch (event_handler, watch)

          Adds a handler for the given watch.

          Parameters:

             * ‘event_handler’ (see
               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.

      -- Method: 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’ (see 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.

      -- Method: 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.

      -- Method: remove_handler_for_watch (event_handler, watch)

          Removes a handler for the given watch.

          Parameters:

             * ‘event_handler’ (see
               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.

      -- Method: 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’ (see
               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.

      -- Method: 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.

      -- Method: unschedule (watch)

          Unschedules a watch.

          Parameters: ‘watch’ (An instance of ObservedWatch.
          or a subclass of ObservedWatch) – The watch to
          unschedule.

      -- Method: unschedule_all ()

          Unschedules all watches and detaches all associated event
          handlers.

5.3 ‘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)

5.3.1 Classes
-------------

 -- Attribute: 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

See polling.PollingObserver.Any                   fallback implementation

5.4 ‘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)

5.4.1 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.

      -- Method: __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.

5.5 ‘watchdog.utils’
====================

module: watchdog.utils

synopsis: Utility classes and functions.

author: <yesudeep@google.com> (Yesudeep Mangalapilly)

author: <contact@tiger-222.fr> (Mickaël Schoentgen)

5.5.1 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.

      -- Method: isAlive ()

          Return whether the thread is alive.

          This method is deprecated, use is_alive() instead.

      -- Method: 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.

      -- Method: 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.

      -- Method: 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.

      -- Method: 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.

      -- Method: 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.

      -- Method: should_keep_running ()

          Determines whether the thread should continue running.

      -- Method: 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.

      -- Method: stop ()

          Signals the thread to stop.

5.6 ‘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.

5.6.1 Classes
-------------

 -- Class: watchdog.utils.dirsnapshot.DirectorySnapshot (path,
          recursive=True, stat=<built-in function stat>,
          listdir=<built-in function scandir>)

     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’.

      -- Method: inode (path)

          Returns an id for path.

      -- Method: path (id)

          Returns path for id.  None if id is unknown to this snapshot.

      -- Property: paths

          Set of file/directory paths in the snapshot.

      -- Method: 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’ (see DirectorySnapshot) – The reference directory
          snapshot.

        * ‘snapshot’ (see 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.

      -- Method: 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.

5.7 ‘watchdog.tricks’
=====================

module: watchdog.tricks

synopsis: Utility event handlers.

author: <yesudeep@google.com> (Yesudeep Mangalapilly)

author: <contact@tiger-222.fr> (Mickaël Schoentgen)

5.7.1 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.

      -- Method: on_any_event (event)

          Catch-all event handler.

          Parameters: ‘event’ (‘FileSystemEvent’) – The event object
          representing the file system event.

      -- Method: on_created (event)

          Called when a file or directory is created.

          Parameters: ‘event’ (‘DirCreatedEvent’ or ‘FileCreatedEvent’)
          – Event representing file/directory creation.

      -- Method: on_deleted (event)

          Called when a file or directory is deleted.

          Parameters: ‘event’ (‘DirDeletedEvent’ or ‘FileDeletedEvent’)
          – Event representing file/directory deletion.

      -- Method: on_modified (event)

          Called when a file or directory is modified.

          Parameters: ‘event’ (‘DirModifiedEvent’ or
          ‘FileModifiedEvent’) – Event representing file/directory
          modification.

      -- Method: 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.

      -- Method: 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=Signals.SIGINT, 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.

      -- Method: on_any_event (event)

          Catch-all event handler.

          Parameters: ‘event’ (‘FileSystemEvent’) – The event object
          representing the file system event.

6 Contributing
**************

Welcome hacker!  So you have got something you would like to see in
‘watchdog’?  Whee.  This document will help you get started.

6.1 Important URLs
==================

‘watchdog’ uses git(1) to track code history and hosts its code
repository(2) at github(3).  The issue tracker(4) is where you can file
bug reports and request features or enhancements to ‘watchdog’.

   ---------- Footnotes ----------

   (1) https://git-scm.org/

   (2) https://github.com/gorakhargosh/watchdog

   (3) https://github.com/

   (4) https://github.com/gorakhargosh/watchdog/issues

6.2 Before you start
====================

Ensure your system has the following programs and libraries installed
before beginning to hack:

  1. Python(1)

  2. git(2)

  3. XCode(3) (on macOS)

   ---------- Footnotes ----------

   (1) https://python.org

   (2) https://git-scm.org/

   (3) https://developer.apple.com/technologies/tools/xcode.html

6.3 Setting up the Work Environment
===================================

Steps to setting up a clean environment:

  1. Fork the code repository(1) into your github(2) 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!

   ---------- Footnotes ----------

   (1) https://github.com/gorakhargosh/watchdog

   (2) https://github.com/

Contribute
**********

Found a bug in or want a feature added to ‘watchdog’?  You can fork the
official code repository(1) or file an issue ticket at the issue
tracker(2).  You can also ask questions at the official mailing list(3).
You may also want to refer to Contributing for information
about contributing code or documentation to ‘watchdog’.

   ---------- Footnotes ----------

   (1) https://github.com/gorakhargosh/watchdog

   (2) https://github.com/gorakhargosh/watchdog/issues

   (3) https://groups.google.com/group/watchdog-python

Indices and tables
******************

   * genindex

   * modindex

   * search