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._StrBase

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._IntBase

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._IntBase

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._IntBase

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._IntBase

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._IntBase

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: long[, 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: long[, 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: long[, 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: unicode

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
class dbus.types.UTF8String(value: bytes or unicode[, variant_level: int=0])

Bases: _dbus_bindings._StrBase

A string represented using UTF-8 - a subtype of bytes. This type is only available in Python 2.

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

By default, when byte arrays are converted from D-Bus to Python, they come out as a dbus.String, which is a subtype of unicode. If you prefer to get UTF-8 strings (as instances of this class) or you want to avoid the conversion overhead of going from UTF-8 to Python’s internal Unicode representation, you can pass the utf8_strings=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

If value is a bytes object it must be valid UTF-8.

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 string, this is represented in Python by a String or UTF8String with variant_level==2.

Since:0.80 (in older versions, use dbus.String)