dbus.types module — dbus-python 1.2.8 documentation

# dbus.types module

class `dbus.types.` `ObjectPath`(path: str[, variant_level: int=0])

  Bases: `_dbus_bindings._StrBase`

  A D-Bus object path, such as `/com/example/MyApp/Documents/abc`.

  ObjectPath is a subtype of `str`, and object-paths behave like strings.

  path must be an ASCII string following the syntax of object paths. variant_level must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an object path, this is represented in Python by an ObjectPath with variant_level==2.

class `dbus.types.` `ByteArray`(str)

  Bases: `_dbus_bindings._BytesBase`

  ByteArray is a subtype of `bytes` (an alias for `str` in Python 2 but a distinct type in Python 3) which can be used when you want an efficient immutable representation of a D-Bus byte array (signature `ay`).

  By default, when byte arrays are converted from D-Bus to Python, they come out as a dbus.Array of dbus.Byte. This is just for symmetry with the other D-Bus types - in practice, what you usually want is the byte array represented as a string, using this class. To get this, pass the `byte_arrays=True` keyword argument to any of these methods:

  - any D-Bus method proxy, or `connect_to_signal`, on the objects returned by Bus.get_object
  - any D-Bus method on a dbus.Interface
  - dbus.Interface.connect_to_signal
  - Bus.add_signal_receiver

  Import via:

      from dbus import ByteArray

  Constructor:

      ByteArray(str)

class `dbus.types.` `Signature`(value: str or unicode[, variant_level: int])

  Bases: `_dbus_bindings._StrBase`

  A string subclass whose values are restricted to valid D-Bus signatures. When iterated over, instead of individual characters it produces Signature instances representing single complete types.

  `value` must be a valid D-Bus signature (zero or more single complete types).

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a signature, this is represented in Python by a Signature with variant_level==2.

class `dbus.types.` `Byte`(integer or bytes of length 1[, variant_level])

  Bases: `_dbus_bindings._LongBase`

  An unsigned byte: a subtype of int, with range restricted to [0, 255].

  A Byte b may be converted to a `str` of length 1 via `str(b) == chr(b)` (Python 2) or to a `bytes` of length 1 via `bytes([b])` (Python 3).

  Most of the time you don’t want to use this class - it mainly exists for symmetry with the other D-Bus types. See dbus.ByteArray for a better way to handle arrays of Byte.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a byte, this is represented in Python by a Byte with variant_level==2.

