### Install python-dbus-next Library

Source: https://github.com/altdesktop/python-dbus-next/blob/master/README.md

This command installs the dbus-next library from PyPi using pip3. It is the first step to set up the library for use in any Python project.

```shell
pip3 install dbus-next
```

--------------------------------

### Control Media Player with DBus Client (Python asyncio)

Source: https://github.com/altdesktop/python-dbus-next/blob/master/README.md

This example demonstrates connecting to a DBus service (MPRIS media player) using the dbus-next high-level client. It shows how to introspect objects, get interfaces, call methods (e.g., play, set_volume), retrieve properties, and listen for property change signals asynchronously.

```python
from dbus_next.aio import MessageBus

import asyncio

loop = asyncio.get_event_loop()


async def main():
    bus = await MessageBus().connect()
    # the introspection xml would normally be included in your project, but
    # this is convenient for development
    introspection = await bus.introspect('org.mpris.MediaPlayer2.vlc', '/org/mpris/MediaPlayer2')

    obj = bus.get_proxy_object('org.mpris.MediaPlayer2.vlc', '/org/mpris/MediaPlayer2', introspection)
    player = obj.get_interface('org.mpris.MediaPlayer2.Player')
    properties = obj.get_interface('org.freedesktop.DBus.Properties')

    # call methods on the interface (this causes the media player to play)
    await player.call_play()

    volume = await player.get_volume()
    print(f'current volume: {volume}, setting to 0.5')

    await player.set_volume(0.5)

    # listen to signals
    def on_properties_changed(interface_name, changed_properties, invalidated_properties):
        for changed, variant in changed_properties.items():
            print(f'property changed: {changed} - {variant.value}')

    properties.on_properties_changed(on_properties_changed)

    await loop.create_future()

loop.run_until_complete(main())
```

--------------------------------

### Install Python DBus-Next Library

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/index.rst

This snippet demonstrates how to install the `dbus-next` library using pip, the Python package installer. The library is available on PyPi.

```Bash
pip3 install dbus-next
```

--------------------------------

### Call DBus ListNames Method with Python Low-Level Interface

Source: https://github.com/altdesktop/python-dbus-next/blob/master/README.md

This Python example demonstrates how to use the low-level interface of `python-dbus-next` to connect to the DBus message bus and call the `ListNames` method on the `org.freedesktop.DBus` service. It shows how to construct a `Message` object, make an asynchronous call, and handle potential errors, finally printing the list of active DBus names.

```python
from dbus_next.message import Message, MessageType
from dbus_next.aio import MessageBus

import asyncio
import json

loop = asyncio.get_event_loop()


async def main():
    bus = await MessageBus().connect()

    reply = await bus.call(
        Message(destination='org.freedesktop.DBus',
                path='/org/freedesktop/DBus',
                interface='org.freedesktop.DBus',
                member='ListNames'))

    if reply.message_type == MessageType.ERROR:
        raise Exception(reply.body[0])

    print(json.dumps(reply.body[0], indent=2))


loop.run_until_complete(main())
```

--------------------------------

### DBus Container Type Signature Examples with Python Representation

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/type-system/index.rst

Provides examples of common DBus container type signatures and their corresponding Python list or dictionary representations, illustrating how nested types and special cases like byte arrays and variants are handled.

```APIDOC
Signature | Notes
----------|-------------------------------------------------------
(su)      | Each element in the array must match the corresponding type of the struct member.
as        | The child type comes immediately after the ``a``. The array can have any number of elements, but they all must match the child type.
a{su}     | An "array of dict entries" is represented by a ``dict``. The type after ``{`` is the key type and the type before the ``}`` is the value type.
ay        | Special case: an array of bytes is represented by Python ``bytes``.
v         | Signature must be a single type. A variant may hold a container type.
(asv)     | Containers may be nested.
```

```Python
# (su) signature example
[ 'foo', 5 ]

# as signature example
[ 'foo', 'bar' ]

# a{su} signature example
{ 'foo': 5 }

# ay signature example
b'\0x62\0x75\0x66'

# v signature example
Variant('as', ['hello'])

# (asv) signature example
[ ['foo'], Variant('s', 'bar') ]
```

--------------------------------

### Defining a DBus Service Interface with Methods, Properties, and Signals in Python

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-service/index.rst

