6239
|
1 |
# watcher.py - high-level interfaces to the Linux inotify subsystem
|
|
2 |
|
|
3 |
# Copyright 2006 Bryan O'Sullivan <bos@serpentine.com>
|
|
4 |
|
|
5 |
# This library is free software; you can redistribute it and/or modify
|
|
6 |
# it under the terms of version 2.1 of the GNU Lesser General Public
|
|
7 |
# License, incorporated herein by reference.
|
|
8 |
|
|
9 |
'''High-level interfaces to the Linux inotify subsystem.
|
|
10 |
|
|
11 |
The inotify subsystem provides an efficient mechanism for file status
|
|
12 |
monitoring and change notification.
|
|
13 |
|
|
14 |
The Watcher class hides the low-level details of the inotify
|
|
15 |
interface, and provides a Pythonic wrapper around it. It generates
|
|
16 |
events that provide somewhat more information than raw inotify makes
|
|
17 |
available.
|
|
18 |
|
|
19 |
The AutoWatcher class is more useful, as it automatically watches
|
|
20 |
newly-created directories on your behalf.'''
|
|
21 |
|
|
22 |
__author__ = "Bryan O'Sullivan <bos@serpentine.com>"
|
|
23 |
|
|
24 |
import _inotify as inotify
|
|
25 |
import array
|
|
26 |
import errno
|
|
27 |
import fcntl
|
|
28 |
import os
|
|
29 |
import termios
|
|
30 |
|
|
31 |
|
|
32 |
class Event(object):
|
|
33 |
'''Derived inotify event class.
|
|
34 |
|
|
35 |
The following fields are available:
|
|
36 |
|
|
37 |
mask: event mask, indicating what kind of event this is
|
|
38 |
|
|
39 |
cookie: rename cookie, if a rename-related event
|
|
40 |
|
|
41 |
path: path of the directory in which the event occurred
|
|
42 |
|
|
43 |
name: name of the directory entry to which the event occurred
|
|
44 |
(may be None if the event happened to a watched directory)
|
|
45 |
|
|
46 |
fullpath: complete path at which the event occurred
|
|
47 |
|
|
48 |
wd: watch descriptor that triggered this event'''
|
|
49 |
|
|
50 |
__slots__ = (
|
|
51 |
'cookie',
|
|
52 |
'fullpath',
|
|
53 |
'mask',
|
|
54 |
'name',
|
|
55 |
'path',
|
|
56 |
'raw',
|
|
57 |
'wd',
|
|
58 |
)
|
|
59 |
|
|
60 |
def __init__(self, raw, path):
|
|
61 |
self.path = path
|
|
62 |
self.raw = raw
|
|
63 |
if raw.name:
|
|
64 |
self.fullpath = path + '/' + raw.name
|
|
65 |
else:
|
|
66 |
self.fullpath = path
|
|
67 |
|
|
68 |
self.wd = raw.wd
|
|
69 |
self.mask = raw.mask
|
|
70 |
self.cookie = raw.cookie
|
|
71 |
self.name = raw.name
|
|
72 |
|
|
73 |
def __repr__(self):
|
|
74 |
r = repr(self.raw)
|
|
75 |
return 'Event(path=' + repr(self.path) + ', ' + r[r.find('(')+1:]
|
|
76 |
|
|
77 |
|
|
78 |
_event_props = {
|
|
79 |
'access': 'File was accessed',
|
|
80 |
'modify': 'File was modified',
|
|
81 |
'attrib': 'Attribute of a directory entry was changed',
|
|
82 |
'close_write': 'File was closed after being written to',
|
|
83 |
'close_nowrite': 'File was closed without being written to',
|
|
84 |
'open': 'File was opened',
|
|
85 |
'moved_from': 'Directory entry was renamed from this name',
|
|
86 |
'moved_to': 'Directory entry was renamed to this name',
|
|
87 |
'create': 'Directory entry was created',
|
|
88 |
'delete': 'Directory entry was deleted',
|
|
89 |
'delete_self': 'The watched directory entry was deleted',
|
|
90 |
'move_self': 'The watched directory entry was renamed',
|
|
91 |
'unmount': 'Directory was unmounted, and can no longer be watched',
|
|
92 |
'q_overflow': 'Kernel dropped events due to queue overflow',
|
|
93 |
'ignored': 'Directory entry is no longer being watched',
|
|
94 |
'isdir': 'Event occurred on a directory',
|
|
95 |
}
|
|
96 |
|
|
97 |
for k, v in _event_props.iteritems():
|
|
98 |
mask = getattr(inotify, 'IN_' + k.upper())
|
|
99 |
def getter(self):
|
|
100 |
return self.mask & mask
|
|
101 |
getter.__name__ = k
|
|
102 |
getter.__doc__ = v
|
|
103 |
setattr(Event, k, property(getter, doc=v))
|
|
104 |
|
|
105 |
del _event_props
|
|
106 |
|
|
107 |
|
|
108 |
class Watcher(object):
|
|
109 |
'''Provide a Pythonic interface to the low-level inotify API.
|
|
110 |
|
|
111 |
Also adds derived information to each event that is not available
|
|
112 |
through the normal inotify API, such as directory name.'''
|
|
113 |
|
|
114 |
__slots__ = (
|
|
115 |
'fd',
|
|
116 |
'_paths',
|
|
117 |
'_wds',
|
|
118 |
)
|
|
119 |
|
|
120 |
def __init__(self):
|
|
121 |
'''Create a new inotify instance.'''
|
|
122 |
|
|
123 |
self.fd = inotify.init()
|
|
124 |
self._paths = {}
|
|
125 |
self._wds = {}
|
|
126 |
|
|
127 |
def fileno(self):
|
|
128 |
'''Return the file descriptor this watcher uses.
|
|
129 |
|
|
130 |
Useful for passing to select and poll.'''
|
|
131 |
|
|
132 |
return self.fd
|
|
133 |
|
|
134 |
def add(self, path, mask):
|
|
135 |
'''Add or modify a watch.
|
|
136 |
|
|
137 |
Return the watch descriptor added or modified.'''
|
|
138 |
|
|
139 |
path = os.path.normpath(path)
|
|
140 |
wd = inotify.add_watch(self.fd, path, mask)
|
|
141 |
self._paths[path] = wd, mask
|
|
142 |
self._wds[wd] = path, mask
|
|
143 |
return wd
|
|
144 |
|
|
145 |
def remove(self, wd):
|
|
146 |
'''Remove the given watch.'''
|
|
147 |
|
|
148 |
inotify.remove_watch(self.fd, wd)
|
|
149 |
self._remove(wd)
|
|
150 |
|
|
151 |
def _remove(self, wd):
|
|
152 |
path_mask = self._wds.pop(wd, None)
|
|
153 |
if path_mask is not None:
|
|
154 |
self._paths.pop(path_mask[0])
|
|
155 |
|
|
156 |
def path(self, path):
|
|
157 |
'''Return a (watch descriptor, event mask) pair for the given path.
|
|
158 |
|
|
159 |
If the path is not being watched, return None.'''
|
|
160 |
|
|
161 |
return self._paths.get(path)
|
|
162 |
|
|
163 |
def wd(self, wd):
|
|
164 |
'''Return a (path, event mask) pair for the given watch descriptor.
|
|
165 |
|
|
166 |
If the watch descriptor is not valid or not associated with
|
|
167 |
this watcher, return None.'''
|
|
168 |
|
|
169 |
return self._wds.get(wd)
|
|
170 |
|
|
171 |
def read(self, bufsize=None):
|
|
172 |
'''Read a list of queued inotify events.
|
|
173 |
|
|
174 |
If bufsize is zero, only return those events that can be read
|
|
175 |
immediately without blocking. Otherwise, block until events are
|
|
176 |
available.'''
|
|
177 |
|
|
178 |
events = []
|
|
179 |
for evt in inotify.read(self.fd, bufsize):
|
|
180 |
events.append(Event(evt, self._wds[evt.wd][0]))
|
|
181 |
if evt.mask & inotify.IN_IGNORED:
|
|
182 |
self._remove(evt.wd)
|
|
183 |
elif evt.mask & inotify.IN_UNMOUNT:
|
|
184 |
self.close()
|
|
185 |
return events
|
|
186 |
|
|
187 |
def close(self):
|
|
188 |
'''Shut down this watcher.
|
|
189 |
|
|
190 |
All subsequent method calls are likely to raise exceptions.'''
|
|
191 |
|
|
192 |
os.close(self.fd)
|
|
193 |
self.fd = None
|
|
194 |
self._paths = None
|
|
195 |
self._wds = None
|
|
196 |
|
|
197 |
def __len__(self):
|
|
198 |
'''Return the number of active watches.'''
|
|
199 |
|
|
200 |
return len(self._paths)
|
|
201 |
|
|
202 |
def __iter__(self):
|
|
203 |
'''Yield a (path, watch descriptor, event mask) tuple for each
|
|
204 |
entry being watched.'''
|
|
205 |
|
|
206 |
for path, (wd, mask) in self._paths.iteritems():
|
|
207 |
yield path, wd, mask
|
|
208 |
|
|
209 |
def __del__(self):
|
|
210 |
if self.fd is not None:
|
|
211 |
os.close(self.fd)
|
|
212 |
|
|
213 |
ignored_errors = [errno.ENOENT, errno.EPERM, errno.ENOTDIR]
|
|
214 |
|
|
215 |
def add_iter(self, path, mask, onerror=None):
|
|
216 |
'''Add or modify watches over path and its subdirectories.
|
|
217 |
|
|
218 |
Yield each added or modified watch descriptor.
|
|
219 |
|
|
220 |
To ensure that this method runs to completion, you must
|
|
221 |
iterate over all of its results, even if you do not care what
|
|
222 |
they are. For example:
|
|
223 |
|
|
224 |
for wd in w.add_iter(path, mask):
|
|
225 |
pass
|
|
226 |
|
|
227 |
By default, errors are ignored. If optional arg "onerror" is
|
|
228 |
specified, it should be a function; it will be called with one
|
|
229 |
argument, an OSError instance. It can report the error to
|
|
230 |
continue with the walk, or raise the exception to abort the
|
|
231 |
walk.'''
|
|
232 |
|
|
233 |
# Add the IN_ONLYDIR flag to the event mask, to avoid a possible
|
|
234 |
# race when adding a subdirectory. In the time between the
|
|
235 |
# event being queued by the kernel and us processing it, the
|
|
236 |
# directory may have been deleted, or replaced with a different
|
|
237 |
# kind of entry with the same name.
|
|
238 |
|
|
239 |
submask = mask | inotify.IN_ONLYDIR
|
|
240 |
|
|
241 |
try:
|
|
242 |
yield self.add(path, mask)
|
|
243 |
except OSError, err:
|
|
244 |
if onerror and err.errno not in self.ignored_errors:
|
|
245 |
onerror(err)
|
|
246 |
for root, dirs, names in os.walk(path, topdown=False, onerror=onerror):
|
|
247 |
for d in dirs:
|
|
248 |
try:
|
|
249 |
yield self.add(root + '/' + d, submask)
|
|
250 |
except OSError, err:
|
|
251 |
if onerror and err.errno not in self.ignored_errors:
|
|
252 |
onerror(err)
|
|
253 |
|
|
254 |
def add_all(self, path, mask, onerror=None):
|
|
255 |
'''Add or modify watches over path and its subdirectories.
|
|
256 |
|
|
257 |
Return a list of added or modified watch descriptors.
|
|
258 |
|
|
259 |
By default, errors are ignored. If optional arg "onerror" is
|
|
260 |
specified, it should be a function; it will be called with one
|
|
261 |
argument, an OSError instance. It can report the error to
|
|
262 |
continue with the walk, or raise the exception to abort the
|
|
263 |
walk.'''
|
|
264 |
|
|
265 |
return [w for w in self.add_iter(path, mask, onerror)]
|
|
266 |
|
|
267 |
|
|
268 |
class AutoWatcher(Watcher):
|
|
269 |
'''Watcher class that automatically watches newly created directories.'''
|
|
270 |
|
|
271 |
__slots__ = (
|
|
272 |
'addfilter',
|
|
273 |
)
|
|
274 |
|
|
275 |
def __init__(self, addfilter=None):
|
|
276 |
'''Create a new inotify instance.
|
|
277 |
|
|
278 |
This instance will automatically watch newly created
|
|
279 |
directories.
|
|
280 |
|
|
281 |
If the optional addfilter parameter is not None, it must be a
|
|
282 |
callable that takes one parameter. It will be called each time
|
|
283 |
a directory is about to be automatically watched. If it returns
|
|
284 |
True, the directory will be watched if it still exists,
|
|
285 |
otherwise, it will beb skipped.'''
|
|
286 |
|
|
287 |
super(AutoWatcher, self).__init__()
|
|
288 |
self.addfilter = addfilter
|
|
289 |
|
|
290 |
_dir_create_mask = inotify.IN_ISDIR | inotify.IN_CREATE
|
|
291 |
|
|
292 |
def read(self, bufsize=None):
|
|
293 |
events = super(AutoWatcher, self).read(bufsize)
|
|
294 |
for evt in events:
|
|
295 |
if evt.mask & self._dir_create_mask == self._dir_create_mask:
|
|
296 |
if self.addfilter is None or self.addfilter(evt):
|
|
297 |
parentmask = self._wds[evt.wd][1]
|
|
298 |
# See note about race avoidance via IN_ONLYDIR above.
|
|
299 |
mask = parentmask | inotify.IN_ONLYDIR
|
|
300 |
try:
|
|
301 |
self.add_all(evt.fullpath, mask)
|
|
302 |
except OSError, err:
|
|
303 |
if err.errno not in self.ignored_errors:
|
|
304 |
raise
|
|
305 |
return events
|
|
306 |
|
|
307 |
|
|
308 |
class Threshold(object):
|
|
309 |
'''Class that indicates whether a file descriptor has reached a
|
|
310 |
threshold of readable bytes available.
|
|
311 |
|
|
312 |
This class is not thread-safe.'''
|
|
313 |
|
|
314 |
__slots__ = (
|
|
315 |
'fd',
|
|
316 |
'threshold',
|
|
317 |
'_iocbuf',
|
|
318 |
)
|
|
319 |
|
|
320 |
def __init__(self, fd, threshold=1024):
|
|
321 |
self.fd = fd
|
|
322 |
self.threshold = threshold
|
|
323 |
self._iocbuf = array.array('i', [0])
|
|
324 |
|
|
325 |
def readable(self):
|
|
326 |
'''Return the number of bytes readable on this file descriptor.'''
|
|
327 |
|
|
328 |
fcntl.ioctl(self.fd, termios.FIONREAD, self._iocbuf, True)
|
|
329 |
return self._iocbuf[0]
|
|
330 |
|
|
331 |
def __call__(self):
|
|
332 |
'''Indicate whether the number of readable bytes has met or
|
|
333 |
exceeded the threshold.'''
|
|
334 |
|
|
335 |
return self.readable() >= self.threshold
|