def action(self):
"""
The device event action as string, or ``None``, if this device was not
received from a :class:`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!
.. versionadded:: 0.16
"""
action = libudev.udev_device_get_action(self)
if action:
return ensure_unicode_string(action)
def device_links(self):
"""
An iterator, which yields the absolute paths (including the device
directory, see :attr:`Context.device_path`) of all symbolic links
pointing to the :attr:`device_node` of this device. The paths are
unicode strings.
UDev can create symlinks to the original device node (see
:attr:`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
:meth:`Device.from_device_file()`. Hence do *not* rely on
``Device.from_device_file(context, link).device_path ==
device.device_path`` from any ``link`` in ``device.device_links``.
"""
devlinks = libudev.udev_device_get_devlinks_list_entry(self)
for name, _ in udev_list_iterate(devlinks):
yield ensure_unicode_string(name)
def sys_number(self):
"""
The trailing number of the :attr:`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 = Device.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
.. versionadded:: 0.11
"""
number = libudev.udev_device_get_sysnum(self)
if number is not None:
return ensure_unicode_string(number)
def action(self):
"""
The device event action as string, or ``None``, if this device was not
received from a :class:`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!
.. versionadded:: 0.16
"""
action = libudev.udev_device_get_action(self)
if action:
return ensure_unicode_string(action)
def 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
:data:`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
:exc:`~exceptions.EnvironmentError` and
:exc:`~subprocess.CalledProcessError` if you call this function.
Return the version number as single integer. Raise
:exc:`~exceptions.ValueError`, if the version number retrieved from udev
could not be converted to an integer. Raise
:exc:`~exceptions.EnvironmentError`, if ``udevadm`` was not found, or could
not be executed. Raise :exc:`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.
.. versionadded:: 0.8
"""
output = ensure_unicode_string(check_output(['udevadm', '--version']))
return int(output.strip())
def sys_number(self):
"""
The trailing number of the :attr:`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 = Device.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
.. versionadded:: 0.11
"""
number = libudev.udev_device_get_sysnum(self)
if number is not None:
return ensure_unicode_string(number)
def device_links(self):
"""
An iterator, which yields the absolute paths (including the device
directory, see :attr:`Context.device_path`) of all symbolic links
pointing to the :attr:`device_node` of this device. The paths are
unicode strings.
UDev can create symlinks to the original device node (see
:attr:`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
:meth:`Device.from_device_file()`. Hence do *not* rely on
``Device.from_device_file(context, link).device_path ==
device.device_path`` from any ``link`` in ``device.device_links``.
"""
devlinks = libudev.udev_device_get_devlinks_list_entry(self)
for name, _ in udev_list_iterate(devlinks):
yield ensure_unicode_string(name)
def 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
:data:`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
:exc:`~exceptions.EnvironmentError` and
:exc:`~subprocess.CalledProcessError` if you call this function.
Return the version number as single integer. Raise
:exc:`~exceptions.ValueError`, if the version number retrieved from udev
could not be converted to an integer. Raise
:exc:`~exceptions.EnvironmentError`, if ``udevadm`` was not found, or could
not be executed. Raise :exc:`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.
.. versionadded:: 0.8
"""
output = ensure_unicode_string(check_output(['udevadm', '--version']))
return int(output.strip())
def __iter__(self):
"""
Iterate over all tags.
Yield each tag as unicode string.
"""
tags = libudev.udev_device_get_tags_list_entry(self.device)
for tag, _ in udev_list_iterate(tags):
yield ensure_unicode_string(tag)
def device_path(self):
"""
The device directory path defaulting to ``/dev`` as unicode string.
"""
if hasattr(libudev, 'udev_get_dev_path'):
return ensure_unicode_string(libudev.udev_get_dev_path(self))
else:
# Fixed path since udev 183
return '/dev'
def sys_path(self):
"""
The ``sysfs`` mount point defaulting to ``/sys'`` as unicode string.
"""
if hasattr(libudev, 'udev_get_sys_path'):
return ensure_unicode_string(libudev.udev_get_sys_path(self))
else:
# Fixed path since udev 183
return '/sys'
def device_path(self):
"""
The device directory path defaulting to ``/dev`` as unicode string.
"""
if hasattr(libudev, 'udev_get_dev_path'):
return ensure_unicode_string(libudev.udev_get_dev_path(self))
else:
# Fixed path since udev 183
return '/dev'
def __iter__(self):
"""
Iterate over all tags.
Yield each tag as unicode string.
"""
tags = libudev.udev_device_get_tags_list_entry(self.device)
for tag, _ in udev_list_iterate(tags):
yield ensure_unicode_string(tag)
def sys_path(self):
"""
The ``sysfs`` mount point defaulting to ``/sys'`` as unicode string.
"""
if hasattr(libudev, 'udev_get_sys_path'):
return ensure_unicode_string(libudev.udev_get_sys_path(self))
else:
# Fixed path since udev 183
return '/sys'
def __iter__(self):
"""
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.
"""
properties = libudev.udev_device_get_properties_list_entry(self)
for name, _ in udev_list_iterate(properties):
yield ensure_unicode_string(name)
def device_path(self):
"""
Kernel device path as unicode string. This path uniquely identifies
a single device.
Unlike :attr:`sys_path`, this path does not contain the ``sysfs``
mount point. However, the path is absolute and starts with a slash
``'/'``.
"""
return ensure_unicode_string(libudev.udev_device_get_devpath(self))
def __iter__(self):
"""
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.
"""
properties = libudev.udev_device_get_properties_list_entry(self)
for name, _ in udev_list_iterate(properties):
yield ensure_unicode_string(name)
def driver(self):
"""
The driver name as unicode string, or ``None``, if there is no
driver for this device.
.. versionadded:: 0.5
"""
driver = libudev.udev_device_get_driver(self)
if driver:
return ensure_unicode_string(driver)
def device_path(self):
"""
Kernel device path as unicode string. This path uniquely identifies
a single device.
Unlike :attr:`sys_path`, this path does not contain the ``sysfs``
mount point. However, the path is absolute and starts with a slash
``'/'``.
"""
return ensure_unicode_string(libudev.udev_device_get_devpath(self))
def driver(self):
"""
The driver name as unicode string, or ``None``, if there is no
driver for this device.
.. versionadded:: 0.5
"""
driver = libudev.udev_device_get_driver(self)
if driver:
return ensure_unicode_string(driver)
def run_path(self):
"""
The run runtime directory path defaulting to ``/run`` as unicode
string.
.. udevversion:: 167
.. versionadded:: 0.10
"""
if hasattr(libudev, 'udev_get_run_path'):
return ensure_unicode_string(libudev.udev_get_run_path(self))
else:
return '/run/udev'
def run_path(self):
"""
The run runtime directory path defaulting to ``/run`` as unicode
string.
.. udevversion:: 167
.. versionadded:: 0.10
"""
if hasattr(libudev, 'udev_get_run_path'):
return ensure_unicode_string(libudev.udev_get_run_path(self))
else:
return '/run/udev'
def asstring(self, attribute):
"""
Get the given ``atribute`` for the device as unicode string.
Depending on the content of the attribute, this may or may not work.
Be prepared to catch :exc:`~exceptions.UnicodeDecodeError`.
``attribute`` is a unicode or byte string containing the name of the
attribute.
Return the attribute value as byte string. Raise a
:exc:`~exceptions.KeyError`, if the given attribute is not defined
for this device, or :exc:`~exceptions.UnicodeDecodeError`, if the
content of the attribute cannot be decoded into a unicode string.
"""
return ensure_unicode_string(self[attribute])
def __getitem__(self, property):
"""
Get the given ``property`` from this device.
``property`` is a unicode or byte string containing the name of the
property.
Return the property value as unicode string, or raise a
:exc:`~exceptions.KeyError`, if the given property is not defined
for this device.
"""
value = libudev.udev_device_get_property_value(
self, ensure_byte_string(property))
if value is None:
raise KeyError(property)
return ensure_unicode_string(unicode(value, 'utf-8'))
def asstring(self, attribute):
"""
Get the given ``atribute`` for the device as unicode string.
Depending on the content of the attribute, this may or may not work.
Be prepared to catch :exc:`~exceptions.UnicodeDecodeError`.
``attribute`` is a unicode or byte string containing the name of the
attribute.
Return the attribute value as byte string. Raise a
:exc:`~exceptions.KeyError`, if the given attribute is not defined
for this device, or :exc:`~exceptions.UnicodeDecodeError`, if the
content of the attribute cannot be decoded into a unicode string.
"""
return ensure_unicode_string(self[attribute])
def __getitem__(self, property):
"""
Get the given ``property`` from this device.
``property`` is a unicode or byte string containing the name of the
property.
Return the property value as unicode string, or raise a
:exc:`~exceptions.KeyError`, if the given property is not defined
for this device.
"""
value = libudev.udev_device_get_property_value(
self, ensure_byte_string(property))
if value is None:
raise KeyError(property)
return ensure_unicode_string(value)
def device_node(self):
"""
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 :attr:`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 :attr:`device_links` to get a list of symbolic links to this
device node.
.. warning::
For devices created with :meth:`from_device_file()`, the value of
this property is not necessary equal to the ``filename`` given to
:meth:`from_device_file()`.
"""
node = libudev.udev_device_get_devnode(self)
if node:
return ensure_unicode_string(node)
def device_type(self):
"""
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'
.. versionadded:: 0.10
"""
device_type = libudev.udev_device_get_devtype(self)
if device_type is not None:
return ensure_unicode_string(device_type)
def device_type(self):
"""
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'
.. versionadded:: 0.10
"""
device_type = libudev.udev_device_get_devtype(self)
if device_type is not None:
return ensure_unicode_string(device_type)
def device_node(self):
"""
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 :attr:`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 :attr:`device_links` to get a list of symbolic links to this
device node.
.. warning::
For devices created with :meth:`from_device_file()`, the value of
this property is not necessary equal to the ``filename`` given to
:meth:`from_device_file()`.
"""
node = libudev.udev_device_get_devnode(self)
if node:
return ensure_unicode_string(node)
def _attributes(self):
attrs = libudev.udev_device_get_sysattr_list_entry(self.device)
for attribute, _ in udev_list_iterate(attrs):
yield ensure_unicode_string(attribute)
def subsystem(self):
"""
Name of the subsystem this device is part of as unicode string.
"""
return ensure_unicode_string(libudev.udev_device_get_subsystem(self))
def sys_name(self):
"""
Device file name inside ``sysfs`` as unicode string.
"""
return ensure_unicode_string(libudev.udev_device_get_sysname(self))
def _attributes(self):
attrs = libudev.udev_device_get_sysattr_list_entry(self.device)
for attribute, _ in udev_list_iterate(attrs):
yield ensure_unicode_string(attribute)
def sys_path(self):
"""
Absolute path of this device in ``sysfs`` including the ``sysfs``
mount point as unicode string.
"""
return ensure_unicode_string(libudev.udev_device_get_syspath(self))
def sys_name(self):
"""
Device file name inside ``sysfs`` as unicode string.
"""
return ensure_unicode_string(libudev.udev_device_get_sysname(self))
def subsystem(self):
"""
Name of the subsystem this device is part of as unicode string.
"""
return ensure_unicode_string(libudev.udev_device_get_subsystem(self))
def sys_path(self):
"""
Absolute path of this device in ``sysfs`` including the ``sysfs``
mount point as unicode string.
"""
return ensure_unicode_string(libudev.udev_device_get_syspath(self))
