pyudev - libudev binding — pyudev 0.21.0 documentation

# `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.