This example demonstrates how to define a DBus service interface by subclassing `ServiceInterface`. It showcases the use of `@method()` for callable functions, `@dbus_property()` for properties with getters and setters, and `@signal()` for emitting events. It illustrates DBus type annotations for parameters and return values, including complex types and asynchronous methods. The example also shows how to raise a `DBusError` to provide detailed error information to clients.

```python
from dbus_next.aio import MessageBus
from dbus_next.service import (ServiceInterface,
                                   method, dbus_property, signal)
from dbus_next import Variant, DBusError

import asyncio

class ExampleInterface(ServiceInterface):
    def __init__(self):
        super().__init__('com.example.SampleInterface0')
        self._bar = 105

    @method()
    def Frobate(self, foo: 'i', bar: 's') -> 'a{us}':
        print(f'called Frobate with foo={foo} and bar={bar}')

        return {
            1: 'one',
            2: 'two'
        }

    @method()
    async def Bazify(self, bar: '(iiu)') -> 'vv':
        print(f'called Bazify with bar={bar}')

        return [Variant('s', 'example'), Variant('s', 'bazify')]

    @method()
    def Mogrify(self, bar: '(iiav)'):
        raise DBusError('com.example.error.CannotMogrify',
                            'it is not possible to mogrify')

    @signal()
    def Changed(self) -> 'b':
        return True

    @dbus_property()
    def Bar(self) -> 'y':
        return self._bar

    @Bar.setter
```

--------------------------------

### Python AsyncIO DBus Client Example for Methods, Signals, and Properties

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/index.rst

Demonstrates how to connect to the DBus message bus using `dbus-next.aio`, obtain a proxy object and interface, and interact with a DBus service. This includes calling methods (e.g., `call_frobate`, `call_bazify`, `call_mogrify`), listening to signals (`on_changed`), and accessing properties (`get_Bar`, `set_Bar`). It shows both loading introspection data from a file and dynamic introspection.

```python3
from dbus_next.aio import MessageBus
from dbus_next import Variant

bus = await MessageBus().connect()

with open('introspection.xml', 'r') as f:
    introspection = f.read()

# alternatively, get the data dynamically:
# introspection = await bus.introspect('com.example.name',
#                                      '/com/example/sample_object0')

proxy_object = bus.get_proxy_object('com.example.name',
                                    '/com/example/sample_object0',
                                    introspection)

interface = proxy_object.get_interface('com.example.SampleInterface0')

# Use call_[METHOD] in snake case to call methods, passing the
# in args and receiving the out args. The `baz` returned will
# be type 'a{us}' which translates to a Python dict with `int`
# keys and `str` values.
baz = await interface.call_frobate(5, 'hello')

# `bar` will be a Variant.
bar = await interface.call_bazify([-5, 5, 5])

await interface.call_mogrify([5, 5, [ Variant('s', 'foo') ]])

# Listen to signals by defining a callback that takes the args 
# specified by the signal definition and registering it on the
# interface with on_[SIGNAL] in snake case.

def changed_notify(new_value):
    print(f'The new value is: {new_value}')

interface.on_changed(changed_notify)

# Use get_[PROPERTY] and set_[PROPERTY] with the property in
# snake case to get and set the property.
```

--------------------------------

### DBus Object Introspection XML Example

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/index.rst

An example of the XML introspection data returned by the `Introspect` method of the `org.freedesktop.DBus.Introspectable` interface. This XML defines a DBus node, including interfaces, methods with arguments, signals, and properties, illustrating the structure used by `dbus-next`.

```xml
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/com/example/sample_object0">
  <interface name="com.example.SampleInterface0">
    <method name="Frobate">
      <arg name="foo" type="i" direction="in"/>
      <arg name="bar" type="s" direction="out"/>
      <arg name="baz" type="a{us}" direction="out"/>
    </method>
    <method name="Bazify">
      <arg name="bar" type="(iiu)" direction="in"/>
      <arg name="bar" type="v" direction="out"/>
    </method>
    <method name="Mogrify">
      <arg name="bar" type="(iiav)" direction="in"/>
    </method>
    <signal name="Changed">
      <arg name="new_value" type="b"/>
    </signal>
    <property name="Bar" type="y" access="readwrite"/>
  </interface>
  <node name="child_of_sample_object"/>
  <node name="another_child_of_sample_object"/>
</node>
```

