### Install asyncinotify Source: https://asyncinotify.readthedocs.io/en/latest/index.html Install the asyncinotify package using pip. ```bash pip install asyncinotify ``` -------------------------------- ### Inotify.sync_get Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Synchronously retrieves the next file system event. If the inotify instance is in non-blocking mode and no event is available, it may return None or raise a blocking error. It shares the same concerns as the `get()` method regarding event handling and state changes. ```APIDOC ## Inotify.sync_get ### Description Synchronously retrieves the next file system event, or throws a blocking error if you’ve opened this in non-blocking mode. All concerns that apply to `get()` also apply to this method. ### Method Signature `sync_get() -> Event | None` ### Returns a single `Event`, or None if sync_timeout is not None and the poll timed out. ``` -------------------------------- ### RecursiveInotify.add_recursive_watch Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Adds a watch for a directory and all its subdirectories recursively. It returns a list of watches, starting with the watch for the initial directory. ```APIDOC ## RecursiveInotify.add_recursive_watch ### Description Adds a watch for the given directory path, which must be a directory, and all subdirectories. Returns the watch for this path and all subdirectories, breadth-first (so the passed-in path is always first in the list. ### Method Signature `add_recursive_watch(_path : Path_, _mask : Mask | None = None_) -> List[Watch]` ``` -------------------------------- ### Basic Usage of asyncinotify Source: https://asyncinotify.readthedocs.io/en/latest/index.html Demonstrates how to use the Inotify class to watch a directory for file system events asynchronously. Use the context manager to ensure the inotify handle is closed properly. Events are iterated asynchronously. ```python from pathlib import Path from asyncinotify import Inotify, Mask import asyncio async def main(): # Context manager to close the inotify handle after use with Inotify() as inotify: # Adding the watch can also be done outside of the context manager. # __enter__ doesn't actually do anything except return self. # This returns an asyncinotify.inotify.Watch instance inotify.add_watch('/tmp', Mask.ACCESS | Mask.MODIFY | Mask.OPEN | Mask.CREATE | Mask.DELETE | Mask.ATTRIB | Mask.CLOSE | Mask.MOVE | Mask.ONLYDIR) # Iterate events forever, yielding them one at a time async for event in inotify: # Events have a helpful __repr__. They also have a reference to # their Watch instance. print(event) # the contained path may or may not be valid UTF-8. See the note # below print(repr(event.path)) asyncio.run(main()) ``` -------------------------------- ### Inotify.get Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Asynchronously retrieves the next file system event. This is the core method for event retrieval and can internally buffer multiple events. Certain events may modify the state of associated watches. ```APIDOC ## Inotify.get ### Description Asynchronously retrieves the next file system event. This is the core method of event retrieval. Asynchronously iterating this class simply calls this method forever. May actually pull multiple events from the inotify handle, and store extras internally. Will always only return one. Building some events may cause changes in the associated `Inotify` or `Watch` instances. For instance, `Mask.IGNORE` will automatically remove its `Watch` instance from this `Inotify` object. A `Mask.ONESHOT` Watch will remove itself on the first event. Caution A watched path being moved will cause the relevant `Watch.path()` to be incorrect. This library will not automatically update it for you, because `Mask.MOVE_SELF` does not tell you the new name. You would have to watch the parent directory and change the `Watch.path()` value yourself if you want that functionality. If you don’t do this and the watch path is moved, the `Event` will have a correct name but incorrect path. ### Method Signature `_async _get() -> Event` ### Returns a single `Event` ``` -------------------------------- ### Watch Class Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Represents a single file system watch. ```APIDOC ## Watch Class Represents an individual file system watch. ### Attributes - `inotify`: The underlying inotify instance. - `mask`: The mask associated with this watch. - `path`: The path being watched. - `wd`: The watch descriptor. ``` -------------------------------- ### Inotify Class Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html The core Inotify class for managing file system watches and fetching events. It operates as an async generator, yielding events indefinitely. ```APIDOC ## class asyncinotify.Inotify ### Description Core Inotify class. Fetches events in bulk, if possible, and stores them internally. Use `get()` to get a single event. This class operates as an async generator, and may be asynchronously iterated, and will return events forever. ### Parameters * **flags** (_asyncinotify.InitFlags_) - Init flags for use with the `Inotify` constructor. Defaults to `CLOEXEC`. * **cache_size** (_int_) - The max number of full-size events to cache. Defaults to 10. * **sync_timeout** (_float | None_) - If this is not None, then sync_get will wait on a selector call for that long, and return None on a timeout. Normal iteration will also exit on a timeout. ### Methods #### add_watch ``` add_watch(_path : PathLike | bytes | str_, _mask : Mask_) -> Watch ``` ##### Description Add a watch dir. ##### Parameters * **path** (_pathlib.Path_) - a string, bytes, or PathLike object * **mask** (_Mask_) - a Mask determining how the watch behaves ##### Returns The relevant Watch instance #### close ``` close() -> None ``` ##### Description Close the file descriptor for this inotify. Once this is done, do not do anything more with this inotify instance. Associated `Watch` and `Event` instances are still valid, but no more may be created, and if this `Inotify` goes out of scope and is cleaned up, the `Event` may lose its `Watch` if you don’t have a reference to it. ### Properties #### cache_size ``` _property _cache_size _: int_ ``` ##### Description The maximum number of full-sized events (events with a NAME_MAX-length name) to store. More events may be stored, because very few events should use a NAME_MAX length name. ``` -------------------------------- ### Asyncinotify Methods Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Core methods for retrieving events and managing watches asynchronously. ```APIDOC ## async _get() -> Event Get a single next event asynchronously. This is the primary method for event retrieval. Asynchronous iteration over the class simply calls this method repeatedly. It may pull multiple events from the inotify handle and store extras internally, but will always return only one event at a time. Certain events, like `Mask.IGNORE` or `Mask.ONESHOT`, can cause modifications to the associated `Inotify` or `Watch` instances. Returns: a single `Event` object. ## rm_watch(_watch : Watch_) -> None Remove a watch from this inotify instance. This action will generate an `Mask.IGNORED` event containing the `Watch` instance that was removed. Parameters: **watch** (_Watch_) – The `Watch` object to remove. ## sync_get() -> Event | None Get a single next event synchronously. This method will throw a blocking error if the instance was opened in non-blocking mode. All concerns that apply to `get()` also apply to this method. Returns: a single `Event` object, or None if `sync_timeout` is not None and the poll timed out. ``` -------------------------------- ### InitFlags Enum Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Enum for initialization flags used with the Inotify constructor. ```APIDOC ## class asyncinotify.InitFlags ### Description Init flags for use with the `Inotify` constructor. You shouldn’t have a reason to use this, as `CLOEXEC` will be desired because there’s no reason for exec’d children to inherit inotify handles here, and `NONBLOCK` shouldn’t even make a difference due to the handle always being watched with select, unless you are using synchronous mode. ### Members * **CLOEXEC** (_ = 524288_) Set the close-on-exec (FD_CLOEXEC) flag on the new file descriptor if it exists. See the description of the O_CLOEXEC flag in open(2) for reasons why this may be useful. * **NONBLOCK** (_ = 524288_) Set the O_NONBLOCK file status flag on the open file description if it exists (see open(2)) referred to by the new file descriptor. Using this flag saves extra calls to fcntl(2) to achieve the same result. ``` -------------------------------- ### Event Class Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Represents an event output from the inotify system. Mask values can be tested directly against this class. ```APIDOC ## class asyncinotify.Event ### Description Event output class. The `Mask` values may be tested directly against this class. ### Properties #### cookie ``` _property _cookie _: int_ ``` ##### Description The cookie associated with this event. According to the inotify man page, cookie is a unique integer that connects related events. Currently, this is used only for rename events, and allows the resulting pair of `Mask.MOVED_FROM` and `Mask.MOVED_TO` events to be connected by the application. For all other event types, cookie is set to 0. ##### Returns the cookie for this event #### mask ``` _property _mask _: Mask_ ``` ##### Description The mask associated with this event ##### Returns the mask for this event #### name ``` _property _name _: Path | None_ ``` ##### Description The name associated with the event. May be None, indicating the watch directory itself. ##### Returns the name of the event, or None if the event is for the watch itself #### path ``` _property _path _: Path | None_ ``` ##### Description The full path to this event, constructed from the `Watch` path and the `name()`. If the `Watch` no longer exists, this returns None. If the `name()` does not exist, just returns the watch path. This value is absolute if the path used to construct the `Watch` (the path used with `Inotify.add_watch()`) is absolute, otherwise it is relative. This means if you have changed directory between constructing a watch with a relative path and receiving this event, you will have to have another way of identifying the file correctly. ##### Returns the full path for the event, or None if it can not be constructed. #### watch ``` _property _watch _: Watch | None_ ``` ##### Description The actual Watch instance associated with this event. This is stored internally as a weak reference. If the event is taken out of context and outlives its generating `Inotify`, this may return None. If `mask()` contains IGNORED or the watch was a ONESHOT, this is not a weak reference, but the actual watch instance. If the watch was ONESHOT, the corresponding IGNORED will not have a watch instance, only the ONESHOT event itself. This may be inconvenient, but the inotify man page doesn’t give strong enough guarantees to risk memory leak with ONESHOT events by leaving the ownership change exclusively to IGNORED events. ##### Returns the watch instance that generated this ``` -------------------------------- ### RecursiveInotify Methods Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Methods available on the RecursiveInotify class for managing recursive file system watches. ```APIDOC ## RecursiveInotify ### Methods - `add_recursive_watch(path: str, mask: int)` Adds a recursive watch to the specified path with the given mask. - `get()` Retrieves the next available event from the watch. - `sync_get()` Synchronously retrieves the next available event from the watch. ``` -------------------------------- ### Asyncinotify Class Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html The main class for asynchronous inotify operations. It can be used as an asynchronous context manager. ```APIDOC ## class asyncinotify This class provides an asynchronous interface for monitoring file system events using inotify. It can be used as an asynchronous context manager. ``` -------------------------------- ### Mask Enum Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Enum representing different file system event masks available in asyncinotify. ```APIDOC ## Mask Enum Represents various file system event flags that can be used with watches. ### Members - `ACCESS` - `ALL` - `ATTRIB` - `CLOSE` - `CLOSE_NOWRITE` - `CLOSE_WRITE` - `CREATE` - `DELETE` - `DELETE_SELF` - `DONT_FOLLOW` - `EXCL_UNLINK` - `IGNORED` - `ISDIR` - `MASK_ADD` - `MASK_CREATE` - `MODIFY` - `MOVE` - `MOVED_FROM` - `MOVED_TO` - `MOVE_SELF` - `ONESHOT` - `ONLYDIR` - `OPEN` - `Q_OVERFLOW` - `UNMOUNT` - `ZERO` ``` -------------------------------- ### Mask Class Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Bit-mask for adding watches and analyzing watch events. Supports standard IntFlag operations. ```APIDOC ## class asyncinotify.Mask(_value_ , _names= _, _*values_ , _module=None_ , _qualname=None_ , _type=None_ , _start=1_ , _boundary=None_) Bit-mask for adding a watch and for analyzing watch events. This class inherits from IntFlag, allowing bitwise operations for combining masks or checking for event types. ### Event Masks: - **ACCESS** = 1: File was accessed (e.g., read(2), execve(2)). - **ALL** = 4095: Monitor all common types of events (excluding modifier flags). - **ATTRIB** = 4: Metadata changed (e.g., permissions, timestamps, extended attributes, link count, user/group ID). - **CLOSE** = 24: Represents either `CLOSE_WRITE` or `CLOSE_NOWRITE`. - **CLOSE_NOWRITE** = 16: File or directory not opened for writing was closed. - **CLOSE_WRITE** = 8: File opened for writing was closed. - **CREATE** = 256: File/directory created in watched directory. - **DELETE** = 512: File/directory deleted from watched directory. - **DELETE_SELF** = 1024: Watched file/directory was itself deleted or moved to another filesystem. - **DONT_FOLLOW** = 33554432: Do not dereference pathname if it is a symbolic link. - **EXCL_UNLINK** = 67108864: Do not generate events for children after they have been unlinked from the watched directory. - **IGNORED** = 32768: Watch was removed explicitly or automatically. - **ISDIR** = 1073741824: Subject of this event is a directory. - **MASK_ADD** = 536870912: If a watch instance already exists, OR the events in mask with the existing mask. - **MASK_CREATE** = 268435456: Used in conjunction with `MASK_ADD`. ``` -------------------------------- ### Asyncinotify Properties Source: https://asyncinotify.readthedocs.io/en/latest/asyncinotify.html Properties available on the asyncinotify class for accessing the file descriptor and synchronous timeout settings. ```APIDOC ## _property _fd_ : int Get the raw file descriptor associated with the inotify instance. ## _property _sync_timeout_ : float | None The timeout for `sync_get()` and synchronous iteration. Set this to None to disable and -1 to wait forever. These options can be different depending on the blocking flags selected. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.