`pyudev` - libudev binding¶

A binding to libudev.

The Context provides the connection to the udev device database and enumerates devices. Individual devices are represented by the Device class.

Device monitoring is provided by Monitor and MonitorObserver. With pyudev.pyqt4, pyudev.pyside, pyudev.glib and pyudev.wx device monitoring can be integrated into the event loop of various GUI toolkits.

`Context`	A device database connection.
`Device`	A single device with attached attributes and properties.
`Devices`	Class for constructing `Device` objects from various kinds of data.
`Monitor`	A synchronous device event monitor.
`MonitorObserver`	An asynchronous observer for device events.

Version information¶

pyudev.__version__¶

The version of pyudev as string. This string contains a major and a minor version number, and optionally a revision in the form major.minor.revision. As said, the revision part is optional and may not be present.

This attribute is mainly intended for display purposes, use __version_info__ to check the version of pyudev in source code.

pyudev.__version_info__¶: The version of pyudev as tuple of integers. This tuple contains a major and a minor number, and optionally a revision number in the form (major, minor, revision). As said, the revision component is optional and may not be present.

New in version 0.10.

pyudev.udev_version()¶

Get the version of the underlying udev library.

udev doesn’t use a standard major-minor versioning scheme, but instead labels releases with a single consecutive number. Consequently, the version number returned by this function is a single integer, and not a tuple (like for instance the interpreter version in sys.version_info).

As libudev itself does not provide a function to query the version number, this function calls the udevadm utility, so be prepared to catch EnvironmentError and CalledProcessError if you call this function.

Return the version number as single integer. Raise ValueError, if the version number retrieved from udev could not be converted to an integer. Raise EnvironmentError, if udevadm was not found, or could not be executed. Raise subprocess.CalledProcessError, if udevadm returned a non-zero exit code. On Python 2.7 or newer, the output attribute of this exception is correctly set.

New in version 0.8.

`Context` – UDev database context¶

class pyudev.Context¶

A device database connection.

This class represents a connection to the udev device database, and is really the central object to access udev. You need an instance of this class for almost anything else in pyudev.

This class itself gives access to various udev configuration data (e.g. sys_path, device_path), and provides device enumeration (list_devices()).

Instances of this class can directly be given as udev * to functions wrapped through ctypes.

__init__()¶: Create a new context.

sys_path¶: The sysfs mount point defaulting to /sys' as unicode string.

device_path¶: The device directory path defaulting to /dev as unicode string.

run_path¶

The run runtime directory path defaulting to /run as unicode string.

Required udev version: 167

New in version 0.10.

log_priority¶

The logging priority of the interal logging facitility of udev as integer with a standard syslog priority. Assign to this property to change the logging priority.

UDev uses the standard syslog priorities. Constants for these priorities are defined in the syslog module in the standard library:

>>> import syslog
>>> context = pyudev.Context()
>>> context.log_priority = syslog.LOG_DEBUG

New in version 0.9.

list_devices(**kwargs)¶

List all available devices.

The arguments of this method are the same as for Enumerator.match(). In fact, the arguments are simply passed straight to method match().

This function creates and returns an Enumerator object, that can be used to filter the list of devices, and eventually retrieve Device objects representing matching devices.

Changed in version 0.8: Accept keyword arguments now for easy matching.

`Enumerator` – device enumeration and filtering¶

class pyudev.Enumerator¶

A filtered iterable of devices.

To retrieve devices, simply iterate over an instance of this class. This operation yields Device objects representing the available devices.

Before iteration the device list can be filtered by subsystem or by property values using match_subsystem() and match_property(). Multiple subsystem (property) filters are combined using a logical OR, filters of different types are combined using a logical AND. The following filter for instance:

devices.match_subsystem('block').match_property(
    'ID_TYPE', 'disk').match_property('DEVTYPE', 'disk')

means the following:

subsystem == 'block' and (ID_TYPE == 'disk' or DEVTYPE == 'disk')

Once added, a filter cannot be removed anymore. Create a new object instead.

Instances of this class can directly be given as given udev_enumerate * to functions wrapped through ctypes.

match(**kwargs)¶

Include devices according to the rules defined by the keyword arguments. These keyword arguments are interpreted as follows:

