dbus-next

0.2.3 · active · verified Thu Apr 16

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.

Common errors

```
AttributeError: 'MessageBus' object has no attribute 'session_bus'
```
cause 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
```
cause 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
```
cause 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'
```
cause 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.

Warnings

breaking The 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.
gotcha When 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.
gotcha The `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.
gotcha Handling 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.

Install

pip install dbus-next Install stable release

Imports

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)
wrong:
```
from dbus_next import MessageBus
```
correct:
```
from dbus_next.aio 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.

Quickstart

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())

view raw JSON →