--------------------------------

### Implement a Custom DBus Method Handler in Python

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/low-level-interface/index.rst

This example shows how to set up a custom message handler to respond to specific DBus messages. It first adds a match rule to the bus to receive messages for a custom interface and member, then defines a `message_handler` function that processes incoming messages and returns a method reply. The handler is registered with `add_message_handler`.

```python3
bus = await MessageBus().connect()

reply = await bus.call(
        Message(destination='org.freedesktop.DBus',
                path='/org/freedesktop/DBus',
                member='AddMatch',
                signature='s',
                body=["member='MyMember', interface='com.test.interface'"]))

assert reply.message_type == MessageType.METHOD_RETURN

def message_handler(msg):
        if msg.interface == 'com.test.interface' and msg.member == 'MyMember':
            return Message.new_method_return(msg, 's', ['got it'])

bus.add_message_handler(message_handler)

await bus.wait_for_disconnect()
```

--------------------------------

### Send a Unix File Descriptor over DBus in Python

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/low-level-interface/index.rst

This example illustrates how to send a Unix file descriptor over DBus. It requires setting `negotiate_unix_fd=True` when connecting to the `MessageBus`. An existing file descriptor is opened, then included in the `unix_fds` list of a `Message` object, which is subsequently sent. Users are responsible for closing sent or received file descriptors.

```python3
bus = await MessageBus().connect(negotiate_unix_fd=True)

fd = os.open('/dev/null', os.O_RDONLY)

msg = Message(destination='org.test.destination',
                  path='/org/test/destination',
                  interface='org.test.interface',
                  member='TestMember',
                  signature='h',
                  body=[0],
                  unix_fds=[fd])

await bus.send(msg)
```

--------------------------------

### dbus_next.aio.ProxyInterface Class API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/aio-proxy-interface.rst

This entry provides the API documentation for the `ProxyInterface` class, which is part of the `dbus_next.aio` module. It specifies that all public and undocumented members, along with the class's inheritance hierarchy, are documented.

```APIDOC
Class: dbus_next.aio.ProxyInterface
  Module: dbus_next.aio
  Purpose: Represents a proxy for a D-Bus interface, designed for asynchronous operations.
  Documentation Directives:
    - :members: All public members are documented.
    - :undoc-members: Undocumented members are also included.
    - :show-inheritance: The class inheritance hierarchy is displayed.
```

--------------------------------

### API Documentation for dbus_next.aio.ProxyObject

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/aio-proxy-object.rst

Provides structured API documentation for the `dbus_next.aio.ProxyObject` class, including its members and inheritance hierarchy as generated by Sphinx's `autoclass` directive.

```APIDOC
Class: dbus_next.aio.ProxyObject
  Description: Represents a D-Bus proxy object for asynchronous operations, allowing interaction with remote D-Bus objects.
  Inheritance:
    (Inherited classes would be listed here, as per :show-inheritance:)
  Members:
    (All public and undocumented methods, properties, and attributes of ProxyObject are documented here, as per :members: and :undoc-members:)
```

--------------------------------

### dbus_next.glib.ProxyInterface Class API Documentation

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/glib-proxy-interface.rst

Provides a detailed API reference for the dbus_next.glib.ProxyInterface class, which facilitates interaction with D-Bus interfaces in GLib-based applications. This documentation includes all public and undocumented members, as well as its inheritance hierarchy.

```APIDOC
Class: dbus_next.glib.ProxyInterface
  Description: Represents a D-Bus proxy interface for GLib applications.
  Members: All public and undocumented members are included.
  Inheritance: Shows inherited members and classes.
```

--------------------------------

### API Reference for dbus_next.proxy_object.BaseProxyInterface

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/base-proxy-interface.rst

Documents the BaseProxyInterface class, a foundational component for D-Bus proxy objects within the dbus-next library. This entry specifies that the generated documentation includes all public and undocumented members of the class, as per the Sphinx autoclass directive.