The value for the keyword argument subsystem is forwarded to match_subsystem().
The value for the keyword argument sys_name is forwared to match_sys_name().
The value for the keyword argument tag is forwared to match_tag().
The value for the keyword argument parent is forwared to match_parent().
All other keyword arguments are forwareded one by one to match_property(). The keyword argument itself is interpreted as property name, the value of the keyword argument as the property value.

All keyword arguments are optional, calling this method without no arguments at all is simply a noop.

Return the instance again.

New in version 0.8.

Changed in version 0.13: Add parent keyword.

match_subsystem(subsystem, nomatch=False)¶

Include all devices, which are part of the given subsystem.

subsystem is either a unicode string or a byte string, containing the name of the subsystem. If nomatch is True (default is False), the match is inverted: A device is only included if it is not part of the given subsystem.

Note that, if a device has no subsystem, it is not included either with value of nomatch True or with value of nomatch False.

Return the instance again.

match_sys_name(sys_name)¶

Include all devices with the given name.

sys_name is a byte or unicode string containing the device name.

Return the instance again.

New in version 0.8.

match_property(prop, value)¶

Include all devices, whose prop has the given value.

prop is either a unicode string or a byte string, containing the name of the property to match. value is a property value, being one of the following types:

int()
bool()
A byte string
Anything convertable to a unicode string (including a unicode string itself)

Return the instance again.

match_attribute(attribute, value, nomatch=False)¶

Include all devices, whose attribute has the given value.

attribute is either a unicode string or a byte string, containing the name of a sys attribute to match. value is an attribute value, being one of the following types:

int(),
bool()
A byte string
Anything convertable to a unicode string (including a unicode string itself)

If nomatch is True (default is False), the match is inverted: A device is include if the attribute does not match the given value.

Note

If nomatch is True, devices which do not have the given attribute at all are also included. In other words, with nomatch=True the given attribute is not guaranteed to exist on all returned devices.

Return the instance again.

match_tag(tag)¶

Include all devices, which have the given tag attached.

tag is a byte or unicode string containing the tag name.

Return the instance again.

Required udev version: 154

New in version 0.6.

match_parent(parent)¶

Include all devices on the subtree of the given parent device.

The parent device itself is also included.

parent is a Device.

Return the instance again.

Required udev version: 172

New in version 0.13.

match_is_initialized()¶

Include only devices, which are initialized.

Initialized devices have properly set device node permissions and context, and are (in case of network devices) fully renamed.

Currently this will not affect devices which do not have device nodes and are not network interfaces.

Return the instance again.

See also

Device.is_initialized

Required udev version: 165

New in version 0.8.

__iter__()¶

Iterate over all matching devices.

Yield Device objects.

`Devices` – constructing Device objects¶

class pyudev.Devices¶

Class for constructing Device objects from various kinds of data.

Construction of device objects

classmethod from_path(context, path)¶

Create a device from a device path. The path may or may not start with the sysfs mount point:

>>> from pyudev import Context, Device
>>> context = Context()
>>> Devices.from_path(context, '/devices/platform')
Device(u'/sys/devices/platform')
>>> Devices.from_path(context, '/sys/devices/platform')
Device(u'/sys/devices/platform')

context is the Context in which to search the device. path is a device path as unicode or byte string.

Return a Device object for the device. Raise DeviceNotFoundAtPathError, if no device was found for path.

New in version 0.18.

classmethod from_sys_path(context, sys_path)¶

Create a new device from a given sys_path:

>>> from pyudev import Context, Device
>>> context = Context()
>>> Devices.from_sys_path(context, '/sys/devices/platform')
Device(u'/sys/devices/platform')

context is the Context in which to search the device. sys_path is a unicode or byte string containing the path of the device inside sysfs with the mount point included.

Return a Device object for the device. Raise DeviceNotFoundAtPathError, if no device was found for sys_path.

New in version 0.18.

classmethod from_name(context, subsystem, sys_name)¶

Create a new device from a given subsystem and a given sys_name:

>>> from pyudev import Context, Device
>>> context = Context()
>>> sda = Devices.from_name(context, 'block', 'sda')
>>> sda
Device(u'/sys/devices/pci0000:00/0000:00:1f.2/host0/target0:0:0/0:0:0:0/block/sda')
>>> sda == Devices.from_path(context, '/block/sda')

context is the Context in which to search the device. subsystem and sys_name are byte or unicode strings, which denote the subsystem and the name of the device to create.

