General Information

Blocking vs Async

Python-sdbus supports both blocking and async IO.

Regular python functions are always blocking.

Asyncio is a part of python standard library that allows non-blocking io.

Asyncio documentation

Generally blocking IO should only be used for simple scripts and programs that interact with existing D-Bus objects.

Blocking:

  • Blocking is easier to initiate (no event loop)

  • Properties behave exactly as Python properties do. (i.e. can assign with ‘=’ operator)

  • Only allows one request at a time.

  • No D-Bus signals.

  • Cannot serve objects, only interact with existing object on D-Bus.

Blocking quick start

Blocking API

Asyncio:

  • Calls need to be await ed.

  • Multiple requests at the same time.

  • Serve object on D-Bus for other programs.

  • D-Bus Signals.

Asyncio quick start

Asyncio API

D-Bus types conversion

D-Bus types reference

Note

Python integers are unlimited size but D-Bus integers are not. All integer types raise OverflowError if you try to pass number outside the type size.

Unsigned integers range is 0 < (2**bit_size)-1.

Signed integers range is -(2**(bit_size-1)) < (2**(bit_size-1))-1.

Name

D-Bus type

Python type

Description

Boolean

b

bool

True or False

Byte

y

int

Unsigned 8-bit integer. Note: array of bytes (ay) has different type in python domain.

Int16

n

int

Signed 16-bit integer.

Uint16

q

int

Unsigned 16-bit integer.

Int32

i

int

Signed 32-bit integer.

Uint32

u

int

Unsigned 32-bit integer.

Int64

x

int

Signed 64-bit integer.

Uint64

t

int

Unsigned 64-bit integer.

Double

d

float

Float point number

Unix FD

h

int

File descriptor

String

s

str

String

Object Path

o

str

Syntactically correct D-Bus object path

Signature

g

str

D-Bus type signature

Array

a

list

List of some single type.

Example: as array of strings

Byte Array

ay

bytes

Array of bytes. Not a unique type in D-Bus but a different type in Python. Accepts both bytes and bytearray. Used for binary data.

Struct

()

tuple

Tuple.

Example: (isax) tuple of int, string and array of int.

Dictionary

a{}

dict

Dictionary with key type and value type.

Note: Dictionary is always a part of array. I.E. a{si} is the dict with string keys and integer values. {si} is NOT a valid signature.

Variant

v

tuple

Unknown type that can be any single type. In Python represented by a tuple of a signature string and a single type.

Example: ("s", "test") variant of a single string

Name conversions

D-Bus uses CamelCase for method names.

Python uses snake_case.

When decorating a method name will be automatically translated from snake_case to CamelCase. Example: close_notification -> CloseNotification

However, all decorators have a parameter to force D-Bus name to a specific value. See API documentation for a particular decorator.

Default bus

Most object methods that take a bus as a parameter will use a thread-local default bus connection if a bus object is not explicitly passed.

Session bus is default bus when running as a user and system bus otherwise.

request_default_bus_name_async() can be used to acquire a service name on default bus.

Use sd_bus_open_user() and sd_bus_open_system() to acquire a specific bus connection.

Set the default connection to a new default with set_default_bus(). This should be done before any object that take bus as an init argument are created.

In the future there will be a better way to create and acquire new bus connections.

Glossary

  • Bus object representing connection to D-Bus.

  • Proxy Python object that represents an object on D-Bus.

    Without proxy you manipulate messages directly.

  • Remote something that exists outside current Python process.

  • Local something that exists inside current Python scope.

  • Service Name a well known name that an process can acquire on D-Bus.

    For example, systemd acquires org.freedesktop.systemd1 name.

  • Signature D-Bus type definition. Represented by a string. See D-Bus types conversion.

Contents