```APIDOC
Class: dbus_next.proxy_object.BaseProxyInterface
  Purpose: Base class for D-Bus proxy interfaces, typically used internally or generated by the dbus-next library.
  Documentation Directives:
    - :members:: All public members (methods, properties) are included in the generated documentation.
    - :undoc-members:: Undocumented members are also included in the generated documentation.
  Note: Specific members (methods, properties) are not detailed in the provided source text, but would be generated by Sphinx based on the class definition.
```

--------------------------------

### Define Custom DBus Service Interface (Python asyncio)

Source: https://github.com/altdesktop/python-dbus-next/blob/master/README.md

This snippet demonstrates how to create and export a custom DBus service using dbus-next's ServiceInterface. It defines a class with decorated methods for DBus methods, properties (with getters and setters), and signals, showcasing how to expose a Python object as a DBus service.

```python
from dbus_next.service import ServiceInterface, method, dbus_property, signal, Variant
from dbus_next.aio import MessageBus

import asyncio

class ExampleInterface(ServiceInterface):
    def __init__(self, name):
        super().__init__(name)
        self._string_prop = 'kevin'

    @method()
    def Echo(self, what: 's') -> 's':
        return what

    @method()
    def GetVariantDict() -> 'a{sv}':
        return {
            'foo': Variant('s', 'bar'),
            'bat': Variant('x', -55),
            'a_list': Variant('as', ['hello', 'world'])
        }

    @dbus_property()
    def string_prop(self) -> 's':
        return self._string_prop

    @string_prop.setter
    def string_prop_setter(self, val: 's'):
        self._string_prop = val

    @signal()
    def signal_simple(self) -> 's':
        return 'hello'

async def main():
    bus = await MessageBus().connect()
    interface = ExampleInterface('test.interface')
    bus.export('/test/path', interface)
    # now that we are ready to handle requests, we can request name from D-Bus
    await bus.request_name('test.name')
    # wait indefinitely
    await asyncio.get_event_loop().create_future()

asyncio.get_event_loop().run_until_complete(main())
```

--------------------------------

### Call a Standard DBus Interface using Python

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/low-level-interface/index.rst

This snippet demonstrates how to call a standard DBus interface method, specifically `ListNames` on `org.freedesktop.DBus`, using the low-level `MessageBus` and `Message` classes. It connects to the bus, constructs a method call message, sends it, and asserts the reply type, then prints the received body.

```python3
bus = await MessageBus().connect()

msg = Message(destination='org.freedesktop.DBus',
                  path='/org/freedesktop/DBus',
                  interface='org.freedesktop.DBus',
                  member='ListNames',
                  serial=bus.next_serial())

reply = await bus.call(msg)

assert reply.message_type == MessageType.METHOD_RETURN

print(reply.body[0])
```

--------------------------------

### API Reference: dbus_next.ReleaseNameReply

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.ReleaseNameReply` enumeration, detailing all its members and their values. This class defines constants representing replies for D-Bus name release operations.

```APIDOC
class dbus_next.ReleaseNameReply:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### dbus_next.SignatureTree API Definition

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/type-system/signature-tree.rst

Defines the API documentation for the `dbus_next.SignatureTree` class, instructing Sphinx to include all members and undocumented members.

```APIDOC
.. autoclass:: dbus_next.SignatureTree
    :members:
    :undoc-members:
```

--------------------------------

### dbus-next High-Level Client Core API References

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/index.rst

Key classes and methods from the `dbus-next` library's high-level client, including `BaseProxyObject`, `BaseProxyInterface`, and `BaseMessageBus`, along with their primary interaction methods like `get_proxy_object`, `introspect`, and `get_interface`.

