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.

The request_default_bus_name_async and request_default_bus_name can be used to acquire a service name on the default bus.

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

The set_default_bus can be used to set the new thread-local bus. This should be done before any objects that take bus as an init argument are created. If no bus has been set the new bus will be initialized and set as thread-local default.

The bus can also be set as default for the current context using set_context_default_bus. The context refers to the standard library’s contextvars module context variables frequently used in asyncio frameworks. Context-local default bus has higher priority over thread-local default bus.

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