Return a Device object for the device. Raise DeviceNotFoundByNameError, if no device was found with the given name.

New in version 0.18.

classmethod from_device_number(context, typ, number)¶

Create a new device from a device number with the given device type:

>>> import os
>>> from pyudev import Context, Device
>>> ctx = Context()
>>> major, minor = 8, 0
>>> device = Devices.from_device_number(context, 'block',
...     os.makedev(major, minor))
>>> device
Device(u'/sys/devices/pci0000:00/0000:00:11.0/host0/target0:0:0/0:0:0:0/block/sda')
>>> os.major(device.device_number), os.minor(device.device_number)
(8, 0)

Use os.makedev() to construct a device number from a major and a minor device number, as shown in the example above.

Warning

Device numbers are not unique across different device types. Passing a correct number with a wrong type may silently yield a wrong device object, so make sure to pass the correct device type.

context is the Context, in which to search the device. type is either 'char' or 'block', according to whether the device is a character or block device. number is the device number as integer.

Return a Device object for the device with the given device number. Raise DeviceNotFoundByNumberError, if no device was found with the given device type and number.

New in version 0.18.

classmethod from_device_file(context, filename)¶

Create a new device from the given device file:

>>> from pyudev import Context, Device
>>> context = Context()
>>> device = Devices.from_device_file(context, '/dev/sda')
>>> device
Device(u'/sys/devices/pci0000:00/0000:00:0d.0/host2/target2:0:0/2:0:0:0/block/sda')
>>> device.device_node
u'/dev/sda'

Warning

Though the example seems to suggest that device.device_node == filename holds with device = Devices.from_device_file(context, filename), this is only true in a majority of cases. There can be devices, for which this relation is actually false! Thus, do not expect device_node to be equal to the given filename for the returned Device. Especially, use device_node if you need the device file of a Device created with this method afterwards.

context is the Context in which to search the device. filename is a string containing the path of a device file.

Return a Device representing the given device file. Raise DeviceNotFoundByFileError if filename is no device file at all or if filename does not exist or if its metadata was inaccessible.

New in version 0.18.

classmethod from_environment(context)¶

Create a new device from the process environment (as in os.environ).

This only works reliable, if the current process is called from an udev rule, and is usually used for tools executed from IMPORT= rules. Use this method to create device objects in Python scripts called from udev rules.

context is the library Context.

Return a Device object constructed from the environment. Raise DeviceNotFoundInEnvironmentError, if no device could be created from the environment.

Required udev version: 152

New in version 0.18.

classmethod METHODS()¶

Return methods that obtain a Device from a variety of different data.

Returns: a list of from_* methods.
Return type: list of class methods

New in version 0.18.

`Device` – accessing device information¶

class pyudev.Device¶

A single device with attached attributes and properties.

This class subclasses the Mapping ABC, providing a read-only dictionary mapping property names to the corresponding values. Therefore all well-known dicitionary methods and operators (e.g. .keys(), .items(), in) are available to access device properties.

Aside of the properties, a device also has a set of udev-specific attributes like the path inside sysfs.

Device objects compare equal and unequal to other devices and to strings (based on device_path). However, there is no ordering on Device objects, and the corresponding operators >, <, <= and >= raise TypeError.

Warning

Never use object identity (is operator) to compare Device objects. pyudev may create multiple Device objects for the same device. Instead compare devices by value using == or !=.

Device objects are hashable and can therefore be used as keys in dictionaries and sets.

They can also be given directly as udev_device * to functions wrapped through ctypes.

Construction of device objects

classmethod from_path(context, path)¶: New in version 0.4.

Deprecated since version 0.18: Use Devices.from_path instead.

classmethod from_sys_path(context, sys_path)¶: Changed in version 0.4: Raise NoSuchDeviceError instead of returning None, if no device was found for sys_path.

Changed in version 0.5: Raise DeviceNotFoundAtPathError instead of NoSuchDeviceError.

Deprecated since version 0.18: Use Devices.from_sys_path instead.

classmethod from_name(context, subsystem, sys_name)¶: New in version 0.5.

Deprecated since version 0.18: Use Devices.from_name instead.

classmethod from_device_number(context, typ, number)¶: New in version 0.11.

Deprecated since version 0.18: Use Devices.from_device_number instead.

classmethod from_device_file(context, filename)¶: New in version 0.15.

Deprecated since version 0.18: Use Devices.from_device_file instead.

