455 lines
21 KiB
Plaintext
455 lines
21 KiB
Plaintext
Metadata-Version: 2.1
|
|
Name: watchdog
|
|
Version: 0.10.0
|
|
Summary: Filesystem events monitoring
|
|
Home-page: http://github.com/gorakhargosh/watchdog
|
|
Author: Yesudeep Mangalapilly
|
|
Author-email: yesudeep@gmail.com
|
|
License: Apache License 2.0
|
|
Description: Watchdog
|
|
========
|
|
|
|
.. image:: https://travis-ci.org/gorakhargosh/watchdog.svg?branch=master
|
|
:target: https://travis-ci.org/gorakhargosh/watchdog
|
|
|
|
Python API and shell utilities to monitor file system events.
|
|
|
|
Works on Python 2.7 and 3.4+. If you want to use an old version of Python, you should stick with watchdog < 0.10.0.
|
|
|
|
Example API Usage
|
|
-----------------
|
|
A simple program that uses watchdog to monitor directories specified
|
|
as command-line arguments and logs events generated:
|
|
|
|
.. code-block:: python
|
|
|
|
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')
|
|
path = sys.argv[1] if len(sys.argv) > 1 else '.'
|
|
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 an *optional* 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:
|
|
|
|
.. code-block:: bash
|
|
|
|
watchmedo log \
|
|
--patterns="*.py;*.txt" \
|
|
--ignore-directories \
|
|
--recursive \
|
|
.
|
|
|
|
You can use the ``shell-command`` subcommand to execute shell commands in
|
|
response to events:
|
|
|
|
.. code-block:: bash
|
|
|
|
watchmedo shell-command \
|
|
--patterns="*.py;*.txt" \
|
|
--recursive \
|
|
--command='echo "${watch_src_path}"' \
|
|
.
|
|
|
|
Please see the help information for these commands by typing:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
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
|
|
------------
|
|
Install from PyPI using ``pip``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python -m pip install watchdog
|
|
|
|
# or to install the watchmedo utility:
|
|
$ python -m pip install watchdog[watchmedo]
|
|
|
|
Install from source:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python -m pip install -e .
|
|
|
|
# or to install the watchmedo utility:
|
|
$ python -m pip install -e ".[watchmedo]"
|
|
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ brew install libyaml
|
|
|
|
On Linux, use your favorite package manager to install LibYAML. Here's how you
|
|
do it on Ubuntu:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ sudo aptitude install libyaml-dev
|
|
|
|
On Windows, please install PyYAML_ using the binaries they provide.
|
|
|
|
Documentation
|
|
-------------
|
|
You can browse the latest release documentation_ online.
|
|
|
|
Contribute
|
|
----------
|
|
Fork the `repository`_ on GitHub and send a pull request, or file an issue
|
|
ticket at the `issue tracker`_. For general help and questions use the official
|
|
`mailing list`_ or ask on `stackoverflow`_ with tag `python-watchdog`.
|
|
|
|
Create and activate your virtual environment, then::
|
|
|
|
python -m pip install pytest pytest-cov
|
|
python -m pip install -e .[watchmedo]
|
|
python -m pytest tests
|
|
|
|
If you are making a substantial change, add an entry to the "Unreleased" section
|
|
of the `changelog`_.
|
|
|
|
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)
|
|
|
|
Note that when using watchdog with kqueue, you need the
|
|
number of file descriptors allowed to be opened by programs
|
|
running on your system to be increased to more than the
|
|
number of files that you will be monitoring. The easiest way
|
|
to do that is to edit your ``~/.profile`` file and add
|
|
a line similar to::
|
|
|
|
ulimit -n 1024
|
|
|
|
This is an inherent problem with kqueue because it uses
|
|
file descriptors to monitor files. That plus the enormous
|
|
amount of bookkeeping that watchdog needs to do in order
|
|
to monitor file descriptors just makes this a painful way
|
|
to monitor files and directories. In essence, kqueue is
|
|
not a very scalable way to monitor a deeply nested
|
|
directory of files and directories with a large number of
|
|
files.
|
|
|
|
About using watchdog with editors like Vim
|
|
------------------------------------------
|
|
Vim does not modify files unless directed to do so.
|
|
It creates backup files and then swaps them in to replace
|
|
the files you are editing on the disk. This means that
|
|
if you use Vim to edit your files, the on-modified events
|
|
for those files will not be triggered by watchdog.
|
|
You may need to configure Vim appropriately to disable
|
|
this feature.
|
|
|
|
|
|
About using watchdog with CIFS
|
|
------------------------------
|
|
When you want to watch changes in CIFS, you need to explicitly tell watchdog to
|
|
use ``PollingObserver``, that is, instead of letting watchdog decide an
|
|
appropriate observer like in the example above, do::
|
|
|
|
from watchdog.observers.polling import PollingObserver as Observer
|
|
|
|
|
|
Dependencies
|
|
------------
|
|
1. Python 2.7, 3.4 or above.
|
|
2. pathtools_
|
|
3. XCode_ (only on Mac OS X)
|
|
4. PyYAML_ (only for ``watchmedo`` script)
|
|
5. argh_ (only for ``watchmedo`` script)
|
|
|
|
|
|
Licensing
|
|
---------
|
|
Watchdog is licensed under the terms of the `Apache License, version 2.0`_.
|
|
|
|
Copyright 2011 `Yesudeep Mangalapilly`_.
|
|
|
|
Copyright 2012 Google, Inc.
|
|
|
|
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: https://watchdog.readthedocs.io/
|
|
.. _stackoverflow: http://stackoverflow.com/questions/tagged/python-watchdog
|
|
.. _mailing list: http://groups.google.com/group/watchdog-python
|
|
.. _repository: http://github.com/gorakhargosh/watchdog
|
|
.. _issue tracker: http://github.com/gorakhargosh/watchdog/issues
|
|
.. _changelog: https://github.com/gorakhargosh/watchdog/blob/master/changelog.rst
|
|
|
|
.. _homebrew: http://mxcl.github.com/homebrew/
|
|
.. _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
|
|
|
|
|
|
.. :changelog:
|
|
|
|
Changelog
|
|
---------
|
|
|
|
0.10.0
|
|
~~~~~~
|
|
|
|
2019-12-20 • `full history <https://github.com/gorakhargosh/watchdog/compare/v0.9.0...v0.10.0>`__
|
|
|
|
**Breaking Changes**
|
|
|
|
- Dropped support for Python 2.6, 3.2 and 3.3
|
|
- Emitters that failed to start are now removed
|
|
- [snapshot] Removed the deprecated ``walker_callback`` argument,
|
|
use ``stat`` instead
|
|
- [watchmedo] The utility is no more installed by default but via the extra
|
|
``watchdog[watchmedo]``
|
|
|
|
**Other Changes**
|
|
|
|
- Fixed several Python 3 warnings
|
|
- Identify synthesized events with ``is_synthetic`` attribute (`#369 <https://github.com/gorakhargosh/watchdog/pull/369>`__)
|
|
- Use ``os.scandir()`` to improve memory usage (`#503 <https://github.com/gorakhargosh/watchdog/pull/503>`__)
|
|
- [bsd] Fixed flavors of FreeBSD detection (`#529 <https://github.com/gorakhargosh/watchdog/pull/529>`__)
|
|
- [bsd] Skip unprocessable socket files (`#509 <https://github.com/gorakhargosh/watchdog/issue/509>`__)
|
|
- [inotify] Fixed events containing non-ASCII characters (`#516 <https://github.com/gorakhargosh/watchdog/issues/516>`__)
|
|
- [inotify] Fixed the way ``OSError`` are re-raised (`#377 <https://github.com/gorakhargosh/watchdog/issues/377>`__)
|
|
- [inotify] Fixed wrong source path after renaming a top level folder (`#515 <https://github.com/gorakhargosh/watchdog/pull/515>`__)
|
|
- [inotify] Removed delay from non-move events (`#477 <https://github.com/gorakhargosh/watchdog/pull/477>`__)
|
|
- [mac] Fixed a bug when calling ``FSEventsEmitter.stop()`` twice (`#466 <https://github.com/gorakhargosh/watchdog/pull/466>`__)
|
|
- [mac] Support for unscheduling deleted watch (`#541 <https://github.com/gorakhargosh/watchdog/issue/541>`__)
|
|
- [mac] Fixed missing field initializers and unused parameters in
|
|
``watchdog_fsevents.c``
|
|
- [snapshot] Don't walk directories without read permissions (`#408 <https://github.com/gorakhargosh/watchdog/pull/408>`__)
|
|
- [snapshot] Fixed a race condition crash when a directory is swapped for a file (`#513 <https://github.com/gorakhargosh/watchdog/pull/513>`__)
|
|
- [snasphot] Fixed an ``AttributeError`` about forgotten ``path_for_inode`` attr (`#436 <https://github.com/gorakhargosh/watchdog/issues/436>`__)
|
|
- [snasphot] Added the ``ignore_device=False`` parameter to the ctor (`597 <https://github.com/gorakhargosh/watchdog/pull/597>`__)
|
|
- [watchmedo] Fixed the path separator used (`#478 <https://github.com/gorakhargosh/watchdog/pull/478>`__)
|
|
- [watchmedo] Fixed the use of ``yaml.load()`` for ``yaml.safe_load()`` (`#453 <https://github.com/gorakhargosh/watchdog/issues/453>`__)
|
|
- [watchmedo] Handle all available signals (`#549 <https://github.com/gorakhargosh/watchdog/issue/549>`__)
|
|
- [watchmedo] Added the ``--debug-force-polling`` argument (`#404 <https://github.com/gorakhargosh/watchdog/pull/404>`__)
|
|
- [windows] Fixed issues when the observed directory is deleted (`#570 <https://github.com/gorakhargosh/watchdog/issues/570>`__ and `#601 <https://github.com/gorakhargosh/watchdog/pull/601>`__)
|
|
- [windows] ``WindowsApiEmitter`` made easier to subclass (`#344 <https://github.com/gorakhargosh/watchdog/pull/344>`__)
|
|
- [windows] Use separate ctypes DLL instances
|
|
- [windows] Generate sub created events only if ``recursive=True`` (`#454 <https://github.com/gorakhargosh/watchdog/pull/454>`__)
|
|
- Thanks to our beloved contributors: @BoboTiG, @LKleinNux, @rrzaripov,
|
|
@wildmichael, @TauPan, @segevfiner, @petrblahos, @QuantumEnergyE,
|
|
@jeffwidman, @kapsh, @nickoala, @petrblahos, @julianolf, @tonybaloney,
|
|
@mbakiev, @pR0Ps, javaguirre, @skurfer, @exarkun, @joshuaskelly,
|
|
@danilobellini, @Ajordat
|
|
|
|
|
|
0.9.0
|
|
~~~~~
|
|
|
|
2018-08-28 • `full history <https://github.com/gorakhargosh/watchdog/compare/v0.8.3...v0.9.0>`__
|
|
|
|
- Deleting the observed directory now emits a ``DirDeletedEvent`` event
|
|
- [bsd] Improved the platform detection (`#378 <https://github.com/gorakhargosh/watchdog/pull/378>`__)
|
|
- [inotify] Fixed a crash when the root directory being watched by was deleted (`#374 <https://github.com/gorakhargosh/watchdog/pull/374>`__)
|
|
- [inotify] Handle systems providing uClibc
|
|
- [linux] Fixed a possible ``DirDeletedEvent`` duplication when
|
|
deleting a directory
|
|
- [mac] Fixed unicode path handling ``fsevents2.py`` (`#298 <https://github.com/gorakhargosh/watchdog/pull/298>`__)
|
|
- [watchmedo] Added the ``--debug-force-polling`` argument (`#336 <https://github.com/gorakhargosh/watchdog/pull/336>`__)
|
|
- [windows] Fixed the ``FILE_LIST_DIRECTORY`` constant (`#376 <https://github.com/gorakhargosh/watchdog/pull/376>`__)
|
|
- Thanks to our beloved contributors: @vulpeszerda, @hpk42, @tamland, @senden9,
|
|
@gorakhargosh, @nolsto, @mafrosis, @DonyorM, @anthrotype, @danilobellini,
|
|
@pierregr, @ShinNoNoir, @adrpar, @gforcada, @pR0Ps, @yegorich, @dhke
|
|
|
|
|
|
0.8.3
|
|
~~~~~
|
|
|
|
2015-02-11 • `full history <https://github.com/gorakhargosh/watchdog/compare/v0.8.2...v0.8.3>`__
|
|
|
|
- Fixed the use of the root logger (`#274 <https://github.com/gorakhargosh/watchdog/issues/274>`__)
|
|
- [inotify] Refactored libc loading and improved error handling in
|
|
``inotify_c.py``
|
|
- [inotify] Fixed a possible unbound local error in ``inotify_c.py``
|
|
- Thanks to our beloved contributors: @mmorearty, @tamland, @tony,
|
|
@gorakhargosh
|
|
|
|
|
|
0.8.2
|
|
~~~~~
|
|
|
|
2014-10-29 • `full history <https://github.com/gorakhargosh/watchdog/compare/v0.8.1...v0.8.2>`__
|
|
|
|
- Event emitters are no longer started on schedule if ``Observer`` is not
|
|
already running
|
|
- [mac] Fixed usued arguments to pass clang compilation (`#265 <https://github.com/gorakhargosh/watchdog/pull/265>`__)
|
|
- [snapshot] Fixed a possible race condition crash on directory deletion (`#281 <https://github.com/gorakhargosh/watchdog/pull/281>`__)
|
|
- [windows] Fixed an error when watching the same folder again (`#270 <https://github.com/gorakhargosh/watchdog/pull/270>`__)
|
|
- Thanks to our beloved contributors: @tamland, @apetrone, @Falldog,
|
|
@theospears
|
|
|
|
|
|
0.8.1
|
|
~~~~~
|
|
|
|
2014-07-28 • `full history <https://github.com/gorakhargosh/watchdog/compare/v0.8.0...v0.8.1>`__
|
|
|
|
- Fixed ``anon_inode`` descriptors leakage (`#249 <https://github.com/gorakhargosh/watchdog/pull/249>`__)
|
|
- [inotify] Fixed thread stop dead lock (`#250 <https://github.com/gorakhargosh/watchdog/issues/250>`__)
|
|
- Thanks to our beloved contributors: @Witos, @adiroiban, @tamland
|
|
|
|
|
|
0.8.0
|
|
~~~~~
|
|
|
|
2014-07-02 • `full history <https://github.com/gorakhargosh/watchdog/compare/v0.7.1...v0.8.0>`__
|
|
|
|
- Fixed ``argh`` deprecation warnings (`#242 <https://github.com/gorakhargosh/watchdog/pull/242>`__)
|
|
- [snapshot] Methods returning internal stats info were replaced by
|
|
``mtime()``, ``inode()`` and ``path()`` methods
|
|
- [snapshot] Deprecated the ``walker_callback`` argument
|
|
- [watchmedo] Fixed ``auto-restart`` to terminate all children processes (`#225 <https://github.com/gorakhargosh/watchdog/pull/225>`__)
|
|
- [watchmedo] Added the ``--no-parallel`` argument (`#227 <https://github.com/gorakhargosh/watchdog/issues/227>`__)
|
|
- [windows] Fixed the value of ``INVALID_HANDLE_VALUE`` (`#123 <https://github.com/gorakhargosh/watchdog/issues/123>`__)
|
|
- [windows] Fixed octal usages to work with Python 3 as well (`#223 <https://github.com/gorakhargosh/watchdog/issues/223>`__)
|
|
- Thanks to our beloved contributors: @tamland, @Ormod, @berdario, @cro,
|
|
@BernieSumption, @pypingou, @gotcha, @tommorris, @frewsxcv
|
|
|
|
Keywords: python filesystem monitoring monitor FSEvents kqueue inotify ReadDirectoryChangesW polling DirectorySnapshot
|
|
Platform: UNKNOWN
|
|
Classifier: Development Status :: 3 - Alpha
|
|
Classifier: Environment :: Console
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: Intended Audience :: System Administrators
|
|
Classifier: License :: OSI Approved :: Apache Software License
|
|
Classifier: Natural Language :: English
|
|
Classifier: Operating System :: POSIX :: Linux
|
|
Classifier: Operating System :: MacOS :: MacOS X
|
|
Classifier: Operating System :: POSIX :: BSD
|
|
Classifier: Operating System :: Microsoft :: Windows :: Windows NT/2000
|
|
Classifier: Operating System :: OS Independent
|
|
Classifier: Programming Language :: Python
|
|
Classifier: Programming Language :: Python :: 2.7
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.4
|
|
Classifier: Programming Language :: Python :: 3.5
|
|
Classifier: Programming Language :: Python :: 3.6
|
|
Classifier: Programming Language :: Python :: 3.7
|
|
Classifier: Programming Language :: Python :: 3.8
|
|
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
Classifier: Programming Language :: C
|
|
Classifier: Topic :: Software Development :: Libraries
|
|
Classifier: Topic :: System :: Monitoring
|
|
Classifier: Topic :: System :: Filesystems
|
|
Classifier: Topic :: Utilities
|
|
Provides-Extra: watchmedo
|