Monitor – monitor devices

class pyudev.Monitor

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.

classmethod from_netlink(context, source=u'udev')

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:

'udev' (the default)

Events emitted after udev as registered and configured the device. This is the absolutely recommended source for applications.

'kernel'

Events emitted directly after the kernel has seen the device. The device has not yet been configured by udev and might not be usable at all. Never use this, unless you know what you are doing.

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.

classmethod from_socket(context, socket_path)

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.

context

The Context to which this monitor is bound.

New in version 0.5.

fileno()

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_by(subsystem, device_type=None)

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_by_tag(tag)

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.

enable_receiving()

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.

start()

Alias for enable_receiving()

set_receive_buffer_size(size)

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_device()

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:

'add'

A device has been added (e.g. a USB device was plugged in)

'remove'

A device has been removed (e.g. a USB device was unplugged)

'change'

Something about the device changed (e.g. a device property)

'move'

The device was renamed, moved, or re-parented

Raise EnvironmentError, if no device could be read.

__iter__()

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).