classmethod from_environment(context)¶: New in version 0.6.

Deprecated since version 0.18: Use Devices.from_environment instead.

General attributes

context¶: The Context to which this device is bound.

New in version 0.5.

sys_path¶: Absolute path of this device in sysfs including the sysfs mount point as unicode string.

sys_name¶: Device file name inside sysfs as unicode string.

sys_number¶

The trailing number of the sys_name as unicode string, or None, if the device has no trailing number in its name.

Note

The number is returned as unicode string to preserve the exact format of the number, especially any leading zeros:

>>> from pyudev import Context, Device
>>> context = Context()
>>> device = Devices.from_path(context, '/sys/devices/LNXSYSTM:00')
>>> device.sys_number
u'00'

To work with numbers, explicitly convert them to ints:

>>> int(device.sys_number)
0

New in version 0.11.

device_path¶

Kernel device path as unicode string. This path uniquely identifies a single device.

Unlike sys_path, this path does not contain the sysfs mount point. However, the path is absolute and starts with a slash '/'.

tags¶

A Tags object representing the tags attached to this device.

The Tags object supports a test for a single tag as well as iteration over all tags:

>>> from pyudev import Context
>>> context = Context()
>>> device = next(iter(context.list_devices(tag='systemd')))
>>> 'systemd' in device.tags
True
>>> list(device.tags)
[u'seat', u'systemd', u'uaccess']

Tags are arbitrary classifiers that can be attached to devices by udev scripts and daemons. For instance, systemd uses tags for multi-seat support.

Required udev version: 154

New in version 0.6.

Changed in version 0.13: Return a Tags object now.

Device driver and subsystem

subsystem¶

Name of the subsystem this device is part of as unicode string.

Returns: name of subsystem if found, else None
Return type: unicode string or NoneType

driver¶: The driver name as unicode string, or None, if there is no driver for this device.

New in version 0.5.

device_type¶

Device type as unicode string, or None, if the device type is unknown.

>>> from pyudev import Context
>>> context = Context()
>>> for device in context.list_devices(subsystem='net'):
...     '{0} - {1}'.format(device.sys_name, device.device_type or 'ethernet')
...
u'eth0 - ethernet'
u'wlan0 - wlan'
u'lo - ethernet'
u'vboxnet0 - ethernet'

New in version 0.10.

Device nodes

device_node¶

Absolute path to the device node of this device as unicode string or None, if this device doesn’t have a device node. The path includes the device directory (see Context.device_path).

This path always points to the actual device node associated with this device, and never to any symbolic links to this device node. See device_links to get a list of symbolic links to this device node.

Warning

For devices created with from_device_file(), the value of this property is not necessary equal to the filename given to from_device_file().

device_number¶

The device number of the associated device as integer, or 0, if no device number is associated.

Use os.major() and os.minor() to decompose the device number into its major and minor number:

>>> import os
>>> from pyudev import Context, Device
>>> context = Context()
>>> sda = Devices.from_name(context, 'block', 'sda')
>>> sda.device_number
2048L
>>> (os.major(sda.device_number), os.minor(sda.device_number))
(8, 0)

For devices with an associated device_node, this is the same as the st_rdev field of the stat result of the device_node:

>>> os.stat(sda.device_node).st_rdev
2048

New in version 0.11.

device_links¶

An iterator, which yields the absolute paths (including the device directory, see Context.device_path) of all symbolic links pointing to the device_node of this device. The paths are unicode strings.

UDev can create symlinks to the original device node (see device_node) inside the device directory. This is often used to assign a constant, fixed device node to devices like removeable media, which technically do not have a constant device node, or to map a single device into multiple device hierarchies. The property provides access to all such symbolic links, which were created by UDev for this device.

Warning

Links are not necessarily resolved by Devices.from_device_file(). Hence do not rely on Devices.from_device_file(context, link).device_path == device.device_path from any link in device.device_links.

Device initialization time

is_initialized¶

True, if the device is initialized, False otherwise.

A device is initialized, if udev has already handled this device and has set up device node permissions and context, or renamed a network device.

Consequently, this property is only implemented for devices with a device node or for network devices. On all other devices this property is always True.

It is not recommended, that you use uninitialized devices.

See also

time_since_initialized

Required udev version: 165

New in version 0.8.

time_since_initialized¶