```APIDOC
Class: dbus_next.proxy_object.BaseProxyObject
  Description: Represents a DBus object node, obtained from MessageBus.get_proxy_object().
  Methods:
    get_interface(interface_name: str)
      Description: Creates a proxy interface for a specified interface name on the proxy object.
      Parameters:
        interface_name (str): The name of the interface to retrieve.

Class: dbus_next.proxy_object.BaseProxyInterface
  Description: Represents a DBus interface. Exposes methods, signals, and properties specified by the interface definition.
  Methods:
    call_[METHOD_NAME](*args)
      Description: Calls a DBus method, where [METHOD_NAME] is the snake_case version of the DBus method name.
      Parameters:
        *args: Arguments corresponding to the 'in' arguments of the DBus method.
      Returns: Values corresponding to the 'out' arguments of the DBus method.
    on_[SIGNAL_NAME](callback: Callable)
      Description: Registers a callback function to listen for a DBus signal, where [SIGNAL_NAME] is the snake_case version of the DBus signal name.
      Parameters:
        callback (Callable): A function that takes arguments specified by the signal definition.
    get_[PROPERTY_NAME]()
      Description: Retrieves the value of a DBus property, where [PROPERTY_NAME] is the snake_case version of the DBus property name.
      Returns: The value of the property.
    set_[PROPERTY_NAME](value)
      Description: Sets the value of a DBus property, where [PROPERTY_NAME] is the snake_case version of the DBus property name.
      Parameters:
        value: The new value for the property.

Class: dbus_next.message_bus.BaseMessageBus
  Description: The main entry point for connecting to the DBus message bus.
  Methods:
    get_proxy_object(bus_name: str, object_path: str, introspection_xml: str)
      Description: Obtains a proxy object for a specific DBus service and object path using provided XML introspection data.
      Parameters:
        bus_name (str): The name of the client to send messages to.
        object_path (str): The path exported by that client.
        introspection_xml (str): The XML introspection data for the object.
      Returns: dbus_next.proxy_object.BaseProxyObject
    introspect(bus_name: str, object_path: str)
      Description: Dynamically retrieves the XML introspection data for a DBus object at runtime.
      Parameters:
        bus_name (str): The name of the client.
        object_path (str): The path of the object.
      Returns: str (XML introspection data)
```

--------------------------------

### dbus_next.glib.MessageBus Class Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/message-bus/glib-message-bus.rst

Detailed API documentation for the `dbus_next.glib.MessageBus` class, including its methods, properties, and inherited members, as generated by Sphinx's autoclass directive.

```APIDOC
class dbus_next.glib.MessageBus:
  # This class documentation is generated by Sphinx's autoclass directive.
  # It includes all public members and inherited members from its base classes.
  # Refer to the source code or full Sphinx documentation for specific methods and attributes.
```

--------------------------------

### API Reference: dbus_next.PropertyAccess

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.PropertyAccess` enumeration, detailing all its members and their values. This class defines constants representing D-Bus property access types.

```APIDOC
class dbus_next.PropertyAccess:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### API Reference: dbus_next.RequestNameReply

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.RequestNameReply` enumeration, detailing all its members and their values. This class defines constants representing replies for D-Bus name requests.

```APIDOC
class dbus_next.RequestNameReply:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### BaseProxyObject Class API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/base-proxy-object.rst

Defines the BaseProxyObject class, a fundamental component for interacting with D-Bus objects as proxies. This entry indicates that the class's public and undocumented members are included in its generated API documentation.

```APIDOC
Class: dbus_next.proxy_object.BaseProxyObject
  Description: Base class for D-Bus proxy objects.
  Directives:
    - :members: Include all public members.
    - :undoc-members: Include all undocumented members.
```

--------------------------------

### dbus_next.Variant Class API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/type-system/variant.rst

Detailed API documentation for the dbus_next.Variant class. This entry specifies that all public and undocumented members of the class should be included in the generated documentation.

```APIDOC
dbus_next.Variant
  Description: Represents a D-Bus variant type.
  Members: All public and undocumented members are included.
```

--------------------------------

### APIDOC: dbus_next.aio.MessageBus Class Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/message-bus/aio-message-bus.rst

Comprehensive API documentation for the `MessageBus` class, which provides an asynchronous interface for interacting with the D-Bus message bus. This documentation is generated using Sphinx's `autoclass` directive, ensuring all public and inherited methods and properties are detailed, along with the class's inheritance hierarchy.

```APIDOC
Class: dbus_next.aio.MessageBus
  Description: Represents an asynchronous D-Bus message bus connection.
  Members:
    (All public and inherited members are documented)
  Inheritance:
    (Inheritance hierarchy is shown)
```

--------------------------------

### Python D-Bus Next Interface Method and Asynchronous Main Loop

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-service/index.rst

This snippet defines a D-Bus interface method `Bar` that updates an internal property and emits a `PropertiesChanged` signal if the value changes. The `main` asynchronous function demonstrates connecting to the D-Bus, exporting an instance of `ExampleInterface` (assumed to be defined elsewhere), requesting a bus name, and then programmatically emitting a `Changed` signal after a two-second delay. The `asyncio` event loop is used to run the `main` coroutine until completion.

