{"id":6524,"library":"asyncinotify","title":"asyncinotify","description":"asyncinotify is a simple, optionally-async Python inotify library, focusing on ease of use and modern Python features. It provides a Pythonic interface to Linux's inotify API, built on `ctypes` without external dependencies. The library is actively maintained, currently at version 4.4.4, and supports Python 3.6 and newer. It offers both asynchronous (async/await) and synchronous modes of operation for file system event monitoring.","status":"active","version":"4.4.4","language":"en","source_language":"en","source_url":"https://github.com/ProCern/asyncinotify","tags":["inotify","asyncio","filesystem","monitoring","linux"],"install":[{"cmd":"pip install asyncinotify","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Inotify","correct":"from asyncinotify import Inotify"},{"symbol":"Mask","correct":"from asyncinotify import Mask"}],"quickstart":{"code":"import asyncio\nimport os\nimport tempfile\nfrom pathlib import Path\nfrom asyncinotify import Inotify, Mask\n\nasync def main():\n    # Create a temporary directory for watching\n    with tempfile.TemporaryDirectory() as tmpdir_name:\n        watch_path = Path(tmpdir_name)\n        print(f\"Watching directory: {watch_path}\")\n\n        with Inotify() as inotify:\n            # Add a watch for various events\n            inotify.add_watch(\n                watch_path,\n                Mask.ACCESS | Mask.MODIFY | Mask.OPEN | Mask.CREATE |\n                Mask.DELETE | Mask.ATTRIB | Mask.CLOSE | Mask.MOVE | Mask.ONLYDIR\n            )\n            print(\"Watch added. Creating a file in the directory...\")\n\n            # Create a file to trigger events\n            test_file = watch_path / \"test_file.txt\"\n            test_file.write_text(\"hello\")\n            await asyncio.sleep(0.1) # Give a moment for events to register\n            test_file.unlink()\n            await asyncio.sleep(0.1) # Give a moment for events to register\n            print(\"File operations completed. Collecting events...\")\n\n            # Collect a few events. In a real application, you'd process them in a loop.\n            events_collected = 0\n            async for event in inotify:\n                print(f\"Event: {event}\")\n                events_collected += 1\n                # Break after a few events or based on application logic\n                if events_collected >= 3: # Adjust based on expected events\n                    break\n            print(\"Finished collecting events.\")\n\nasyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to asynchronously watch a temporary directory for common file system events (create, modify, access, delete). It uses `Inotify` as a context manager to ensure the inotify handle is properly closed. Events are iterated asynchronously, printing details as they occur."},"warnings":[{"fix":"Implement logic to watch parent directories for `Mask.MOVE_SELF` or `Mask.MOVED_FROM`/`Mask.MOVED_TO` events, and programmatically update or re-add watches with the new paths.","message":"When a watched directory or file is moved, the `Event.path` property associated with subsequent events for that watch may become incorrect. The library does not automatically update the watch path. To correctly track moved paths, users must monitor the parent directory for `Mask.MOVE_SELF` events and re-add/update watches as needed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that asynchronous iteration loops have a defined exit condition, such as a counter, a timeout, or a signal-based shutdown mechanism.","message":"The `Inotify` instance, when iterated asynchronously (`async for event in inotify:`), will yield events indefinitely (or until the inotify handle is closed). This is expected for continuous monitoring, but users must include their own logic (e.g., a `break` condition or `asyncio.wait_for`) to stop the iteration if only a finite number of events are expected or if the application needs to terminate.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Plan to migrate to Python versions that are actively supported by the Python community (e.g., Python 3.10+) to ensure continued compatibility and receive security updates.","message":"The library currently supports Python 3.6 and newer. However, the maintainers have stated that in a future version, Python support may be restricted to non-End-of-Life (EOL) versions if supporting older versions becomes inconvenient. Users should consider upgrading to actively supported Python versions to ensure future compatibility.","severity":"deprecated","affected_versions":"Future versions (post 4.x)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install asyncinotify'.","cause":"The 'asyncinotify' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'asyncinotify'"},{"fix":"Ensure you are importing the correct class or function from 'asyncinotify'. Refer to the official documentation for the correct import statements.","cause":"The module 'asyncinotify' does not contain a class or function named 'AsyncInotify'.","error":"ImportError: cannot import name 'AsyncInotify' from 'asyncinotify'"},{"fix":"Verify that you have installed the correct version of 'asyncinotify' that includes the 'Inotify' class. Check the module's documentation for the correct usage.","cause":"The 'Inotify' class is not present in the 'asyncinotify' module, possibly due to a version mismatch or incorrect installation.","error":"AttributeError: module 'asyncinotify' has no attribute 'Inotify'"},{"fix":"Ensure that the directory or file you are trying to watch with `inotify.add_watch()` exists before creating the watch.","cause":"This error typically occurs when the path provided to `Inotify.add_watch()` does not exist on the filesystem.","error":"OSError: [Errno 2] No such file or directory"},{"fix":"Run your application on a Linux-based operating system. If using FreeBSD 15+, the warning might still appear but the functionality should be available.","cause":"The `asyncinotify` library, by default, uses Linux's `inotify` API, which is not available on other operating systems like macOS or Windows. While recent FreeBSD versions (15+) also support inotify, this warning indicates an attempt to run the library on an unsupported platform.","error":"UserWarning: inotify is a Linux-only API. You can package this library on other platforms, but not run it."}]}