README - platform/external/python/watchdog - Git at Google

 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
     import logging
     from watchdog.observers import Observer
     from watchdog.events import LoggingEventHandler

     if __name__ == "__main__":
         logging.basicConfig(level=logging.INFO,
                             format='%(asctime)s - %(message)s',
                             datefmt='%Y-%m-%d %H:%M:%S')
         event_handler = LoggingEventHandler()
         observer = Observer()
         observer.schedule(event_handler, path=sys.argv[1], 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_,
 which brings a performance boost to the PyYAML parser. However, installing
 LibYAML_ is optional but recommended. 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_


 Licensing
 ---------
 Watchdog is licensed under the terms of the `Apache License, version 2.0`_.

 Copyright (C) 2011 `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
 .. _Apache License, version 2.0: http://www.apache.org/licenses/LICENSE-2.0
 .. _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

 .. _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
	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
	import logging
	from watchdog.observers import Observer
	from watchdog.events import LoggingEventHandler

	if __name__ == "__main__":
	logging.basicConfig(level=logging.INFO,
	format='%(asctime)s - %(message)s',
	datefmt='%Y-%m-%d %H:%M:%S')
	event_handler = LoggingEventHandler()
	observer = Observer()
	observer.schedule(event_handler, path=sys.argv[1], 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_,
	which brings a performance boost to the PyYAML parser. However, installing
	LibYAML_ is optional but recommended. 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_


	Licensing
	---------
	Watchdog is licensed under the terms of the `Apache License, version 2.0`_.

	Copyright (C) 2011 `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
	.. _Apache License, version 2.0: http://www.apache.org/licenses/LICENSE-2.0
	.. _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

	.. _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