1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
General Information
===================
.. py:currentmodule:: sdbus
.. _blocking-vs-async:
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 <https://docs.python.org/3/library/asyncio.html>`_
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.
:doc:`/sync_quick`
:doc:`/sync_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.
:doc:`/asyncio_quick`
:doc:`/asyncio_api`
.. _dbus-types:
D-Bus types conversion
++++++++++++++++++++++++
`D-Bus types reference <https://dbus.freedesktop.org/doc/dbus-specification.html#type-system>`_
.. note:: Python integers are unlimited size but D-Bus integers are not.
All integer types raise :py:exc:`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 | :py:obj:`bool` | :py:obj:`True` or :py:obj:`False` |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Byte | y | :py:obj:`int` | Unsigned 8-bit integer. |
| | | | **Note:** array of bytes (*ay*) has different type |
| | | | in python domain. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Int16 | n | :py:obj:`int` | Signed 16-bit integer. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Uint16 | q | :py:obj:`int` | Unsigned 16-bit integer. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Int32 | i | :py:obj:`int` | Signed 32-bit integer. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Uint32 | u | :py:obj:`int` | Unsigned 32-bit integer. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Int64 | x | :py:obj:`int` | Signed 64-bit integer. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Uint64 | t | :py:obj:`int` | Unsigned 64-bit integer. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Double | d | :py:obj:`float` | Float point number |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Unix FD | h | :py:obj:`int` | File descriptor |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| String | s | :py:obj:`str` | String |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Object | o | :py:obj:`str` | Syntactically correct D-Bus object path |
| Path | | | |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Signature | g | :py:obj:`str` | D-Bus type signature |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Array | a | :py:obj:`list` | List of some single type. |
| | | | |
| | | | Example: ``as`` array of strings |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Byte Array | ay | :py:obj:`bytes` | Array of bytes. Not a unique type in D-Bus but a different type in |
| | | | Python. Accepts both :py:obj:`bytes` and :py:obj:`bytearray`. |
| | | | Used for binary data. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Struct | () | :py:obj:`tuple` | Tuple. |
| | | | |
| | | | Example: ``(isax)`` tuple of int, string and array of int. |
+-------------+------------+-----------------+--------------------------------------------------------------------+
| Dictionary | a{} | :py:obj:`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 | :py:obj:`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 :py:func:`request_default_bus_name_async <sdbus.default_bus.request_default_bus_name_async>`
and :py:func:`request_default_bus_name <sdbus.default_bus.request_default_bus_name>`
can be used to acquire a service name on the default bus.
Use :py:func:`sd_bus_open_user` and :py:func:`sd_bus_open_system` to
acquire a specific bus connection.
The :py:func:`set_default_bus <sdbus.default_bus.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
:py:func:`set_context_default_bus <sdbus.default_bus.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 :ref:`dbus-types`.
Contents
++++++++++++++++++++
* :ref:`genindex`
* :doc:`/api_index`
* :ref:`search`
|
