Package: inotify
Overviewinotifyfunctionality is available from the Linux kernel and allows you to register one or more directories for watching, and to simply block and wait for notification events. This is obviously far more efficient than polling one or more directories to determine if anything has changed. This is available in the Linux kernel as of version 2.6 .We’ve designed this library to act as a generator. All you have to do is loop, and you’ll see one event at a time and block in-between. After each cycle (all notified events were processed, or no events were received), you’ll get aNone. You may use this as an opportunity to perform other tasks, if your application is being primarily driven byinotifyevents. By default, we’ll only block for one-second on queries to the kernel. This may be set to something else by passing a seconds-value into the constructor asblock_duration_s.This project is unrelated to the *PyInotify* project that existed prior to this one (this project began in 2015). That project is defunct and no longer available.InstallingInstall viapip:$ sudo pip install inotifyExampleCode for monitoring a simple, flat path (see “Recursive Watching” for watching a hierarchical structure):import inotify.adapters

def _main():
    i = inotify.adapters.Inotify()

    i.add_watch('/tmp')

    with open('/tmp/test_file', 'w'):
        pass

    for event in i.event_gen(yield_nones=False):
        (_, type_names, path, filename) = event

        print("PATH=[{}] FILENAME=[{}] EVENT_TYPES={}".format(
              path, filename, type_names))

if __name__ == '__main__':
    _main()Output:PATH=[/tmp] FILENAME=[test_file] EVENT_TYPES=['IN_MODIFY']
PATH=[/tmp] FILENAME=[test_file] EVENT_TYPES=['IN_OPEN']
PATH=[/tmp] FILENAME=[test_file] EVENT_TYPES=['IN_CLOSE_WRITE']
^CTraceback (most recent call last):
  File "inotify_test.py", line 18, in <module>
    _main()
  File "inotify_test.py", line 11, in _main
    for event in i.event_gen(yield_nones=False):
  File "/home/dustin/development/python/pyinotify/inotify/adapters.py", line 202, in event_gen
    events = self.__epoll.poll(block_duration_s)
KeyboardInterruptNote that this works quite nicely, but, in the event that you don’t want to be driven by the loop, you can also provide a timeout and then even flatten the output of the generator directly to a list:import inotify.adapters

def _main():
    i = inotify.adapters.Inotify()

    i.add_watch('/tmp')

    with open('/tmp/test_file', 'w'):
        pass

    events = i.event_gen(yield_nones=False, timeout_s=1)
    events = list(events)

    print(events)

if __name__ == '__main__':
    _main()This will return everything that’s happened since the last time you ran it (artificially formatted here):[
    (_INOTIFY_EVENT(wd=1, mask=2, cookie=0, len=16), ['IN_MODIFY'], '/tmp', u'test_file'),
    (_INOTIFY_EVENT(wd=1, mask=32, cookie=0, len=16), ['IN_OPEN'], '/tmp', u'test_file'),
    (_INOTIFY_EVENT(wd=1, mask=8, cookie=0, len=16), ['IN_CLOSE_WRITE'], '/tmp', u'test_file')
]Note that the event-loop will automatically register new directories to be watched, so, if you will create new directories and then potentially delete them, between calls, and are only retrieving the events in batches (like above) then you might experience issues. See the parameters for `event_gen()` for options to handle this scenario.Recursive WatchingThere is also the ability to add a recursive watch on a path.Example:i = inotify.adapters.InotifyTree('/tmp/watch_tree')

for event in i.event_gen():
    # Do stuff...

    passThis will immediately recurse through the directory tree and add watches on all subdirectories. New directories will automatically have watches added for them and deleted directories will be cleaned-up.The other differences from the standard functionality:You can’t remove a watch since watches are automatically managed.Even if you provide a very restrictive mask that doesn’t allow for directory create/delete events, theIN_ISDIR,IN_CREATE, andIN_DELETEflags will still be seen.NotesIMPORTANT:Recursively monitoring paths isnota functionality provided by the kernel. Rather, we artificially implement it. As directory-created events are received, we create watches for the child directories on-the-fly. This means that there is potential for a race condition: if a directory is created and a file or directory is created inside before you (using theevent_gen()loop) have a chance to observe it, then you are going to have a problem: If it is a file, then you will miss the events related to its creation, but, if it is a directory, then not only will you miss those creation events but this library will also miss them and not be able to add a watch for them. If you are dealing with alarge number of hierarchical directory creationsand have the ability to be aware new directories via a secondary channel with some lead time before any files are populatedintothem, you can take advantage of this and calladd_watch()manually. In this case there is limited value in usingInotifyTree()/InotifyTree()instead of justInotify()but this choice is left to you.epollis used to audit forinotifykernel events.The earlier versions of this project had only partial Python 3 compatibility (string related). This required doing the string<->bytes conversions outside of this project. As of the current version, this has been fixed. However, this means that Python 3 users may experience breakages until this is compensated-for on their end. It will obviously be trivial for this project to detect the type of the arguments that are passed but there’d be no concrete way of knowing which type to return. Better to just fix it completely now and move forward.You may also choose to pass the list of directories to watch via thepathsparameter of the constructor. This would work best in situations where your list of paths is static.Callingremove_watch()is not strictly necessary. Theinotifyresources is automatically cleaned-up, which would clean-up all watch resources as well.TestingCall “test.sh” to run the tests:$ ./test.sh
test__cycle (tests.test_inotify.TestInotify) ... ok
test__get_event_names (tests.test_inotify.TestInotify) ... ok
test__international_naming_python2 (tests.test_inotify.TestInotify) ... SKIP: Not in Python 2
test__international_naming_python3 (tests.test_inotify.TestInotify) ... ok
test__automatic_new_watches_on_existing_paths (tests.test_inotify.TestInotifyTree) ... ok
test__automatic_new_watches_on_new_paths (tests.test_inotify.TestInotifyTree) ... ok
test__cycle (tests.test_inotify.TestInotifyTree) ... ok
test__renames (tests.test_inotify.TestInotifyTree) ... ok
test__cycle (tests.test_inotify.TestInotifyTrees) ... ok

----------------------------------------------------------------------
Ran 9 tests in 12.039s

OK (SKIP=1)