{"id":7148,"library":"dbus-next","title":"dbus-next","description":"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.","status":"active","version":"0.2.3","language":"en","source_language":"en","source_url":"https://github.com/altdesktop/python-dbus-next","tags":["dbus","asyncio","ipc","linux-desktop","interprocess-communication"],"install":[{"cmd":"pip install dbus-next","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.6 or higher. The library is pure Python with zero external dependencies.","package":"Python","optional":false}],"imports":[{"note":"For asyncio-based applications, the most common entry point.","symbol":"MessageBus","correct":"from dbus_next.aio import MessageBus"},{"note":"Required when working with DBus 'variant' types.","symbol":"Variant","correct":"from dbus_next import Variant"},{"note":"For creating and exporting D-Bus services.","symbol":"ServiceInterface","correct":"from dbus_next.service import (ServiceInterface, method, dbus_property, signal)"},{"note":"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.","wrong":"from dbus_next import MessageBus","symbol":"MessageBus (legacy)","correct":"from dbus_next.aio import MessageBus"}],"quickstart":{"code":"import asyncio\nimport os\nfrom dbus_next.aio import MessageBus\n\nasync def main():\n    bus = await MessageBus().connect() # Connect to the session bus\n    \n    # Example: Introspect and interact with a media player (MPRIS)\n    # Replace 'org.mpris.MediaPlayer2.vlc' with your player's bus name if different\n    player_bus_name = os.environ.get('DBUS_PLAYER_NAME', 'org.mpris.MediaPlayer2.vlc')\n    player_object_path = os.environ.get('DBUS_PLAYER_PATH', '/org/mpris/MediaPlayer2')\n\n    try:\n        introspection = await bus.introspect(player_bus_name, player_object_path)\n        obj = bus.get_proxy_object(player_bus_name, player_object_path, introspection)\n        player_interface = obj.get_interface('org.mpris.MediaPlayer2.Player')\n\n        # Call a method (e.g., Play)\n        print(f\"Calling Play on {player_bus_name}...\")\n        await player_interface.call_play()\n        print(\"Play called.\")\n\n        # Get a property (e.g., PlaybackStatus)\n        status = await player_interface.get_playback_status()\n        print(f\"Current playback status: {status}\")\n\n    except Exception as e:\n        print(f\"Could not interact with media player (is one running?): {e}\")\n    finally:\n        bus.disconnect()\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The convenience constructors `MessageBus.session_bus()` and `MessageBus.system_bus()` were removed in version 0.1.1.","severity":"breaking","affected_versions":">=0.1.1"},{"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.","message":"When defining service methods, properties, or signals, all parameters and return values must be explicitly annotated with D-Bus type signature strings.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `MessageBus().connect()` call is an awaitable coroutine and must be `await`ed.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Handling Unix file descriptors (type 'h') requires explicit configuration and manual management.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Replace `MessageBus.session_bus()` or `MessageBus.system_bus()` with `await MessageBus().connect()` or `await MessageBus(bus_type=BusType.SYSTEM).connect()` respectively.","cause":"Attempting to use deprecated convenience constructors for the message bus after version 0.1.1.","error":"AttributeError: 'MessageBus' object has no attribute 'session_bus'"},{"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':`.","cause":"A method, property getter/setter, or signal in a `ServiceInterface` subclass has not been annotated with a D-Bus type signature string.","error":"ValueError: method parameters must specify the dbus type string as an annotation"},{"fix":"Ensure that `MessageBus().connect()` is called with the `await` keyword: `bus = await MessageBus().connect()`.","cause":"Attempting to use the result of an awaitable function (like `MessageBus().connect()`) without actually `await`ing it.","error":"TypeError: object 'coroutine' can't be used in 'await' expression"},{"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.","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.","error":"dbus_next.errors.InterfaceNotFoundError: Cannot get interface 'org.mpris.MediaPlayer2.Player' on object at path '/org/mpris/MediaPlayer2'"}]}