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.
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.
Asyncio:
Calls need to be
await
ed.Multiple requests at the same time.
Serve object on D-Bus for other programs.
D-Bus Signals.
D-Bus types conversion
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 |
|
|
Byte |
y |
|
Unsigned 8-bit integer. Note: array of bytes (ay) has different type in python domain. |
Int16 |
n |
|
Signed 16-bit integer. |
Uint16 |
q |
|
Unsigned 16-bit integer. |
Int32 |
i |
|
Signed 32-bit integer. |
Uint32 |
u |
|
Unsigned 32-bit integer. |
Int64 |
x |
|
Signed 64-bit integer. |
Uint64 |
t |
|
Unsigned 64-bit integer. |
Double |
d |
|
Float point number |
Unix FD |
h |
|
File descriptor |
String |
s |
|
String |
Object Path |
o |
|
Syntactically correct D-Bus object path |
Signature |
g |
|
D-Bus type signature |
Array |
a |
|
List of some single type. Example: |
Byte Array |
ay |
|
Array of bytes. Not a unique type in D-Bus but a different type in
Python. Accepts both |
Struct |
() |
|
Tuple. Example: |
Dictionary |
a{} |
|
Dictionary with key type and value type. Note: Dictionary is always a part of array.
I.E. |
Variant |
v |
|
Unknown type that can be any single type. In Python represented by a tuple of a signature string and a single type. Example: |
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.