```python
        def Bar(self, val: 'y'):
            if self._bar == val:
                return

            self._bar = val

            self.emit_properties_changed({'Bar': self._bar})

    async def main():
        bus = await MessageBus().connect()
        interface = ExampleInterface()
        bus.export('/com/example/sample0', interface)
        await bus.request_name('com.example.name')

        # emit the changed signal after two seconds.
        await asyncio.sleep(2)

        interface.Changed()

        await bus.wait_for_disconnect()

    asyncio.get_event_loop().run_until_complete(main())
```

--------------------------------

### BaseMessageBus Class API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/message-bus/base-message-bus.rst

Provides API documentation for the `dbus_next.message_bus.BaseMessageBus` class, including all its public members as generated by Sphinx's autoclass directive. This class serves as the foundational element for D-Bus message bus implementations.

```APIDOC
Class: dbus_next.message_bus.BaseMessageBus
  Description: Base class for D-Bus message bus implementations.
  Members: All public methods and attributes are documented.
```

--------------------------------

### dbus_next.glib.ProxyObject Class Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/glib-proxy-object.rst

This entry documents the `dbus_next.glib.ProxyObject` class, a core component for interacting with D-Bus services within a GLib application. It details the class structure, its members (including undocumented ones), and its inheritance hierarchy, as generated by Sphinx's `autoclass` directive.

```APIDOC
Class: dbus_next.glib.ProxyObject
  Purpose: Represents a D-Bus remote object, integrated with GLib's event loop for asynchronous operations.
  Members: All public and undocumented members (methods, properties, signals) are included in the documentation.
  Inheritance: The class inheritance hierarchy is shown.
```

--------------------------------

### Perform Asynchronous D-Bus Interface Operations in Python

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-client/index.rst

This snippet demonstrates how to interact with a D-Bus interface asynchronously using `await`. It shows fetching a property value, setting a property value, and waiting for the D-Bus connection to disconnect. This is typical for event-driven D-Bus applications.

```Python
bar_value = await interface.get_bar()

await interface.set_bar(105)

await bus.wait_for_disconnect()
```

--------------------------------

### D-Bus Type Signature to Python Type Mapping

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/type-system/index.rst

This table provides a comprehensive mapping of D-Bus signature tokens to their corresponding Python data types, including specific notes and constraints for each type.

```APIDOC
D-Bus Type Mapping:
Name        | Token | Python Type | Notes
------------|-------|-------------|-------------------------------------------------------------------------
BYTE        | y     | int         | An integer 0-255. In an array, it has type `bytes`.
BOOLEAN     | b     | bool        |
INT16       | n     | int         |
UINT16      | q     | int         |
INT32       | i     | int         |
UINT32      | u     | int         |
INT64       | x     | int         |
UINT64      | t     | int         |
DOUBLE      | d     | float       |
STRING      | s     | str         |
OBJECT_PATH | o     | str         | Must be a valid object path.
SIGNATURE   | g     | str         | Must be a valid signature.
UNIX_FD     | h     | int         | In the low-level interface, an index pointing to a file descriptor in the `unix_fds` member of the :class:`Message <dbus_next.Message>`.
```

--------------------------------

### API Reference: dbus_next.BusType

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.BusType` enumeration, detailing all its members and their values. This class defines constants representing different D-Bus bus types.

```APIDOC
class dbus_next.BusType:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### API Reference: dbus_next.ArgDirection

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.ArgDirection` enumeration, detailing all its members and their values. This class defines constants representing D-Bus argument directions (in/out).

```APIDOC
class dbus_next.ArgDirection:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### API Reference: dbus_next.NameFlag

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.NameFlag` enumeration, detailing all its members and their values. This class defines constants representing different D-Bus name flags.

```APIDOC
class dbus_next.NameFlag:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### DBus Authentication Protocol Classes API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/authentication.rst

API documentation for the DBus authentication protocol classes, including Authenticator, AuthExternal, and AuthAnnonymous, used with MessageBus implementations.

