Monitor udev events:
>>> context = pyudev.Context()
>>> monitor = pyudev.Monitor.from_netlink(context)
>>> monitor.filter_by(subsystem='input')
>>> for action, device in monitor:
... print('{0}: {1}'.format(action, device))
...
A Monitor objects connects to the udev daemon and listens for changes to the device list. A monitor is created by connecting to the kernel daemon through netlink (see from_netlink()). Alternatively, connections to arbitrary daemons can be made using from_socket(), which is however only seldom of use.
Once the monitor is created, you can add a filter using filter_by() to drop incoming events in subsystems, which are not of interest to the application.
If the monitor is eventually set up, you can either iterate over the Monitor object. In this case, the monitor implicitly starts listening, and polls for incoming events. Such events are then yielded to the caller. Iteration is a blocking operation and does not integrate into external event loops. If such integration is required, you can explicitly enable the monitor (see enable_receiving()), and then retrieve a file descriptor using fileno(). This file descriptor can then be passed to classes like QSocketNotifier from Qt4.
Instances of this class can directly be given as udev_monitor * to functions wrapped through ctypes.
Create a monitor by connecting to the kernel daemon through netlink.
context is the Context to use. source is a string, describing the event source. Two sources are available:
Return a new Monitor object, which is connected to the given source. Raise ValueError, if an invalid source has been specified. Raise EnvironmentError, if the creation of the monitor failed.
Connect to an arbitrary udev daemon using the given socket_path.
context is the Context to use. socket_path is a byte or unicode string, pointing to an existing socket. If the path starts with a @, use an abstract namespace socket. If socket_path does not exist, fall back to an abstract namespace socket.
The caller is responsible for permissions and cleanup of the socket file.
Return a new Monitor object, which is connected to the given socket. Raise EnvironmentError, if the creation of the monitor failed.
Return the file description associated with this monitor as integer.
This is really a real file descriptor ;), which can be watched and select.select()ed.
Filter incoming events.
subsystem is a byte or unicode string with the name of a subsystem (e.g. 'input'). Only events originating from the given subsystem pass the filter and are handed to the caller.
If given, device_type is a byte or unicode string specifying the device type. Only devices with the given device type are propagated to the caller. If device_type is not given, no additional filter for a specific device type is installed.
These filters are executed inside the kernel, and client processes will usually not be woken up for device, that do not match these filters.
This method must be called before enable_receiving().
Filter incoming events by the given tag.
tag is a byte or unicode string with the name of a tag. Only events for devices which have this tag attached pass the filter and are handed to the caller.
Like with filter_by() this filter is also executed inside the kernel, so that client processes are usually not woken up for devices without the given tag.
This method must be called before enable_receiving().
Required udev version: 154
New in version 0.9.
Switch the monitor into listing mode.
Connect to the event source and receive incoming events. Only after calling this method, the monitor listens for incoming events.
Note
This method is implicitly called by __iter__(). You don’t need to call it explicitly, if you are iterating over the monitor.
Alias for enable_receiving()
Set the receive buffer size.
size is the requested buffer size in bytes, as integer.
Note
The CAP_NET_ADMIN capability must be contained in the effective capability set of the caller for this method to succeed. Otherwise EnvironmentError will be raised, with errno set to EPERM. Unprivileged processes typically lack this capability. You can check the capabilities of the current process with the python-prctl module:
>>> import prctl
>>> prctl.cap_effective.net_admin
Raise EnvironmentError, if the buffer size could not bet set.
New in version 0.13.
Receive a single device from the monitor.
The caller must make sure, that there are events available in the event queue. The call blocks, until a device is available.
If a device was available, return (action, device). device is the Device object describing the device. action is a string describing the action. udev informs about the following actions:
Raise EnvironmentError, if no device could be read.
Wait for incoming events and receive them upon arrival.
This methods implicitly calls enable_receiving(), and starts polling the fileno() of this monitor. If a event comes in, it receives the corresponding device and yields it to the caller.
The returned iterator is endless, and continues receiving devices without ever stopping.
Yields (action, device) (see receive_device() for a description).
A Thread class to observe a Monitor in background:
>>> context = pyudev.Context()
>>> monitor = pyudev.Monitor.from_netlink(context)
>>> monitor.filter_by(subsystem='input')
>>> def print_device_event(action, device):
... print('background event {0}: {1}'.format(action, device))
>>> observer = MonitorObserver(monitor, print_device_event, name='monitor-observer')
>>> observer.daemon
True
>>> observer.start()
In the above example, input device events will be printed in background, until stop() is called on observer.
Note
Instances of this class are always created as daemon thread. If you do not want to use daemon threads for monitoring, you need explicitly set daemon to False before invoking start().
Create a new observer for the given monitor.
monitor is the Monitor to observe. event_handler is a callable with the signature event_handler(action, device), where action is a string describing the event (see Monitor.receive_device()), and device is the Device object that caused this event. This callable is invoked for every device event received through monitor.
Warning
event_handler is always invoked in this background thread, and not in the calling thread.
args and kwargs are passed unchanged to the parent constructor of Thread.
Send a stop signal to the background thread.
The background thread will eventually exit, but it may still be running when this method returns. This method is essentially the asynchronous equivalent to stop().
Note
The underlying monitor is not stopped.
Stop the background thread.
Warning
Calling this method from the event_handler results in a dead lock. If you need to stop the observer from event_handler, use send_stop(), and be prepared to get some more events before the observer actually exits.
Send a stop signal to the backgroud (see send_stop()) and waits for the background thread to exit (see join()). After this method returns, it is guaranteed that the event_handler passed to MonitorObserver.__init__() is not longer called for any event from monitor.
Note
The underlying monitor is not stopped.