def from_name(cls, 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 = Device.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 == Device.from_path(context, '/block/sda')
``context`` is the :class:`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 :class:`Device` object for the device. Raise
:exc:`DeviceNotFoundByNameError`, if no device was found with the given
name.
.. versionadded:: 0.5
"""
device = libudev.udev_device_new_from_subsystem_sysname(
context, ensure_byte_string(subsystem),
ensure_byte_string(sys_name))
if not device:
raise DeviceNotFoundByNameError(subsystem, sys_name)
return cls(context, device)
def from_name(cls, 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 = Device.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 == Device.from_path(context, '/block/sda')
``context`` is the :class:`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 :class:`Device` object for the device. Raise
:exc:`DeviceNotFoundByNameError`, if no device was found with the given
name.
.. versionadded:: 0.5
"""
device = libudev.udev_device_new_from_subsystem_sysname(
context, ensure_byte_string(subsystem),
ensure_byte_string(sys_name))
if not device:
raise DeviceNotFoundByNameError(subsystem, sys_name)
return cls(context, device)
def find_parent(self, 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 :class:`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.
.. versionadded:: 0.9
"""
subsystem = ensure_byte_string(subsystem)
if device_type is not None:
device_type = ensure_byte_string(device_type)
parent = libudev.udev_device_get_parent_with_subsystem_devtype(
self, subsystem, device_type)
if not parent:
return None
# parent device is not referenced, thus forcibly acquire a reference
return Device(self.context, libudev.udev_device_ref(parent))
def find_parent(self, 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 :class:`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.
.. versionadded:: 0.9
"""
subsystem = ensure_byte_string(subsystem)
if device_type is not None:
device_type = ensure_byte_string(device_type)
parent = libudev.udev_device_get_parent_with_subsystem_devtype(
self, subsystem, device_type)
if not parent:
return None
# parent device is not referenced, thus forcibly acquire a reference
return Device(self.context, libudev.udev_device_ref(parent))
def filter_by(self, 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.
.. versionchanged:: 0.15
This method can also be after :meth:`start()` now.
"""
subsystem = ensure_byte_string(subsystem)
if device_type:
device_type = ensure_byte_string(device_type)
libudev.udev_monitor_filter_add_match_subsystem_devtype(
self, subsystem, device_type)
libudev.udev_monitor_filter_update(self)
def filter_by(self, 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.
.. versionchanged:: 0.15
This method can also be after :meth:`start()` now.
"""
subsystem = ensure_byte_string(subsystem)
if device_type:
device_type = ensure_byte_string(device_type)
libudev.udev_monitor_filter_add_match_subsystem_devtype(
self, subsystem, device_type)
libudev.udev_monitor_filter_update(self)
def from_netlink(cls, context, source='udev'):
"""
Create a monitor by connecting to the kernel daemon through netlink.
``context`` is the :class:`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 :class:`Monitor` object, which is connected to the
given source. Raise :exc:`~exceptions.ValueError`, if an invalid
source has been specified. Raise
:exc:`~exceptions.EnvironmentError`, if the creation of the monitor
failed.
"""
if source not in ('kernel', 'udev'):
raise ValueError('Invalid source: {0!r}. Must be one of "udev" '
'or "kernel"'.format(source))
monitor = libudev.udev_monitor_new_from_netlink(
context, ensure_byte_string(source))
if not monitor:
raise EnvironmentError('Could not create udev monitor')
return cls(context, monitor)
def from_sys_path(cls, context, sys_path):
"""
Create a new device from a given ``sys_path``:
>>> from pyudev import Context, Device
>>> context = Context()
>>> Device.from_path(context, '/sys/devices/platform')
Device(u'/sys/devices/platform')
``context`` is the :class:`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 :class:`Device` object for the device. Raise
:exc:`DeviceNotFoundAtPathError`, if no device was found for
``sys_path``.
.. versionchanged:: 0.4
Raise :exc:`NoSuchDeviceError` instead of returning ``None``, if
no device was found for ``sys_path``.
.. versionchanged:: 0.5
Raise :exc:`DeviceNotFoundAtPathError` instead of
:exc:`NoSuchDeviceError`.
"""
device = libudev.udev_device_new_from_syspath(
context, ensure_byte_string(sys_path))
if not device:
raise DeviceNotFoundAtPathError(sys_path)
return cls(context, device)
def from_netlink(cls, context, source='udev'):
"""
Create a monitor by connecting to the kernel daemon through netlink.
``context`` is the :class:`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 :class:`Monitor` object, which is connected to the
given source. Raise :exc:`~exceptions.ValueError`, if an invalid
source has been specified. Raise
:exc:`~exceptions.EnvironmentError`, if the creation of the monitor
failed.
"""
if source not in ('kernel', 'udev'):
raise ValueError('Invalid source: {0!r}. Must be one of "udev" '
'or "kernel"'.format(source))
monitor = libudev.udev_monitor_new_from_netlink(
context, ensure_byte_string(source))
if not monitor:
raise EnvironmentError('Could not create udev monitor')
return cls(context, monitor)
def match_attribute(self, 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:
- :func:`int`,
- :func:`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 = (libudev.udev_enumerate_add_match_sysattr
if not nomatch else
libudev.udev_enumerate_add_nomatch_sysattr)
match(self, ensure_byte_string(attribute),
property_value_to_bytes(value))
return self
def match_attribute(self, 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:
- :func:`int`,
- :func:`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 = (libudev.udev_enumerate_add_match_sysattr if not nomatch else
libudev.udev_enumerate_add_nomatch_sysattr)
match(self, ensure_byte_string(attribute),
property_value_to_bytes(value))
return self
def from_sys_path(cls, context, sys_path):
"""
Create a new device from a given ``sys_path``:
>>> from pyudev import Context, Device
>>> context = Context()
>>> Device.from_path(context, '/sys/devices/platform')
Device(u'/sys/devices/platform')
``context`` is the :class:`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 :class:`Device` object for the device. Raise
:exc:`DeviceNotFoundAtPathError`, if no device was found for
``sys_path``.
.. versionchanged:: 0.4
Raise :exc:`NoSuchDeviceError` instead of returning ``None``, if
no device was found for ``sys_path``.
.. versionchanged:: 0.5
Raise :exc:`DeviceNotFoundAtPathError` instead of
:exc:`NoSuchDeviceError`.
"""
device = libudev.udev_device_new_from_syspath(
context, ensure_byte_string(sys_path))
if not device:
raise DeviceNotFoundAtPathError(sys_path)
return cls(context, device)
def match_sys_name(self, 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.
.. versionadded:: 0.8
"""
libudev.udev_enumerate_add_match_sysname(
self, ensure_byte_string(sys_name))
return self
def match_sys_name(self, 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.
.. versionadded:: 0.8
"""
libudev.udev_enumerate_add_match_sysname(self,
ensure_byte_string(sys_name))
return self
def match_tag(self, 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.
.. udevversion:: 154
.. versionadded:: 0.6
"""
libudev.udev_enumerate_add_match_tag(self, ensure_byte_string(tag))
return self
def match_tag(self, 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.
.. udevversion:: 154
.. versionadded:: 0.6
"""
libudev.udev_enumerate_add_match_tag(self, ensure_byte_string(tag))
return self
def match_subsystem(self, 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``.
Return the instance again.
"""
match = (libudev.udev_enumerate_add_match_subsystem if not nomatch else
libudev.udev_enumerate_add_nomatch_subsystem)
match(self, ensure_byte_string(subsystem))
return self
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 match_subsystem(self, 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``.
Return the instance again.
"""
match = (libudev.udev_enumerate_add_match_subsystem
if not nomatch else
libudev.udev_enumerate_add_nomatch_subsystem)
match(self, ensure_byte_string(subsystem))
return self
def __getitem__(self, attribute):
"""
Get the given system ``attribute`` for the device.
``attribute`` is a unicode or byte string containing the name of the
system attribute.
Return the attribute value as byte string, or raise a
:exc:`~exceptions.KeyError`, if the given attribute is not defined
for this device.
"""
value = libudev.udev_device_get_sysattr_value(
self.device, ensure_byte_string(attribute))
if value is None:
raise KeyError(attribute)
return value
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 __getitem__(self, attribute):
"""
Get the given system ``attribute`` for the device.
``attribute`` is a unicode or byte string containing the name of the
system attribute.
Return the attribute value as byte string, or raise a
:exc:`~exceptions.KeyError`, if the given attribute is not defined
for this device.
"""
value = libudev.udev_device_get_sysattr_value(
self.device, ensure_byte_string(attribute))
if value is None:
raise KeyError(attribute)
return value
def from_device_number(cls, context, type, 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 = Device.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 :func:`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 :class:`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 :class:`Device` object for the device with the given device
``number``. Raise :exc:`DeviceNotFoundByNumberError`, if no device was
found with the given device type and number. Raise
:exc:`~exceptions.ValueError`, if ``type`` is any other string than
``'char'`` or ``'block'``.
.. versionadded:: 0.11
"""
if type not in ('char', 'block'):
raise ValueError('Invalid type: {0!r}. Must be one of "char" '
'or "block".'.format(type))
device = libudev.udev_device_new_from_devnum(
context, ensure_byte_string(type[0]), number)
if not device:
raise DeviceNotFoundByNumberError(type, number)
return cls(context, device)
def from_device_number(cls, context, type, 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 = Device.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 :func:`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 :class:`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 :class:`Device` object for the device with the given device
``number``. Raise :exc:`DeviceNotFoundByNumberError`, if no device was
found with the given device type and number. Raise
:exc:`~exceptions.ValueError`, if ``type`` is any other string than
``'char'`` or ``'block'``.
.. versionadded:: 0.11
"""
if type not in ('char', 'block'):
raise ValueError('Invalid type: {0!r}. Must be one of "char" '
'or "block".'.format(type))
device = libudev.udev_device_new_from_devnum(
context, ensure_byte_string(type[0]), number)
if not device:
raise DeviceNotFoundByNumberError(type, number)
return cls(context, device)
def match_property(self, property, value):
"""
Include all devices, whose ``property`` has the given ``value``.
``property`` 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:
- :func:`int`
- :func:`bool`
- A byte string
- Anything convertable to a unicode string (including a unicode string
itself)
Return the instance again.
"""
libudev.udev_enumerate_add_match_property(
self, ensure_byte_string(property), property_value_to_bytes(value))
return self
def match_property(self, property, value):
"""
Include all devices, whose ``property`` has the given ``value``.
``property`` 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:
- :func:`int`
- :func:`bool`
- A byte string
- Anything convertable to a unicode string (including a unicode string
itself)
Return the instance again.
"""
libudev.udev_enumerate_add_match_property(
self, ensure_byte_string(property), property_value_to_bytes(value))
return self
def filter_by_tag(self, 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 :meth:`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``.
.. udevversion:: 154
.. versionadded:: 0.9
.. versionchanged:: 0.15
This method can also be after :meth:`start()` now.
"""
libudev.udev_monitor_filter_add_match_tag(
self, ensure_byte_string(tag))
libudev.udev_monitor_filter_update(self)
def filter_by_tag(self, 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 :meth:`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``.
.. udevversion:: 154
.. versionadded:: 0.9
.. versionchanged:: 0.15
This method can also be after :meth:`start()` now.
"""
libudev.udev_monitor_filter_add_match_tag(self,
ensure_byte_string(tag))
libudev.udev_monitor_filter_update(self)
def __contains__(self, attribute):
value = libudev.udev_device_get_sysattr_value(
self.device, ensure_byte_string(attribute))
return value is not None
def _has_tag(self, tag):
return bool(libudev.udev_device_has_tag(
self.device, ensure_byte_string(tag)))
def _has_tag(self, tag):
return bool(
libudev.udev_device_has_tag(self.device,
ensure_byte_string(tag)))
def __contains__(self, attribute):
value = libudev.udev_device_get_sysattr_value(
self.device, ensure_byte_string(attribute))
return value is not None