```APIDOC
dbus_next.auth.Authenticator:
  Description: Base class for the DBus authentication protocol.

dbus_next.auth.AuthExternal:
  Description: Implements the EXTERNAL authentication mechanism for DBus.

dbus_next.auth.AuthAnnonymous:
  Description: Implements the ANONYMOUS authentication mechanism for DBus.
```

--------------------------------

### Emit a DBus Signal using Python

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/low-level-interface/index.rst

This snippet demonstrates how to emit a custom DBus signal using the low-level interface. It connects to the message bus and then uses `Message.new_signal` to construct a signal message with a specified path, interface, member, signature, and body, which is then sent using `bus.send()`.

```python3
bus = await MessageBus().connect()

await bus.send(Message.new_signal('/com/test/path',
                                      'com.test.interface',
                                      'SomeSignal',
                                      's', ['a signal']))
```

--------------------------------

### API Reference: dbus_next.MessageFlag

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.MessageFlag` enumeration, detailing all its members and their values. This class defines constants representing different D-Bus message flags.

```APIDOC
class dbus_next.MessageFlag:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### API Reference: dbus_next.MessageType

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.MessageType` enumeration, detailing all its members and their values. This class defines constants representing different D-Bus message types.

```APIDOC
class dbus_next.MessageType:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### DBus Type System Primitive and Container Type Mappings

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/type-system/index.rst

Defines the mapping between fundamental DBus type signatures and their corresponding Python data types, including notes on usage and structure for container types like ARRAY, STRUCT, VARIANT, and DICT_ENTRY.

```APIDOC
DBus Type | Signature | Python Type | Notes
----------|-----------|-------------|-------------------------------------------------------------------------
ARRAY     | a         | list        | Must be followed by a complete type which specifies the child type.
STRUCT    | (         | list        | Types in the Python ``list`` must match the types between the parens.
VARIANT   | v         | :class:`Variant <dbus_next.Variant>` | This class is provided by the library.
DICT_ENTRY| {         | dict        | Must be included in an array to be a ``dict``.
```

--------------------------------

### D-Bus Introspection Classes API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/introspection.rst

This API documentation details the classes provided by the `dbus_next.introspection` module. These classes are essential for programmatically working with D-Bus introspection data, allowing developers to parse and navigate the structure of D-Bus services.

```APIDOC
dbus_next.introspection.Node
  Represents a node in the D-Bus introspection data, typically corresponding to an object path.
  (Members included via :members: and :undoc-members:)

dbus_next.introspection.Interface
  Represents an interface within a D-Bus node, defining its methods, properties, and signals.
  (Members included via :members: and :undoc-members:)

dbus_next.introspection.Property
  Represents a property of a D-Bus interface, including its name, type, and access direction.
  (Members included via :members: and :undoc-members:)

dbus_next.introspection.Method
  Represents a method of a D-Bus interface, including its name and arguments.
  (Members included via :members: and :undoc-members:)

dbus_next.introspection.Signal
  Represents a signal of a D-Bus interface, including its name and arguments.
  (Members included via :members: and :undoc-members:)

dbus_next.introspection.Arg
  Represents an argument for a D-Bus method or signal, including its name and type signature.
  (Members included via :members: and :undoc-members:)
```

--------------------------------

### dbus_next.Message Class API Definition

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/low-level-interface/message.rst

Defines the `Message` class within the `dbus_next` library. This class represents a D-Bus message and its structure. The `autoclass` directive indicates that all public and undocumented members of this class are included in the generated documentation.

```APIDOC
Class: dbus_next.Message
  Description: Represents a D-Bus message, handling its structure, headers, and body.
  Members:
    - All public members (auto-generated)
    - All undocumented members (auto-generated)
```

--------------------------------

### Python dbus_next Library Error Class Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/errors.rst

This section provides API documentation for the error classes defined in the `dbus_next` Python library. These classes are subclasses of `Exception` (or `dbus_next.DBusError` for most) and are raised to indicate various issues encountered during D-Bus communication, such as invalid data formats, authentication failures, or missing interfaces. `dbus_next.DBusError` serves as the base class for all D-Bus related exceptions and includes its own set of members.

```APIDOC
class dbus_next.DBusError(Exception)
  # This class includes various members and undocumented members.
```

```APIDOC
class dbus_next.SignatureBodyMismatchError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidSignatureError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidAddressError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.AuthError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidMessageError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidIntrospectionError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InterfaceNotFoundError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.SignalDisabledError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidBusNameError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidObjectPathError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidInterfaceNameError(dbus_next.DBusError)
```