class `dbus.types.` `Boolean`(value: bool[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  A boolean, represented as a subtype of `int` (not `bool`, because `bool` cannot be subclassed).

  `value` is converted to 0 or 1 as if by `int(bool(value))`.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a boolean, this is represented in Python by a Boolean with variant_level==2.

class `dbus.types.` `Int16`(value: int[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  A signed 16-bit integer between -0x8000 and +0x7FFF, represented as a subtype of int.

  value must be within the allowed range, or OverflowError will be raised.

  > variant_level must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an int16, this is represented in Python by an Int16 with variant_level==2.

class `dbus.types.` `UInt16`(value: int[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  An unsigned 16-bit integer between 0 and 0xFFFF, represented as a subtype of `int`.

  `value` must be within the allowed range, or OverflowError will be raised.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a uint16, this is represented in Python by a UInt16 with variant_level==2.

class `dbus.types.` `Int32`(value: int[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  A signed 32-bit integer between -0x8000 0000 and +0x7FFF FFFF, represented as a subtype of `int`.

  `value` must be within the allowed range, or OverflowError will be raised.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an int32, this is represented in Python by an Int32 with variant_level==2.

class `dbus.types.` `UInt32`(value: int[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  An unsigned 32-bit integer between 0 and 0xFFFF FFFF, represented as a subtype of `long` in Python 2 or `int` in Python 3.

  `value` must be within the allowed range, or OverflowError will be raised.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a uint32, this is represented in Python by a UInt32 with variant_level==2.

class `dbus.types.` `Int64`(value: int[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  A signed 64-bit integer between -0x8000 0000 0000 0000 and +0x7FFF FFFF FFFF FFFF, represented as a subtype of `long` in Python 2 or `int` in Python 3.

  Note that this may be changed in future to be a subtype of int on 64-bit platforms; applications should not rely on either behaviour.

  `value` must be within the allowed range, or OverflowError will be raised.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an int64, this is represented in Python by an Int64 with variant_level==2.

class `dbus.types.` `UInt64`(value: int[, variant_level: int])

  Bases: `_dbus_bindings._LongBase`

  An unsigned 64-bit integer between 0 and 0xFFFF FFFF FFFF FFFF, subtype of `long` in Python 2 or `int` in Python 3.

  `value` must be within the allowed range, or OverflowError will be raised.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a uint64, this is represented in Python by a UInt64 with variant_level==2.

class `dbus.types.` `Double`

  Bases: `_dbus_bindings._FloatBase`

  A double-precision floating point number (a subtype of float).

class `dbus.types.` `String`(value: str or unicode[, variant_level: int])

  Bases: `str`

  A string represented using Unicode - a subtype of `unicode` (Python 2) or `str` (Python 3).

  All strings on D-Bus are required to be valid Unicode; in the “wire protocol” they’re transported as UTF-8.

  By default, when strings are converted from D-Bus to Python, they come out as this class. In Python 2, if you prefer to get UTF-8 strings (as instances of a subtype of str) or you want to avoid the conversion overhead of going from UTF-8 to Python’s internal Unicode representation, see the documentation for dbus.UTF8String.

  variant_level must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an array, this is represented in Python by a String or UTF8String with variant_level==2.

class `dbus.types.` `Array`([iterable][, signature][, variant_level])

  Bases: `list`

  An array of similar items, implemented as a subtype of list.

  As currently implemented, an Array behaves just like a list, but with the addition of a `signature` property set by the constructor; conversion of its items to D-Bus types is only done when it’s sent in a Message. This might change in future so validation is done earlier.

  `variant_level` must be non-negative; the default is 0.

  `signature` is the D-Bus signature string for a single element of the array, or None. If not None it must represent a single complete type, the type of a single array item; the signature of the whole Array may be obtained by prepending `a` to the given signature.

  If None (the default), when the Array is sent over D-Bus, the item signature will be guessed from the first element.

  `signature`

    The D-Bus signature of each element of this Array (a Signature instance)

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an array, this is represented in Python by an Array with variant_level==2.

class `dbus.types.` `Struct`(iterable, signature=None, variant_level=0)

  Bases: `tuple`

  An structure containing items of possibly distinct types.

  D-Bus structs may not be empty, so the iterable argument is required and may not be an empty iterable.

  `signature` is either None, or a string representing the contents of the struct as one or more complete type signatures. The overall signature of the struct will be the given signature enclosed in parentheses, `()`.

  If the signature is None (default) it will be guessed from the types of the items during construction.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a struct, this is represented in Python by a Struct with variant_level==2.

class `dbus.types.` `Dictionary`(mapping_or_iterable=(), signature=None, variant_level=0)

  Bases: `dict`

  An mapping whose keys are similar and whose values are similar, implemented as a subtype of dict.

  As currently implemented, a Dictionary behaves just like a dict, but with the addition of a `signature` property set by the constructor; conversion of its items to D-Bus types is only done when it’s sent in a Message. This may change in future so validation is done earlier.

  `variant_level` must be non-negative; the default is 0.

  `signature` is either a string or None. If a string, it must consist of exactly two complete type signatures, representing the ‘key’ type (which must be a primitive type, i.e. one of “bdginoqstuxy”) and the ‘value’ type. The signature of the whole Dictionary will be `a{xx}` where `xx` is replaced by the given signature.

  If it is None (the default), when the Dictionary is sent over D-Bus, the key and value signatures will be guessed from an arbitrary element of the Dictionary.

  `signature`

    The D-Bus signature of each key in this Dictionary, followed by that of each value in this Dictionary, as a Signature instance.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing a dictionary, this is represented in Python by a Dictionary with variant_level==2.

class `dbus.types.` `UnixFd`(value: int or file object[, variant_level: int])

  Bases: `object`

  A Unix Fd.

  `value` must be the integer value of a file descriptor, or an object that implements the fileno() method. Otherwise, ValueError will be raised.

  UnixFd keeps a dup() (duplicate) of the supplied file descriptor. The caller remains responsible for closing the original fd.

  `variant_level` must be non-negative; the default is 0.

  `variant_level`

    Indicates how many nested Variant containers this object is contained in: if a message’s wire format has a variant containing a variant containing an Unix Fd, this is represented in Python by an Unix Fd with variant_level==2.

  `take`() → int

    This method returns the file descriptor owned by UnixFd object. Note that, once this method is called, closing the file descriptor is the caller’s responsibility.

    This method may be called at most once; UnixFd ‘forgets’ the file descriptor after it is taken.

    Raises ValueError:
    | if this method has already been called