xibus

commit

647052fe98a33e126299b9c262cc48c24ede404d

parent

7175cabd964a680ef6f8ad7d9ad941c6128c5cf0

Author

Tobias Bengfort <tobias.bengfort@posteo.de>

Date

2026-02-16 08:42

add README

Diffstat

1 files changed, 82 insertions, 0 deletions

diff --git a/README.md b/README.md

@@ -0,0 +1,82 @@
   -1     1 # xibus - pure python async D-Bus library
   -1     2 
   -1     3 This is a pure python implementation of the [D-Bus
   -1     4 Specification](https://dbus.freedesktop.org/doc/dbus-specification.html).
   -1     5 It consists of the following parts:
   -1     6 
   -1     7 -   `marshal.py` implements the low-level wire format
   -1     8 -   `message.py` builds on that to define messages
   -1     9 -   `connection.py` allows to send and receive messages over a socket as well as introducing the concepts of method calls and signals
   -1    10 -   `client.py` provides high level abstractions
   -1    11     -   properties
   -1    12     -   introspection
   -1    13     -   guessing the correct path and interface to reduce verbosity
   -1    14     -   portal-style async responses (`org.freedesktop.portal.Request`)
   -1    15 
   -1    16 ## Usage
   -1    17 
   -1    18 ```python
   -1    19 import asyncio
   -1    20 from xibus import get_client
   -1    21 
   -1    22 async def amain():
   -1    23     async with get_client('session') as c:
   -1    24         # call a method
   -1    25         print(await c.call(
   -1    26             'org.freedesktop.portal.Desktop',
   -1    27             '/org/freedesktop/portal/desktop',
   -1    28             'org.freedesktop.portal.Settings',
   -1    29             'ReadOne',
   -1    30             ('org.freedesktop.appearance', 'color-scheme'),
   -1    31             'ss',
   -1    32         ))
   -1    33 
   -1    34         # if path, interface, or signature are omitted,
   -1    35         # they will be inferred from introspection
   -1    36         print(await c.call(
   -1    37             'org.freedesktop.portal.Desktop',
   -1    38             None,
   -1    39             None,
   -1    40             'ReadOne',
   -1    41             ('org.freedesktop.appearance', 'color-scheme'),
   -1    42         ))
   -1    43 
   -1    44         # get a property
   -1    45         print(await c.get_property(
   -1    46             'org.freedesktop.portal.Desktop',
   -1    47             None,
   -1    48             'org.freedesktop.portal.Settings',
   -1    49             'version',
   -1    50         ))
   -1    51 
   -1    52         # receive signals
   -1    53         async with c.subscribe_signal(
   -1    54             'org.freedesktop.portal.Desktop',
   -1    55             None,
   -1    56             None,
   -1    57             'SettingChanged',
   -1    58         ) as queue:
   -1    59             async for signal in queue:
   -1    60                 print(signal)
   -1    61 
   -1    62         # desktop portals have a different mechanism for returning values,
   -1    63         # so there is a special way to call them
   -1    64         await c.portal_call(
   -1    65             'org.freedesktop.portal.Desktop',
   -1    66             None,
   -1    67             None,
   -1    68             'OpenURI',
   -1    69             ['', 'https://example.com', {}],
   -1    70         )
   -1    71 
   -1    72 asyncio.run(amain())
   -1    73 ```
   -1    74 
   -1    75 ## Links
   -1    76 
   -1    77 -   [dbus-next](https://github.com/altdesktop/python-dbus-next) and its forks
   -1    78     [dbus-fast](https://github.com/bluetooth-devices/dbus-fast) and
   -1    79     [asyncdbus](https://github.com/M-o-a-T/asyncdbus) also implements D-Bus in
   -1    80     python, but the code is much more complex.
   -1    81 -   [Talk on why systemd is moving from D-Bus to
   -1    82     Varlink](https://mirror.as35701.net/video.fosdem.org/2026/ub2147/NFNKEK-varlink-ipc-system-keynote.av1.webm)