```APIDOC
class dbus_next.InvalidMemberNameError(dbus_next.DBusError)
```

--------------------------------

### API Reference: dbus_next.ErrorType

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/constants.rst

Auto-generated API documentation for the `dbus_next.ErrorType` enumeration, detailing all its members and their values. This class defines constants representing different D-Bus error types.

```APIDOC
class dbus_next.ErrorType:
  # Members are automatically documented by Sphinx autoclass with :members: and :undoc-members:
```

--------------------------------

### D-Bus Name and Path Validation Functions (dbus_next)

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/validators.rst

Provides a comprehensive list of functions from the `dbus_next` library designed to validate various D-Bus identifiers such as bus names, member names, object paths, and interface names. The `is_` functions return a boolean indicating validity, while the `assert_` functions raise an error if the input is invalid.

```APIDOC
dbus_next.is_bus_name_valid(name: str) -> bool
  Checks if a given string is a valid D-Bus bus name.
dbus_next.is_member_name_valid(name: str) -> bool
  Checks if a given string is a valid D-Bus member name.
dbus_next.is_object_path_valid(path: str) -> bool
  Checks if a given string is a valid D-Bus object path.
dbus_next.is_interface_name_valid(name: str) -> bool
  Checks if a given string is a valid D-Bus interface name.
dbus_next.assert_bus_name_valid(name: str) -> None
  Asserts that a given string is a valid D-Bus bus name, raising an error if not.
dbus_next.assert_member_name_valid(name: str) -> None
  Asserts that a given string is a valid D-Bus member name, raising an error if not.
dbus_next.assert_object_path_valid(path: str) -> None
  Asserts that a given string is a valid D-Bus object path, raising an error if not.
dbus_next.assert_interface_name_valid(name: str) -> None
  Asserts that a given string is a valid D-Bus interface name, raising an error if not.
```

--------------------------------

### Python D-Bus ServiceInterface Class Definition

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-service/service-interface.rst

The `ServiceInterface` class serves as the base for defining D-Bus interfaces. Inheriting from this class allows Python objects to expose methods, properties, and signals over D-Bus. The `:members:` and `:undoc-members:` options indicate that all public and undocumented members of the class should be exposed as part of the D-Bus interface.

```APIDOC
Class: dbus_next.service.ServiceInterface
  Description: Base class for defining D-Bus service interfaces.
  Members: All public and undocumented members are exposed.
```

--------------------------------

### Python D-Bus Method Decorator

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-service/service-interface.rst

The `method` decorator is applied to Python functions within a `ServiceInterface` to expose them as D-Bus methods. Clients can then call these methods remotely over the D-Bus.

```APIDOC
Decorator: dbus_next.service.method
  Description: Decorator to expose a Python method as a D-Bus method.
  Usage: @method
```

--------------------------------

### Python D-Bus Signal Decorator

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-service/service-interface.rst

The `signal` decorator is used on Python functions within a `ServiceInterface` to allow them to emit D-Bus signals. Clients can subscribe to these signals to receive notifications when certain events occur.

```APIDOC
Decorator: dbus_next.service.signal
  Description: Decorator to expose a Python method as a D-Bus signal emitter.
  Usage: @signal
```

--------------------------------

### dbus_next.SignatureType Class API Reference

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/type-system/signature-type.rst

API documentation for the `dbus_next.SignatureType` class, which represents a D-Bus signature type. This entry details the class and its members, excluding the 'signature' member, as generated by the Sphinx `autoclass` directive.

```APIDOC
Class: dbus_next.SignatureType
Description: Represents a D-Bus signature type.
Members: All public and undocumented members are documented.
Excluded Members: signature
```

--------------------------------

### Python D-Bus Property Decorator

Source: https://github.com/altdesktop/python-dbus-next/blob/master/docs/high-level-service/service-interface.rst

The `dbus_property` decorator is used to mark a Python property within a `ServiceInterface` as a D-Bus property. This allows D-Bus clients to read and write the value of the property.

```APIDOC
Decorator: dbus_next.service.dbus_property
  Description: Decorator to expose a Python property as a D-Bus property.
  Usage: @dbus_property
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.