A binding to libudev.
To use pyudev, simply import it:
>>> import pyudev
>>> pyudev.__version__
'0.8'
>>> pyudev.udev_version()
165
With the exception of the toolkit integration all classes and functions are available in the top-level namespace of pyudev.
To use these classes and functions, a Context object is required:
>>> context = pyudev.Context()
You can see this object as some kind of connection to the udev database, through which the contents of this database can be queried.
The Context provides access to the list of all devices through Context.list_devices():
>>> devices = context.list_devices()
You can filter the devices by specific subsystems or properties. For instance, the following code only matches all mouse devices:
>>> devices = context.list_devices(subsystem='input', ID_INPUT_MOUSE=True)
In both cases devices is an instance of Enumerator. When iterated over, this class yields Device objects, representing those devices, which match the filters. Device objects provide various attributes to access information:
>>> for device in devices:
... if device.sys_name.startswith('event'):
... device.parent['NAME']
...
u'"Logitech USB-PS/2 Optical Mouse"'
u'"Broadcom Corp"'
u'"PS/2 Mouse"'
Instead of listing devices, you can monitor the device tree for changes using the Monitor class:
>>> monitor = pyudev.Monitor.from_netlink(context)
>>> monitor.filter_by(subsystem='input')
>>> for action, device in monitor:
... if action == 'add':
... print('{0!r} added'.format(device))
If you are interested in a specific device, whose name or whose path is known to you, you can construct a Device object directly, either with from a device path:
>>> platform_device = pyudev.Device.from_path(
... context, '/sys/devices/platform')
>>> platform_device
Device(u'/sys/devices/platform')
>>> platform_device.sys_name
u'platform'
Or from a subsystem and a device name:
>>> sda = pyudev.Device.from_name(context, 'block', 'sda')
>>> sda.subsystem
u'block'
>>> sda.sys_name
u'sda'
In either case, you get Device objects, which are really the central objects in pyudev, because they give access to everything you ever wanted to know about devices.
The Device class implements the Mapping ABC, and thus behaves like a read-only dictionary. It maps the names of general UDev properties to the corresponding values. You can use all the well-known dictionary methods to access device information.
Aside of dictionary access, some special properties are available, that provide access to udev properties and attributes of the device (like its path in sysfs, which is available through Device.device_path).
One important property is Device.attributes, which gives you a dictionary containing the system attributes of the device. A system attribute is basically just a file inside the device directory. These attributes contain device-specific information about the device (in contrast to the general UDev properties).
pyudev provides classes, which integrate monitoring into the event loop of GUI toolkits. Currently, PyQt4, PySide and pygobject are supported.
pyudev tries to provide all features of recent udev versions, while maintaining compatibility with older versions. This means, that some attributes of pyudev classes are not available, if udev is too old. Whenever this is the case, the minimum version of udev required to use the attribute is described in the documentation, see for instance Device.is_initialized. If no specific version is mentioned, the attribute is available from udev 151 onwards, which is the oldest udev version supported by pyudev. udev 150 and earlier may work with pyudev, but are not tested and consequently not officially supported.
You can use udev_version() to check the version of udev and see, if it is recent enough for your needs:
>>> if pyudev.udev_version() < 165:
... print('udev is somewhat older here')
... else:
... print('udev is quite up to date here')
...
udev is quite up to date here
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.
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.
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 utilitiy, 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.