spacefreak/pyinotifyd
1
0
Fork 0
Code Issues Pull Requests Releases Activity

change README.md

Browse Source
This commit is contained in:
Thomas Oettli
2020-11-03 21:10:41 +01:00
parent 1fa5e0bad6
commit f2b6f1e0b6
1 changed files with 15 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@@ -9,20 +9,20 @@ A daemon to monitore filesystems events with inotify on Linux and execute tasks
pip install pyinotifyd pip install pyinotifyd
``` ```
# Configuration ## Configuration
The config file **/etc/pyinotifyd/config.py** is written in Python syntax. pyinotifyd reads and executes its content, that means you can add your custom Python code to the config file. The config file **/etc/pyinotifyd/config.py** is written in Python syntax. pyinotifyd reads and executes its content, that means you can add your custom Python code to the config file.
## Tasks ### Tasks
Tasks are Python methods that are called in case an event occurs. They can be bound directly to an event type in an event map. Although this is the easiest and quickest way, it is usually better to add a task to a scheduler and bind the scheduler to event types. Tasks are Python methods that are called in case an event occurs. They can be bound directly to an event type in an event map. Although this is the easiest and quickest way, it is usually better to add a task to a scheduler and bind the scheduler to event types.
### Simple #### Simple
This is a very basic example task that just logs each event and task_id: This is a very basic example task that just logs each event and task_id:
```python ```python
async def task(event, task_id): async def task(event, task_id):
logging.info(f"{task_id}: execute example task: {event}") logging.info(f"{task_id}: execute example task: {event}")
``` ```
### FileManager #### FileManager
FileManager moves, copy or deletes files and/or directories following a list of *rules*. FileManager moves, copy or deletes files and/or directories following a list of *rules*.
A rule holds an *action* (move, copy or delete) and a regular expression *src_re*. The FileManager task will be executed if *src_re* matches the path of an event. If the action is copy or move, the destination path *dst_re* is mandatory. If *auto_create* is True, possibly missing subdirectories in *dst_re* are automatically created. If *action* is delete and *rec* is True, non-empty directories will be deleted recursively. It is possible to use Regex subgroups or named-subgroups in *src_re* and *dst_re*. Use *logname* in log messages. A rule holds an *action* (move, copy or delete) and a regular expression *src_re*. The FileManager task will be executed if *src_re* matches the path of an event. If the action is copy or move, the destination path *dst_re* is mandatory. If *auto_create* is True, possibly missing subdirectories in *dst_re* are automatically created. If *action* is delete and *rec* is True, non-empty directories will be deleted recursively. It is possible to use Regex subgroups or named-subgroups in *src_re* and *dst_re*. Use *logname* in log messages.
@@ -35,10 +35,10 @@ fm = FileManager(rules=[rule], logname="FileManager")
``` ```
FileManager provides a task **fm.task**. FileManager provides a task **fm.task**.
## Schedulers ### Schedulers
pyinotifyd has different schedulers to schedule tasks with an optional delay. The advantages of using a scheduler are consistent logging and the possibility to cancel delayed tasks. Furthermore, schedulers have the ability to differentiate between files and directories. pyinotifyd has different schedulers to schedule tasks with an optional delay. The advantages of using a scheduler are consistent logging and the possibility to cancel delayed tasks. Furthermore, schedulers have the ability to differentiate between files and directories.
### TaskScheduler #### TaskScheduler
TaskScheduler schedules *task* with an optional *delay* in seconds. Use the *files* and *dirs* arguments to schedule tasks only for files and/or directories. TaskScheduler schedules *task* with an optional *delay* in seconds. Use the *files* and *dirs* arguments to schedule tasks only for files and/or directories.
Use *logname* in log messages. All arguments except for *task* are optional. Use *logname* in log messages. All arguments except for *task* are optional.
```python ```python
@@ -50,12 +50,12 @@ TaskScheduler provides two tasks which can be bound to an event in an event map.
* **s.cancel** * **s.cancel**
Cancel a scheduled task. Cancel a scheduled task.
### ShellScheduler #### ShellScheduler
ShellScheduler schedules Shell command *cmd*. The placeholders **{maskname}**, **{pathname}** and **{src_pathname}** are replaced with the actual values of the event. ShellScheduler has the same optional arguments as TaskScheduler and provides the same tasks. ShellScheduler schedules Shell command *cmd*. The placeholders **{maskname}**, **{pathname}** and **{src_pathname}** are replaced with the actual values of the event. ShellScheduler has the same optional arguments as TaskScheduler and provides the same tasks.
```python ```python
s1 = ShellScheduler(cmd="/usr/local/bin/task.sh {maskname} {pathname} {src_pathname}") s1 = ShellScheduler(cmd="/usr/local/bin/task.sh {maskname} {pathname} {src_pathname}")
``` ```
## Event maps ### Event maps
EventMap maps event types to tasks. It is possible to set a list of tasks to run multiple tasks on a single event. If the task of an event type is set to None, it is ignored. EventMap maps event types to tasks. It is possible to set a list of tasks to run multiple tasks on a single event. If the task of an event type is set to None, it is ignored.
This is an example: This is an example:
```python ```python
@@ -63,21 +63,21 @@ event_map = EventMap({"IN_CLOSE_NOWRITE": [s.schedule, s1.schedule],
"IN_CLOSE_WRITE": s.schedule}) "IN_CLOSE_WRITE": s.schedule})
``` ```
## Watches ### Watches
Watch watches *path* for event types in *event_map* and execute the corresponding task(s). If *rec* is True, a watch will be added on each subdirectory in *path*. If *auto_add* is True, a watch will be added automatically on newly created subdirectories in *path*. Watch watches *path* for event types in *event_map* and execute the corresponding task(s). If *rec* is True, a watch will be added on each subdirectory in *path*. If *auto_add* is True, a watch will be added automatically on newly created subdirectories in *path*.
```python ```python
watch = Watch(path="/tmp", event_map=event_map, rec=False, auto_add=False) watch = Watch(path="/tmp", event_map=event_map, rec=False, auto_add=False)
``` ```
## PyinotifydConfig ### PyinotifydConfig
pyinotifyd expects an instance of PyinotifydConfig named **pyinotifyd_config** that holds its config options. The options are a list of *watches*, the *loglevel* (see https://docs.python.org/3/library/logging.html#levels) and the *shutdown_timeout*. pyinotifyd will wait *shutdown_timeout* seconds for pending tasks to complete during shutdown. pyinotifyd expects an instance of PyinotifydConfig named **pyinotifyd_config** that holds its config options. The options are a list of *watches*, the *loglevel* (see https://docs.python.org/3/library/logging.html#levels) and the *shutdown_timeout*. pyinotifyd will wait *shutdown_timeout* seconds for pending tasks to complete during shutdown.
```python ```python
pyinotifyd_config = PyinotifydConfig(watches=[watch], loglevel=logging.INFO, shutdown_timeout=30) pyinotifyd_config = PyinotifydConfig(watches=[watch], loglevel=logging.INFO, shutdown_timeout=30)
``` ```
# Examples ## Examples
## Schedule Python task for all events ### Schedule Python task for all events
```python ```python
async def task(event, task_id): async def task(event, task_id):
logging.info(f"{task_id}: execute example task: {event}") logging.info(f"{task_id}: execute example task: {event}")
@@ -91,7 +91,7 @@ pyinotifyd_config = PyinotifydConfig(
watches=[watch], loglevel=logging.INFO, shutdown_timeout=5) watches=[watch], loglevel=logging.INFO, shutdown_timeout=5)
``` ```
## Schedule Shell commands for specific events on files ### Schedule Shell commands for specific events on files
```python ```python
s = ShellScheduler( s = ShellScheduler(
cmd="/usr/local/sbin/task.sh {pathname}", files=True, dirs=False) cmd="/usr/local/sbin/task.sh {pathname}", files=True, dirs=False)
@@ -104,7 +104,7 @@ pyinotifyd_config = PyinotifydConfig(
watches=[watch], loglevel=logging.INFO, shutdown_timeout=5) watches=[watch], loglevel=logging.INFO, shutdown_timeout=5)
``` ```
## Move, copy or delete newly created files after a delay ### Move, copy or delete newly created files after a delay
```python ```python
move_rule = Rule(action="move", move_rule = Rule(action="move",
src_re="^/src_path/(?P<path>.*)\.to_move$", src_re="^/src_path/(?P<path>.*)\.to_move$",
@@ -138,7 +138,7 @@ pyinotifyd_config = PyinotifydConfig(
watches=[watch], loglevel=logging.INFO, shutdown_timeout=35) watches=[watch], loglevel=logging.INFO, shutdown_timeout=35)
``` ```
# Autostart ### Autostart
pyinotifyd provides a systemd service file. pyinotifyd provides a systemd service file.
```sh ```sh
# start pyinotifyd at boot time # start pyinotifyd at boot time