The time elapsed since initialization as timedelta.

This property is only implemented on devices, which need to store properties in the udev database. On all other devices this property is simply zero timedelta.

See also

is_initialized

Required udev version: 165

New in version 0.8.

Device hierarchy

parent¶: The parent Device or None, if there is no parent device.

ancestors¶

Yield all ancestors of this device from bottom to top.

Return an iterator yielding a Device object for each ancestor of this device from bottom to top.

New in version 0.16.

children¶

Yield all direct children of this device.

Note

In udev, parent-child relationships are generally ambiguous, i.e. a parent can have multiple children, and a child can have multiple parents. Hence, child.parent == parent does generally not hold for all child objects in parent.children. In other words, the parent of a device in this property can be different from this device!

Note

As the underlying library does not provide any means to directly query the children of a device, this property performs a linear search through all devices.

Return an iterable yielding a Device object for each direct child of this device.

Required udev version: 172

Changed in version 0.13: Requires udev version 172 now.

find_parent(subsystem, device_type=None)¶

Find the parent device with the given subsystem and device_type.

subsystem is a byte or unicode string containing the name of the subsystem, in which to search for the parent. device_type is a byte or unicode string holding the expected device type of the parent. It can be None (the default), which means, that no specific device type is expected.

Return a parent Device within the given subsystem and, if device_type is not None, with the given device_type, or None, if this device has no parent device matching these constraints.

New in version 0.9.

Device events

action¶

The device event action as string, or None, if this device was not received from a Monitor.

Usual actions are:

'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)
'online': The device is online now
'offline': The device is offline now

Warning

Though the actions listed above are the most common, this property may return other values, too, so be prepared to handle unknown actions!

New in version 0.16.

sequence_number¶: The device event sequence number as integer, or 0 if this device has no sequence number, i.e. was not received from a Monitor.

New in version 0.16.

Device properties

__iter__()¶

Iterate over the names of all properties defined for this device.

Return a generator yielding the names of all properties of this device as unicode strings.

Deprecated since version 0.21: Will be removed in 1.0. Access properties with Device.properties.

__len__()¶: Return the amount of properties defined for this device as integer.

Deprecated since version 0.21: Will be removed in 1.0. Access properties with Device.properties.

__getitem__(prop)¶

Get the given property from this device.

prop is a unicode or byte string containing the name of the property.

Return the property value as unicode string, or raise a KeyError, if the given property is not defined for this device.

Deprecated since version 0.21: Will be removed in 1.0. Access properties with Device.properties.

asint(prop)¶

Get the given property from this device as integer.

prop is a unicode or byte string containing the name of the property.

Return the property value as integer. Raise a KeyError, if the given property is not defined for this device, or a ValueError, if the property value cannot be converted to an integer.

Deprecated since version 0.21: Will be removed in 1.0. Use Device.properties.asint() instead.

asbool(prop)¶

Get the given property from this device as boolean.

A boolean property has either a value of '1' or of '0', where '1' stands for True, and '0' for False. Any other value causes a ValueError to be raised.

prop is a unicode or byte string containing the name of the property.

Return True, if the property value is '1' and False, if the property value is '0'. Any other value raises a ValueError. Raise a KeyError, if the given property is not defined for this device.

Deprecated since version 0.21: Will be removed in 1.0. Use Device.properties.asbool() instead.

Sysfs attributes

attributes¶

The system attributes of this device as read-only Attributes mapping.

System attributes are basically normal files inside the the device directory. These files contain all sorts of information about the device, which may not be reflected by properties. These attributes are commonly used for matching in udev rules, and can be printed using udevadm info --attribute-walk.

The values of these attributes are not always proper strings, and can contain arbitrary bytes.

New in version 0.5.

Deprecated members

traverse()¶

Traverse all parent devices of this device from bottom to top.

Return an iterable yielding all parent devices as Device objects, not including the current device. The last yielded Device is the top of the device hierarchy.

Deprecated since version 0.16: Will be removed in 1.0. Use ancestors instead.

class pyudev.Attributes¶

udev attributes for Device objects.

New in version 0.5.

device¶: The Device to which these attributes belong.

asstring(attribute)¶

Get the given attribute for the device as unicode string.

Parameters

attribute (unicode or byte string) – the key for an attribute value

Returns

the value corresponding to attribute, as unicode

Return type

unicode

Raises

