1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
Metadata-Version: 1.0
Name: MacFSEvents
Version: 0.2.6
Summary: Thread-based interface to file system observation primitives.
Home-page: UNKNOWN
Author: Malthe Borch
Author-email: mborch@gmail.com
License: BSD
Description: .. contents::
Overview
========
.. role:: mod(emphasis)
:mod:`MacFSEvents` is a Python library that provides thread-safe
directory observation primitives using callbacks. It wraps the Mac OS
X ``FSEvents`` API in a C-extension.
Requirements:
- Mac OS X 10.5+ (Leopard)
This software was written by Malthe Borch <mborch@gmail.com>. The
:mod:`pyfsevents` module by Nicolas Dumazet was used for reference.
Why?
----
At this time of writing there are three other libraries that integrate
with the ``FSEvents`` API:
**pyobjc-framework-FSEvents**
These use the PyObjC bridge infrastructure which most applications
do not need.
**pyfsevents**
Not thread-safe (API is not designed to support it).
**fsevents**
Obsolete bindings to the socket API by John Sutherland.
These issues have been addressed in :mod:`MacFSEvents`. The library
provides a clean API and has full test coverage.
Note that :mod:`pyfsevents` has bindings to the file descriptor
observation primitives. This is not currently implemented by the
present library.
License
-------
Made available as-is under the BSD License.
Usage
=====
To observe a directory structure (recursively) under ``path``, we set
up an observer thread and schedule an event stream::
from fsevents import Observer
observer = Observer()
observer.start()
def callback(FileEvent):
...
from fsevents import Stream
stream = Stream(callback, path)
observer.schedule(stream)
Streams can observe any number of paths; simply pass them as
positional arguments (or using the ``*`` operator)::
stream = Stream(callback, *paths)
To start the observer in its own thread, use the ``start`` method::
observer.starts()
To start the observer in the current thread, use the ``run`` method
(it will block the thread until stopped from another thread)::
observer.run()
The callback function will be called when an event occurs. A
``FileEvent`` instance is passed to the callback and has 3 attributes:
``mask``, ``cookie`` and ``name``. ``name`` parameter contains the path
at which the event happened (may be a subdirectory) while ``mask``
parameter is the event mask [#]_.
To stop observation, simply unschedule the stream and stop the
observer::
observer.unschedule(stream)
observer.stop()
While the observer thread will automatically join your main thread at
this point, it doesn't hurt to be explicit about this::
observer.join()
We often want to know about events on a file level; to receive file
events instead of path events, pass in ``file_events=True`` to the
stream constructor::
def callback(event):
...
stream = Stream(callback, path, file_events=True)
The event object mimick the file events of the ``inotify`` kernel
extension available in newer linux kernels. It has the following
attributes:
``mask``
The mask field is a bitmask representing the event that occurred.
``cookie``
The cookie field is a unique identifier linking together two related but separate events. It is used to link together an ``IN_MOVED_FROM`` and an ``IN_MOVED_TO`` event.
``name``
The name field contains the name of the object to which the event occurred. This is the absolute filename.
Note that the logic to implement file events is implemented in Python;
a snapshot of the observed file system hierarchies is maintained and
used to monitor file events.
.. [#] See `FSEventStreamEventFlags <http://developer.apple.com/mac/library/documentation/Darwin/Reference/FSEvents_Ref/FSEvents_h/index.html#//apple_ref/c/tag/FSEventStreamEventFlags>`_ for a reference. To check for a particular mask, use the *bitwise and* operator ``&``.
Changelog
=========
0.2.6 (2012-03-17)
------------------
- Fixed compilation problen on newer platforms.
[nsfmc]
0.2.5 (2012-02-01)
------------------
- Ignore files that don't exist while recursing.
[bobveznat]
0.2.4 (2010-12-06)
------------------
- Prevent crashes on recursive folder delete and multiple folder add.
[totolici].
0.2.3 (2010-07-27)
------------------
- Fixed broken release.
0.2.2 (2010-07-26)
------------------
- Python 2.4 compatibility [howitz]
- Fixed an issue where the addition of a new directory would crash the
program when using file event monitoring [andymacp].
0.2.1 (2010-04-27)
------------------
- Fixed an import issue [andymacp].
0.2 (2010-04-26)
----------------
- Fixed issue where existing directories would be reported along with
a newly created one [marcboeker].
- Added support for file event monitoring.
- Fixed reference counting bug which could result in a segmentation
fault.
0.1 (2009-11-27)
----------------
- Initial public release.
Platform: Mac OS X
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 2.4
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
|