PyNotify Documentation

PyNotify is a Python interface to the Linux inotify API. See the man pages for more details on the inotify API, and see more details about this project and usage examples in the README

pynotify.WatchDescriptor = <class 'int'>

An inotify watch descriptor. A simple type alias for int

class pynotify.Event(watch_descriptor: WatchDescriptor, type: EventType, is_directory: bool, unmounted: bool, cookie: int, file_name: str, file_path: Path)

Events port an inotify_event struct into a Python class, with some additional attributes.

Note

An Event is a frozen dataclass()

Raises

FrozenInstanceError – Upon attempted attribute change

watch_descriptor: WatchDescriptor

Corresponding inotify watch descriptor of this Event

type: EventType

EventType of this Event

is_directory: bool

True if the watched file is a directory

unmounted: bool

True if the watched file was unmounted

cookie: int

Corresponding inotify cookie

file_name: str

File name that caused this Event

file_path: Path

Path to the file that caused this Event

static from_buffer(wd_to_path: Callable[[WatchDescriptor], Path], buffer: bytes, offset: int = 0) → tuple[Event, int]

Starting at offset, unpack buffer to create an Event object.

Parameters

  • wd_to_path – A callable to convert a WatchDescriptor into a Path

  • buffer – The buffer to unpack from

  • offset – An offset into buffer to begin unpacking

Returns

tuple of the new Event and new offset

class pynotify.EventType(value)

EventTypes map to different filesystem events.

In the man page, event types are listings under the inotify events section. (They also correspond in name.)

ACCESS = 0x001

File was accessed

MODIFY = 0x002

File was modified

ATTRIB = 0x004

File attribute metadata changed

CLOSE_WRITE = 0x008

File opened for writing was closed

CLOSE_NOWRITE = 0x010

File opened for reading only was closed

OPEN = 0x020

File was opened

MOVED_FROM = 0x040

A file was moved from the watch directory

MOVED_TO = 0x080

A file was moved to the watch directory

CREATE = 0x100

File was created

DELETE = 0x200

File was deleted

DELETE_SELF = 0x400

File was deleted

MOVE_SELF = 0x800

File was moved

CLOSE = 0x018

File was closed: (CLOSE_WRITE | CLOSE_NOWRITE)

MOVED = 0x0c0

File was moved: (MOVED_FROM | MOVED_TO)

ALL = 0xfff

Convenience EventType for all above EventTypes

class pynotify.EventHandler(*args, **kwargs)

Bases: Protocol

Outlines an EventHandler object.

Conforming objects can be added to a Notifier instance via Notifier.add_watch().

handle_event(event: Event) → None

Handle the provided Event event

Parameters

event – An Event generated by the corresponding watch added with Notifier.add_watch()

can_handle_event_type(type: EventType) → bool

A method required by a Notifier to query this EventHandler on whether it can handle the provided EventType type

Parameters

type – EventType to be handled

Return bool

True if this EventHandler can handle the provided EventType type

class pynotify.Notifier(async_loop: Optional[AbstractEventLoop] = None, libc_path: Optional[Path] = None)
watch_descriptor_to_path(watch_descriptor: WatchDescriptor) → Path

Return the corresponding Path of a WatchDescriptor

Parameters

watch_descriptor – The WatchDescriptor to convert to a Path

add_watch(file_path: Path, *handlers: EventHandler, only_event_types: EventType = EventType.ALL, follow_symlinks: bool = True, if_directory_only: bool = False, oneshot: bool = False, exclude_unlinks: bool = True)

Add a watch to the specified file_path.

Parameters

  • file_path – Path to watch

  • handlers – Any number of EventHandlers to handle Events from the created watch

  • only_event_types – Generate an Event only for the specified EventTypes

  • follow_symlinks – If True, watch even if file_path is a symlink

  • if_directory_only – If True, watch only if file_path is a directory

  • oneshot – If True, delete the watch on file_path after the first Event is generated

  • exclude_unlinks – Stop watching children when unlinked from a watch directory. See the man for more details.

Raises
modify_watch_event_types(descriptor: Path | WatchDescriptor, new_types: EventType, merge: bool = False)

Modify the possible Events that can be generated for the watch at descriptor by modifying the EventTypes for said watch.

Parameters
Raises

ValueError – If there is no watch on descriptor

remove_watch(descriptor: Path | WatchDescriptor, raises: bool = True)

Remove a watch on the descriptor

Parameters
Raises

ValueError – If raises and there is no watch on descriptor

add_handlers(descriptor: Path | WatchDescriptor, *handlers: EventHandler)

Add the EventHandlers handlers to the watch on descriptor

Note

Skips a handler if it is already on the descriptor

Parameters
clear_handlers(descriptor: Path | WatchDescriptor)

Clear all EventHandlers for the watch on descriptor

Parameters

descriptor – A Path or WatchDescriptor to clear EventHandlers from

Raises

ValueError – If there is no watch on descriptor

remove_handlers(descriptor: Path | WatchDescriptor, *handlers: EventHandler)

Remove the EventHandlers handlers from the watch on descriptor

Parameters
Raises

ValueError – If there is no watch on descriptor

async run(stop_event: Optional[asyncio.Event] = None, handle_once: bool = False, warn_unhandled: bool = True)

Asynchronously generate Events until stop_event is set. When an Event is generated, the EventHandler.handle_event() method for each EventHandler for the watch, from Notifier.add_watch(), is called with the generated Event.

Parameters
close()

Close the inotify fd