eventloop 0.0.26
Abstraction layer for filesystem events

==================================================
eventloop: Abstraction layer for filesystem events
==================================================

Eventloop uses any of: `pyuv` or `PySide2` or `PyQt5` installed in the system 
to provide callback interface for filesystem events. And also timers.

Package intended to be a building block for utility scripts for recompiling 
or pushing files or restarting tests.

`pyuv` is used preferably as it's most efficient. `uv` is a library that 
powers nodejs event loop.

Installing
==========

eventloop can be installed via pip as follows:

::

    pip install eventloop

Author
======

Stanislav Doronin <mugisbrows@gmail.com>

Usage
=====

In simple case you can use `on_file_changed` decorator. It creates event loop, system watch and schedule, then connects them, then starts the loop and calls decorated function on filesystem events.

.. code-block:: python

    from eventloop import on_file_changed

    if __name__ == "__main__":
        @on_file_changed("/path/to/dir")
        def your_handler(file_path):
            print(file_path)

Decorator accepts `include` and `exclude` args (list of globs or names to include or exclude files from watch) and `timeout` arg (read about timeout below) and `loop` arg.

If you need to watch more than one path you need to create and start `EventLoop` explicitly and pass it to decorators.

.. code-block:: python

    from eventloop import EventLoop, on_file_changed

    if __name__ == "__main__":

        loop = EventLoop()

        @on_file_changed("/path/to/first/dir", loop=loop)
        def first_handler(file_path):
            print(file_path)

        @on_file_changed("/path/to/second/dir", loop=loop)
        def second_handler(file_path):
            print(file_path)

        loop.start()

For finer control over things you can use classes, first example can be rewriten as

.. code-block:: python

    from eventloop import EventLoop, FileSystemWatch, Schedule, base

    class Executor(base.Executor):
        def execute(self, file_path):
            print(file_path)

    if __name__ == "__main__":

        loop = EventLoop()
        executor = Executor()
        schedule = Schedule(executor)

        def on_change(file_path, event):
            schedule.append(file_path, timeout=1)
            
        watch = FileSystemWatch(loop)
        watch.start("/path/to/dir", on_change)
        loop.start()

`Schedule` caches (deduplicates) tasks appended within `timeout` interval, so for example three immediate consecutive `changed` events on same file end up in just one `Executor.execute(task)` call. `on_file_changed` decorator also uses `Schedule` to cache events.

Cli
===

You can use onchange script in command line to execute commands 

.. code-block:: shell

    python -m eventloop.onchange D:\dev\app -- echo FILE
    onchange D:\dev\app -- echo FILE
    onchange D:\dev\app -i *.cpp *.ui --cwd D:\dev\app\build -- ninja "&&" ctest
    onchange . -i "*.pyx" --beep -- python setup.py build_ext --inplace
    onchange http-server.py --server -- python -u http-server.py

License
=======

Eventloop is distributed under the terms of MIT license, check `LICENSE` file.