Watchinotify
Watchinotify is a python library to easily use the libc's inotify functions to watch for any file interaction.
The library aims at being simple yet powerfull with easily auditable code.
Limitations
If you watch a file or a folder for a move it will be unwatched after being moved (renaming is considered a move). This is a limitation of the inotify system which desn't give any way to know the new name/path. Any move/rename within watched folders are still being tracked, this also works with the recursive option.
When using the recursive option the folder SUB_CREATED and SUB_MOVED events are enforced. Otherwise the watcher would not be able to keep track of the file tree after adding or moving folders.
Install
Use pip or equivalent to install package name watchinotify:
pip install watchinotify
Usage
Create a Watcher and assign its callback to your custom function, then with the Watcher's watch function to add a list (or any iterable) or path to file/folder to watch. The watcher is going to run on a separated thread waiting for any event then calling the callback. You can run your code after calling watch or wait for an event using the threading.Event for instance.
The following example explicits the parameters types of the callback function:
from pathlib import Path
import threading
from watchinotify import Watcher
event_received = threading.Event()
def callback(path: Path | None, event, name: bytes):
print(f'New event {event} from path {path} with additionnal name {name.decode()}')
event_received.set()
watcher = Watcher() as watcher:
watcher.watch([Path('/path/to/watch')])
watcher.callback = callback
# Any of your code from here
event_received.wait()
# Do not forget to close the watcher once done (or use a 'with' statement)
watcher.close()
Using a with statement is easier and safer so the close will be automatically called.
with Watcher(event_type, exclude_patterns, recursive) as watcher: # will automatically close
watcher.watch([Path('/path/to/watch')])
The Watcher has 3 arguments:
- event_type : what type of event to watch see the *Event Type section below. If set to None it is using default value of
FileEvent.MODIFIED | FileEvent.DELETED | FileEvent.MOVEDfor files andFolderEvent.DELETED | FolderEvent.MOVED | FolderEvent.SUB_CREATED | FolderEvent.SUB_DELETED | FolderEvent.SUB_MOVEDfor folders. You can use the parentEventtype to set all required events, if you want specific events separated it is better to create multiple watchers. Default: None - exclude_patterns : iterable (list, tuple, etc) of pattern to ignore,following glob conventions, example :
['*/sub_folder', __pycache__]. Default: None - recursive : boolean to watch recursively all sub folders/files when adding a folder to watch. This will force the events
FolderEvent.SUB_CREATEDandFolderEvent.SUB_MOVEDto be watched in order to properly work, you'll have to filter out those event in you callback if unwanted. Default: True
Event Types
All possible events are un the Event flag. You can cumulate events by using the or or | operator. 2 additionnal types FileEvent and FolderEvent inherits from the Event values but only contains the event that can be trigger respectively from files and folders. The 2 sub types also have an ALL value as a handy shortcut.
The events are defined as:
from enum import IntFlag, auto
class Event(IntFlag):
OPENED = auto()
MODIFIED = auto()
DELETED = auto()
MOVED = auto()
CLOSED = auto()
SUB_CREATED = auto()
SUB_DELETED = auto()
SUB_MOVED = auto()
class FileEvent(IntFlag):
OPENED = Event.OPENED.value
MODIFIED = Event.MODIFIED.value
DELETED = Event.DELETED.value
MOVED = Event.MOVED.value
CLOSED = Event.CLOSED.value
ALL = OPENED | MODIFIED | DELETED | MOVED | CLOSED
class FolderEvent(IntFlag):
DELETED = Event.DELETED.value
MOVED = Event.MOVED.value
SUB_CREATED = Event.SUB_CREATED.value
SUB_DELETED = Event.SUB_DELETED.value
SUB_MOVED = Event.SUB_MOVED.value
ALL = DELETED | MOVED | SUB_CREATED | SUB_DELETED | SUB_MOVED
Development
Run test
pytest
Run coverage
python tests/run_coverage.py
LICENSE
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
Metadata
Release files for watchinotify 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| watchinotify-0.2.1.tar.gz | 21.2 kB | Without provenance | Details for watchinotify-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| watchinotify-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for watchinotify-0.2.1-py3-none-any.whl |
Total release size: 41.3 kB
Release files / watchinotify-0.2.1.tar.gz
| Download URL | watchinotify-0.2.1.tar.gz |
|---|---|
| Size | 21.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d12655a91eb521bb751d15118187a98e26cadae941e35301ebe30fdae5b6194a
|
|
BLAKE2b-256 checksum How to use checksums |
1c76eaf6899ba1f1531833821ff918423439c4ecd979ee0fecc289bf70c1db44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / watchinotify-0.2.1-py3-none-any.whl
| Download URL | watchinotify-0.2.1-py3-none-any.whl |
|---|---|
| Size | 20.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3196381f406e5e5deece55fd1fd54c6ea02f1d0cb725b9a31f20dd605ffc4741
|
|
BLAKE2b-256 checksum How to use checksums |
b8b5a993edaa5c7c752b4b6ffeb04eb0e6e7d1f3c2c0d7ec40360b57e6f22887
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for watchinotify 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.