Registry / http-networking / dbus-next

dbus-next

JSON →
library0.2.3pypypi✓ verified 89d ago

dbus-next is a pure Python 3 library for the D-Bus message bus system, designed for interprocess communication in Linux desktop and mobile environments. It boasts zero dependencies and offers first-class asyncio support, along with an optional GLib main loop backend. It's a modern alternative to older D-Bus bindings, providing high-level client and service interfaces, and is currently at version 0.2.3 with an active development and release cadence.

pip install dbus-next
INSTALL
IMPORT
SIG · DBUS-NEXT
D
dbus-next
http-networkingpythonv0.2.3
Install
1.6s avg
Import
306ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.2.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.324s · 18.3MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.288s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MessageBus
✓ from dbus_next.aio import MessageBus
For asyncio-based applications, the most common entry point.
Variant
✓ from dbus_next import Variant
Required when working with DBus 'variant' types.
ServiceInterface
✓ from dbus_next.service import (ServiceInterface, method, dbus_property, signal)
For creating and exporting D-Bus services.
MessageBus (legacy)
✓ from dbus_next.aio import MessageBus
✗ from dbus_next import MessageBus
In older versions (pre 0.1.1), `MessageBus` was directly available, but now it's typically imported from `dbus_next.aio` or `dbus_next.glib` depending on the desired backend.

This quickstart demonstrates connecting to the D-Bus session bus and interacting with a media player using the MPRIS (Media Player Remote Interfacing Specification) interface. It showcases how to connect to the bus, introspect an object, obtain a proxy interface, call a method, and read a property.

import asyncio import os from dbus_next.aio import MessageBus async def main(): bus = await MessageBus().connect() # Connect to the session bus # Example: Introspect and interact with a media player (MPRIS) # Replace 'org.mpris.MediaPlayer2.vlc' with your player's bus name if different player_bus_name = os.environ.get('DBUS_PLAYER_NAME', 'org.mpris.MediaPlayer2.vlc') player_object_path = os.environ.get('DBUS_PLAYER_PATH', '/org/mpris/MediaPlayer2') try: introspection = await bus.introspect(player_bus_name, player_object_path) obj = bus.get_proxy_object(player_bus_name, player_object_path, introspection) player_interface = obj.get_interface('org.mpris.MediaPlayer2.Player') # Call a method (e.g., Play) print(f"Calling Play on {player_bus_name}...") await player_interface.call_play() print("Play called.") # Get a property (e.g., PlaybackStatus) status = await player_interface.get_playback_status() print(f"Current playback status: {status}") except Exception as e: print(f"Could not interact with media player (is one running?): {e}") finally: bus.disconnect() if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingThe convenience constructors `MessageBus.session_bus()` and `MessageBus.system_bus()` were removed in version 0.1.1.
fix
Instead of `MessageBus.session_bus()` or `MessageBus.system_bus()`, use `await MessageBus().connect()` for the session bus or `await MessageBus(bus_type=BusType.SYSTEM).connect()` for the system bus.
affects: >=0.1.1
gotchaWhen defining service methods, properties, or signals, all parameters and return values must be explicitly annotated with D-Bus type signature strings.
fix
Ensure all method arguments and return types in `ServiceInterface` subclasses are annotated with D-Bus type signatures (e.g., `def my_method(self, value: 's') -> 'b':`). This is crucial for correct type marshalling.
affects: All versions
gotchaThe `MessageBus().connect()` call is an awaitable coroutine and must be `await`ed.
fix
Always use `bus = await MessageBus().connect()` rather than `bus = MessageBus().connect()`. Forgetting `await` will result in a `TypeError` if you try to use the returned coroutine object directly.
affects: All versions
gotchaHandling Unix file descriptors (type 'h') requires explicit configuration and manual management.
fix
To send or receive Unix file descriptors, you must set `negotiate_unix_fd=True` in the `MessageBus` constructor (e.g., `MessageBus(negotiate_unix_fd=True)`). You are responsible for closing any received file descriptors.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'MessageBus' object has no attribute 'session_bus'
Attempting to use deprecated convenience constructors for the message bus after version 0.1.1.
fix
Replace `MessageBus.session_bus()` or `MessageBus.system_bus()` with `await MessageBus().connect()` or `await MessageBus(bus_type=BusType.SYSTEM).connect()` respectively.
ValueError: method parameters must specify the dbus type string as an annotation
A method, property getter/setter, or signal in a `ServiceInterface` subclass has not been annotated with a D-Bus type signature string.
fix
Add appropriate D-Bus type signature string annotations to all parameters and return values of service interface methods. Example: `def my_method(self, name: 's') -> 's':`.
TypeError: object 'coroutine' can't be used in 'await' expression
Attempting to use the result of an awaitable function (like `MessageBus().connect()`) without actually `await`ing it.
fix
Ensure that `MessageBus().connect()` is called with the `await` keyword: `bus = await MessageBus().connect()`.
dbus_next.errors.InterfaceNotFoundError: Cannot get interface 'org.mpris.MediaPlayer2.Player' on object at path '/org/mpris/MediaPlayer2'
The D-Bus service or interface you are trying to connect to is not running, not exporting the specified interface, or the bus name/object path is incorrect.
fix
Verify that the D-Bus service you intend to interact with is running and correctly exporting the expected interface at the specified object path. Use `qdbusviewer` or `busctl` to inspect available services and interfaces on your system.
Upgrade
Version history
0.2.3latest on PyPI · released Jul 25, 2021
Audit
Dependencies
PythonrequiredRequires Python 3.6 or higher. The library is pure Python with zero external dependencies.
Agent activity
17 hits · last 30 days
node
16
OpenAI (training)
1
Resources
dbus-next — pip install dbus-next · libregistry