KeyError – if no value found for attribute
UnicodeDecodeError – if value is not convertible

asint(attribute)¶

Get the given attribute as an int.

Parameters

attribute (unicode or byte string) – the key for an attribute value

Returns

the value corresponding to attribute, as an int

Return type

int

Raises

KeyError – if no value found for attribute
UnicodeDecodeError – if value is not convertible to unicode
ValueError – if unicode value can not be converted to an int

asbool(attribute)¶

Get the given attribute from this device as a bool.

Parameters

attribute (unicode or byte string) – the key for an attribute value

Returns

the value corresponding to attribute, as bool

Return type

bool

Raises

KeyError – if no value found for attribute
UnicodeDecodeError – if value is not convertible to unicode
ValueError – if unicode value can not be converted to a bool

A boolean attribute has either a value of '1' or of '0', where '1' stands for True, and '0' for False. Any other value causes a ValueError to be raised.

class pyudev.Tags¶

A iterable over Device tags.

Subclasses the Container and the Iterable ABC.

__iter__()¶

Iterate over all tags.

Yield each tag as unicode string.

__contains__(tag)¶

Check for existence of tag.

tag is a tag as unicode string.

Return True, if tag is attached to the device, False otherwise.

`Device` exceptions¶

class pyudev.DeviceNotFoundError¶: An exception indicating that no Device was found.

Changed in version 0.5: Rename from NoSuchDeviceError to its current name.

class pyudev.DeviceNotFoundAtPathError(sys_path)¶

A DeviceNotFoundError indicating that no Device was found at a given path.

property sys_path¶: The path that caused this error as string.

class pyudev.DeviceNotFoundByNameError(subsystem, sys_name)¶

A DeviceNotFoundError indicating that no Device was found with a given name.

property subsystem¶: The subsystem that caused this error as string.

property sys_name¶: The sys name that caused this error as string.

class pyudev.DeviceNotFoundByNumberError(typ, number)¶

A DeviceNotFoundError indicating, that no Device was found for a given device number.

property device_number¶: The device number causing this error as integer.

property device_type¶: The device type causing this error as string. Either 'char' or 'block'.

class pyudev.DeviceNotFoundInEnvironmentError¶: A DeviceNotFoundError indicating, that no Device could be constructed from the process environment.

`Monitor` – device monitoring¶

class pyudev.Monitor¶

A synchronous device event monitor.

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

>>> from pyudev import Context, Monitor
>>> context = Context()
>>> monitor = Monitor.from_netlink(context)

Once the monitor is created, you can add a filter using filter_by() or filter_by_tag() to drop incoming events in subsystems, which are not of interest to the application:

>>> monitor.filter_by('input')

When the monitor is eventually set up, you can either poll for events synchronously:

>>> device = monitor.poll(timeout=3)
>>> if device:
...     print('{0.action}: {0}'.format(device))
...

Or you can monitor events asynchronously with MonitorObserver.

To integrate into various event processing frameworks, the monitor provides a selectable file description by fileno(). However, do not read or write directly on this file descriptor.

Instances of this class can directly be given as udev_monitor * to functions wrapped through ctypes.

Changed in version 0.16: Remove from_socket() which is deprecated, and even removed in recent udev versions.

