README

Watchdog
========
Python API and shell utilities to monitor file system events.


Example API Usage
-----------------
A simple program that uses watchdog to monitor directories specified
as command-line arguments and logs events generated::

    import sys
    import time
    from logging import INFO, basicConfig
    from watchdog.observers import Observer
    from watchdog.events import LoggingEventHandler

    if __name__ == "__main__":
        basicConfig(level   = INFO,
                    format  = '%(asctime)s - %(message)s',
                    datefmt = '%Y-%m-%d %H:%M:%S')
        path = sys.argv[1]
        event_handler = LoggingEventHandler()
        observer = Observer()
        observer.schedule(event_handler, path, recursive=True)
        observer.start()
        try:
            while True:
                time.sleep(1)
        except KeyboardInterrupt:
            observer.stop()
        observer.join()


Shell Utilities
---------------
Watchdog comes with a utility script called ``watchmedo``.
Please type ``watchmedo --help`` at the shell prompt to
know more about this tool.

Here is how you can log the current directory recursively
for events related only to ``*.py`` and ``*.txt`` files while
ignoring all directory events::

    watchmedo log \
        --patterns="*.py;*.txt" \
        --ignore-directories \
        --recursive \
        .

You can use the ``shell-command`` subcommand to execute shell commands in
response to events::

    watchmedo shell-command \
        --patterns="*.py;*.txt" \
        --recursive \
        --command='echo "${watch_src_path}"' \
        .

Please see the help information for these commands by typing::

    watchmedo [command] --help


About ``watchmedo`` Tricks
~~~~~~~~~~~~~~~~~~~~~~~~~~
``watchmedo`` can read ``tricks.yaml`` files and execute tricks within them in
response to file system events. Tricks are actually event handlers that
subclass ``watchdog.tricks.Trick`` and are written by plugin authors. Trick
classes are augmented with a few additional features that regular event handlers
don't need.

An example ``tricks.yaml`` file::

    tricks:
    - watchdog.tricks.LoggerTrick:
        patterns: ["*.py", "*.js"]
    - watchmedo_webtricks.GoogleClosureTrick:
        patterns: ['*.js']
        hash_names: true
        mappings_format: json                  # json|yaml|python
        mappings_module: app/javascript_mappings
        suffix: .min.js
        compilation_level: advanced            # simple|advanced
        source_directory: app/static/js/
        destination_directory: app/public/js/
        files:
          index-page:
          - app/static/js/vendor/jquery*.js
          - app/static/js/base.js
          - app/static/js/index-page.js
          about-page:
          - app/static/js/vendor/jquery*.js
          - app/static/js/base.js
          - app/static/js/about-page/**/*.js

The directory containing the ``tricks.yaml`` file will be monitored. Each trick
class is initialized with its corresponding keys in the ``tricks.yaml`` file as
arguments and events are fed to an instance of this class as they arrive.

Tricks will be included in the 0.5.0 release. I need community input about them.
Please file enhancement requests at the `issue tracker`_.


Installation
------------
Installing from PyPI using ``pip``::

    pip install watchdog

Installing from PyPI using ``easy_install``::

    easy_install watchdog

Installing from source::

    python setup.py install


Installation Caveats
~~~~~~~~~~~~~~~~~~~~
The ``watchmedo`` script depends on PyYAML_ which links with LibYAML_.
On Mac OS X, you can use homebrew_ to install LibYAML::

    brew install libyaml

On Linux, use your favorite package manager to install LibYAML. Here's how you
do it on Ubuntu::

    sudo aptitude install libyaml-dev

On Windows, please install PyYAML_ using the binaries they provide.

Documentation
-------------
You can browse the latest release documentation_ online.

Supported Platforms
-------------------
* Linux 2.6 (inotify)
* Mac OS X (FSEvents, kqueue)
* FreeBSD/BSD (kqueue)
* Windows (ReadDirectoryChangesW with I/O completion ports;
  ReadDirectoryChangesW worker threads)
* OS-independent (polling the disk for directory snapshots and comparing them
  periodically; slow and not recommended)


Dependencies
------------
1. Python 2.5 or above.
2. XCode_ (only on Mac OS X)
3. PyYAML_
4. argh_
5. select_backport_ (select.kqueue replacement for Python2.5/2.6 on BSD/Mac OS X)
6. pathtools_
7. Brownie_


Licensing
---------
Watchdog is licensed under the terms of the `MIT License`_.

Copyright (C) 2010 `Yesudeep Mangalapilly`_ and the Watchdog authors.

Project `source code`_ is available at Github. Please report bugs and file
enhancement requests at the `issue tracker`_.

Why Watchdog?
-------------
Too many people tried to do the same thing and none did what I needed Python
to do:

* pnotify_
* `unison fsmonitor`_
* fsmonitor_
* guard_
* pyinotify_
* `inotify-tools`_
* jnotify_
* treewalker_
* `file.monitor`_
* pyfilesystem_

.. links:
.. _Yesudeep Mangalapilly: yesudeep@gmail.com
.. _source code: http://github.com/gorakhargosh/watchdog
.. _issue tracker: http://github.com/gorakhargosh/watchdog/issues
.. _MIT License: http://www.opensource.org/licenses/mit-license.php
.. _documentation: http://packages.python.org/watchdog/

.. _homebrew: http://mxcl.github.com/homebrew/
.. _select_backport: http://pypi.python.org/pypi/select_backport
.. _argh: http://pypi.python.org/pypi/argh
.. _PyYAML: http://www.pyyaml.org/
.. _XCode: http://developer.apple.com/technologies/tools/xcode.html
.. _LibYAML: http://pyyaml.org/wiki/LibYAML
.. _pathtools: http://github.com/gorakhargosh/pathtools
.. _Brownie: http://github.com/DasIch/brownie

.. _pnotify: http://mark.heily.com/pnotify
.. _unison fsmonitor: https://webdav.seas.upenn.edu/viewvc/unison/trunk/src/fsmonitor.py?view=markup&pathrev=471
.. _fsmonitor: http://github.com/shaurz/fsmonitor
.. _guard: http://github.com/guard/guard
.. _pyinotify: http://github.com/seb-m/pyinotify
.. _inotify-tools: http://github.com/rvoicilas/inotify-tools
.. _jnotify: http://jnotify.sourceforge.net/
.. _treewalker: http://github.com/jbd/treewatcher
.. _file.monitor: http://github.com/pke/file.monitor
.. _pyfilesystem: http://code.google.com/p/pyfilesystem