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
|
Interface code generator
========================
Python-sdbus is able to generate the interfaces code from
the D-Bus introspection XML. (either from a file or live object on D-Bus)
Currently async interfaces code is generated by default.
Blocking interfaces can be generated by passing ``--block`` option.
Running code generator requires
`Jinja <https://palletsprojects.com/projects/jinja/>`_
to be installed.
.. warning:: Do NOT send the generator result to ``exec()`` function.
Interface code MUST be inspected before running.
The generated interfaces code will be syntactically correct but NOT stylistically.
It is recommended running a code formatter on the generated code. (for example ``black``)
Generating from XML files
-------------------------
To run generator on files (such as found under ``/usr/share/dbus-1/interfaces/`` folder)
execute the ``sdbus`` module with ``gen-from-file`` first argument
and file paths to introspection XML files:
.. code-block:: shell
python -m sdbus gen-from-file /usr/share/dbus-1/interfaces/org.gnome.Shell.Screenshot.xml
The generated interface code will be printed in to stdout. You
can use shell redirection ``>`` to save it in to file.
Multiple interface files can be passed which generates a file
containing multiple interfaces.
Generating from run-time introspection
--------------------------------------
To run generator on some service on the D-Bus execute
the ``sdbus`` module with ``gen-from-connection`` first argument,
the service connection name as second and one or more object paths:
.. code-block:: shell
python -m sdbus gen-from-connection org.freedesktop.systemd1 /org/freedesktop/systemd1
The generated interface code will be printed in to stdout. You
can use shell redirection ``>`` to save it in to file.
Multiple object paths can be passed which generates a file
containing all interfaces encountered in the objects.
Pass ``--system`` option to use system bus instead of session bus.
Renaming interfaces and members
-------------------------------
*New in version 0.13.0.*
Some interface and member names might conflict with Python keywords when
converted from D-Bus introspection to Python code by gerator. The CLI interface
allow to override the particular interface and member names using the ``--select-*``
and ``--set-name`` options. The selector options move the cursor to a particular
interface and member
Available override options:
* ``--set-name``
Sets the name of currently selected element as it would
be in generated Python code. Can be used if either interface or
member is selected.
* ``--select-interface``
Selects the interface using its D-Bus name.
* ``--select-method``
Selects the method using its D-Bus name.
An interface must be selected first.
* ``--select-property``
Selects the property using its D-Bus name.
An interface must be selected first.
* ``--select-signal``
Selects the signal using its D-Bus name.
An interface must be selected first.
For example, an ``org.example.Interface`` interface has a property called ``Class``.
When automatically converted the name will become ``class`` which is a reserved Python keyword.
Using these CLI options it is possible to override the name of the property and class:
.. code-block:: shell
python -m sdbus gen-from-file \
org.example.interface.xml \
--select-interface org.example.Interface \
--set-name Example \
--select-property Class \
--set-name example_class
This will generate following Python code:
.. code-block:: python
class Example:
@dbus_property_async(
property_signature="s",
)
def example_class(self) -> str:
raise NotImplementedError
|