classmethod from_netlink(context, source='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.

context¶: The Context to which this monitor is bound.

New in version 0.5.

started¶: True, if this monitor was started, False otherwise. Readonly.

See also

start()

New in version 0.16.

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.

Changed in version 0.15: This method can also be after start() now.

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.

Required udev version: 154

New in version 0.9.

Changed in version 0.15: This method can also be after start() now.

remove_filter()¶

Remove any filters installed with filter_by() or filter_by_tag() from this monitor.

Warning

Up to udev 181 (and possibly even later versions) the underlying udev_monitor_filter_remove() seems to be broken. If used with affected versions this method always raises ValueError.

Raise EnvironmentError if removal of installed filters failed.

New in version 0.15.

start()¶

Start this monitor.

The monitor will not receive events until this method is called. This method does nothing if called on an already started Monitor.

Note

Typically you don’t need to call this method. It is implicitly called by poll() and __iter__().

See also

started

Changed in version 0.16: This method does nothing if the Monitor was already started.

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.

poll(timeout=None)¶

Poll for a device event.

You can use this method together with iter() to synchronously monitor events in the current thread:

for device in iter(monitor.poll, None):
    print('{0.action} on {0.device_path}'.format(device))

Since this method will never return None if no timeout is specified, this is effectively an endless loop. With functools.partial() you can also create a loop that only waits for a specified time:

for device in iter(partial(monitor.poll, 3), None):
    print('{0.action} on {0.device_path}'.format(device))

This loop will only wait three seconds for a new device event. If no device event occurred after three seconds, the loop will exit.

timeout is a floating point number that specifies a time-out in seconds. If omitted or None, this method blocks until a device event is available. If 0, this method just polls and will never block.

Note

This method implicitly calls start().

Return the received Device, or None if a timeout occurred. Raise EnvironmentError if event retrieval failed.

See also

Device.action: The action that created this event.
Device.sequence_number: The sequence number of this event.

New in version 0.16.

Deprecated members

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.

Deprecated since version 0.16: Will be removed in 1.0. Use start() instead.

receive_device()¶

Receive a single device from the monitor.

Warning

You must call start() before calling this method.

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. Usual actions are:

'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)
'online': The device is online now
'offline': The device is offline now

Raise EnvironmentError, if no device could be read.

Deprecated since version 0.16: Will be removed in 1.0. Use Monitor.poll() instead.

__iter__()¶

Wait for incoming events and receive them upon arrival.

This methods implicitly calls start(), 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).

Deprecated since version 0.16: Will be removed in 1.0. Use an explicit loop over poll() instead, or monitor asynchronously with MonitorObserver.

`MonitorObserver` – asynchronous device monitoring¶

class pyudev.MonitorObserver(monitor, event_handler=None, callback=None, *args, **kwargs)¶

An asynchronous observer for device events.

This class subclasses Thread class to asynchronously observe a Monitor in a background thread:

>>> from pyudev import Context, Monitor, MonitorObserver
>>> context = Context()
>>> monitor = Monitor.from_netlink(context)
>>> monitor.filter_by(subsystem='input')
>>> def print_device_event(device):
...     print('background event {0.action}: {0.device_path}'.format(device))
>>> observer = MonitorObserver(monitor, callback=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().

See also

Device.action: The action that created this event.
Device.sequence_number: The sequence number of this event.

New in version 0.14.

Changed in version 0.15: Monitor.start() is implicitly called when the thread is started.

monitor¶: Get the Monitor observer by this object.

__init__(monitor, event_handler=None, callback=None, *args, **kwargs)¶

Create a new observer for the given monitor.

monitor is the Monitor to observe. callback is the callable to invoke on events, with the signature callback(device) where device is the Device that caused the event.

Warning

callback is invoked in the observer thread, hence the observer is blocked while callback executes.

args and kwargs are passed unchanged to the constructor of Thread.

Deprecated since version 0.16: The event_handler argument will be removed in 1.0. Use the callback argument instead.

Changed in version 0.16: Add callback argument.

send_stop()¶

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

Synchronously stop the background thread.

Note

This method can safely be called from the observer thread. In this case it is equivalent to send_stop().

Send a stop signal to the backgroud (see send_stop()), and waits for the background thread to exit (see join()) if the current thread is not the observer thread.

After this method returns in a thread that is not the observer thread, the callback is guaranteed to not be invoked again anymore.

Note

The underlying monitor is not stopped.

Changed in version 0.16: This method can be called from the observer thread.

`pyudev` - libudev binding¶

Version information¶

`Context` – UDev database context¶

`Enumerator` – device enumeration and filtering¶

`Devices` – constructing Device objects¶

`Device` – accessing device information¶

`Device` exceptions¶

`Monitor` – device monitoring¶

`MonitorObserver` – asynchronous device monitoring¶

Install

Links

Support

Table of Contents

Previous topic

Next topic

This Page

pyudev - libudev binding¶

Version information¶

Context – UDev database context¶

Enumerator – device enumeration and filtering¶

Devices – constructing Device objects¶

Device – accessing device information¶

Device exceptions¶

Monitor – device monitoring¶

MonitorObserver – asynchronous device monitoring¶

`pyudev` - libudev binding¶

`Context` – UDev database context¶

`Enumerator` – device enumeration and filtering¶

`Devices` – constructing Device objects¶

`Device` – accessing device information¶

`Device` exceptions¶

`Monitor` – device monitoring¶

`MonitorObserver` – asynchronous device monitoring¶