Metadata-Version: 1.1
Name: pollinotify
Version: 0.1.1
Summary: inotify wrapper providing polling with timeout for specified filesystem events
Home-page: http://jpembedded.solutions
Author: Julian Porter
Author-email: julian@jpembedded.solutions
License: UNKNOWN
Description: 1 Summary
        =========
        
        **pollinotify** is a simple extension module that wraps the Linux **inotify** service, providing a way to watch for 
        specific kinds of file events happening to specified files or in specified directories.  Its major selling points are
        that:
        
        1) It is *polled*, so instead of having to set up a background thread, or attach a separate event-watching package,
        the programmer calls it with an optional timeout, so it reports event that have already occurred, or waits for at most
        the specified time, or until an event occurs;
        2) The polling can wait for specific kinds of event.
        
        As the module depends on the **inotify** service, **it is only available on Linux**.
         
        
        2 Module Structure
        ==================
        
        2.1 Constants
        -------------
        
        A number of constants representing common Linux file system event codes, with friendly names:
        
        =============    ================  =================================================================
        Constant Name    Linux Name        Interpretation
        =============    ================  =================================================================
        Access           IN_ACCESS         Object accessed
        Modify           IN_MODIFY         Object modified
        Attributes       IN_ATTRIB         Object attributes modified
        Open             IN_OPEN		   File opened
        CloseWrite       IN_CLOSE_WRITE    File closed after contents changed
        CloseOther       IN_CLOSE_NOWRITE  File closed without contents changed
        Close            IN_CLOSE          File closed
        MoveFrom         IN_MOVED_FROM     Object moved from location
        MoveTo           IN_MOVED_TO       Object moved to location
        Move             IN_MOVE           Object moved
        MoveSelf         IN_MOVE_SELF      Object being monitored is deleted
        Create           IN_CREATE         Object created
        Delete           IN_DELETE         Object deleted
        DeleteSelf       IN_DELETE_SELF    Object being monitored is deleted
        Ignored          IN_IGNORED        Ignored
        DirEvent         IN_ISDIR          The monitored object to which the event occurred is a directory
        AllEvents        IN_ALL_EVENTS	   Any event
        =============    ================  =================================================================
        
        The constants are set up so they can be *or*-ed together to create meaningful combinations of event types.
        
        2.2 Utility functions
        ---------------------
        
        *maskAsString(mask)*
        	Takes a value equal to one or more of the event constants *or*-ed together
        	and returns a readable string representation, consisting of a space-separated
        	list of the names of the matching events
        	
        2.3 *FileEvent* class
        ---------------------
        
        *FileEvent* represents an event detected by the **inotify** service.  The event information is held
        in the attributes:
        
        *self.path*
        	The path to the file or directory suffering the event
        *self.mask*
        	Value representing the event(s) it suffered, represented as an *or*-ed collection of event codes, one for
        	each kind of event that was detected
        *self.decode()*
        	Returns a list of the names of the event types to which the event corresponds
        *self.matches(mask)*
        	Returns **True** if the argument is the code for one of the event types that the object represents, **False** 
        	otherwise
        	
        	
        In addition, if *e* is a *FileEvent* object then
        
        ::
        
        	str(e) = maskAsString(e.mask)
        	len(e) = len(e.decode())
        	x in e = e.matches(x)
        	
        
        2.4 *Watcher* class
        -------------------
        
        The fundamental class of the module.  It connects to the system **inotify** service and uses it to 
        poll for events in one or more specified file system paths.  Polling is based on a timeout,
        and so can be non-blocking.  
        
        It has the following methods:
             
        
        *__init__()*			
        	No-args constructor
        *addPath(path,mode=AllEvents)*
        	Adds *path* to the list of directories to be polled for events; polling 
        	will collect only events that match the *or*-ed event code mask 
        	specified in the optional argument *mode* (defaults to all events)
        *poll(timeout=0)*
        	Polls for events occurring on the specified paths, returning
        	**True** if any occur, **False** otherwise; times out
        	after *timeout* milliseconds, in which case it returns **False**
        *events(match=AllEvents)*		
        	Returns a list of *FileEvent* objects, one for
        	each event detected during last polling session
        	that matches the specified optional *or*-ed event code mask
        *nPaths()*			
        	Returns the number of paths currently registered with the Watcher
        *nEvents()*			
        	Returns the number of events detected in the last polling session
        
        
        If *w* is a *Watcher* instance then
        
        ::
        
        	len(w)  = w.nEvents()
        	iter(w) = iter(w.events())
        	
        
        3 EXAMPLE
        =========
        
        A simple example that polls with a timeout of 1 second and lists those events
        corresponding to file creation or modification (including **touch**) in the
        user's home directory.
        
        ::
        
            import pollinotify
        
            n=pollinotify.Watcher()
            n.addPath('~')
            while True:
                got=n.poll(timeout=1000)
                if got:
                    events=n.events(match=notify.CloseWrite)
                    print 'Got %s events' % len(events)
                    for event in events:
                        print event.path,event.mask,str(event)
                        
        
Platform: linux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Monitoring
