Blocking API

Classes

class sdbus.DbusInterfaceCommon(interface_name)

D-Bus interface class. D-Bus methods and properties should be defined using dbus_property() and dbus_method() decorators.

Parameters:

interface_name (str) – Sets the D-Bus interface name that will be used for all properties and methods defined in the body of the class

__init__(service_name, object_path[, bus])

Init will create a proxy to a remote object

Parameters:

  • service_name (str) – Remote object D-Bus connection name. For example, systemd uses org.freedesktop.systemd1

  • object_path (str) – Remote object D-Bus path. Should be a forward slash separated path. Starting object is usually /. Example: /org/freedesktop/systemd/unit/dbus_2eservice

  • bus (SdBus) – Optional D-Bus connection object. If not passed the default D-Bus will be used.

dbus_ping()

Pings the remote service using D-Bus.

Useful to test if connection or remote service is alive.

Warning

This method is ignores the particular object path meaning it can NOT be used to test if object exist.

dbus_machine_id()

Returns the machine UUID of D-Bus the object is connected to.

Returns:

machine UUID

Return type:

str

dbus_introspect()

Get D-Bus introspection XML.

It is users responsibility to parse that data.

Returns:

string with introspection XML

Return type:

str

properties_get_all_dict()

Get all object properties as a dictionary where keys are member names and values are properties values.

Equivalent to GetAll method of the org.freedesktop.DBus.Properties interface but the member names are automatically translated to python names. (internally calls it for each interface used in class definition)

Parameters:

on_unknown_member (str) – If an unknown D-Bus property was encountered either raise an "error" (default), "ignore" the property or "reuse" the D-Bus name for the member.

Returns:

dictionary of properties

Return type:

Dict[str, Any]

Example:

from sdbus import (DbusInterfaceCommon,
                   dbus_method, dbus_property)


class ExampleInterface(DbusInterfaceCommon,
                       interface_name='org.example.my'
                       ):

    # Method that takes an integer and does not return anything
    @dbus_method('u')
    def close_notification(self, an_int: int) -> None:
        raise NotImplementedError

    # Method that does not take any arguments and returns a list of str
    @dbus_method()
    def get_capabilities(self) -> List[str]:
        raise NotImplementedError

    # Method that takes a dict of {str: str} and returns an int
    @dbus_method('a{ss}')
    def count_entries(self, a_dict: Dict[str, str]) -> int:
        raise NotImplementedError

    # Read only property of int
    @dbus_property()
    def test_int(self) -> int:
        raise NotImplementedError

    # Read/Write property of str
    @dbus_property('s')
    def test_string(self) -> str:
        raise NotImplementedError
class sdbus.DbusObjectManagerInterface(interface_name)

This class is almost identical to DbusInterfaceCommon but implements ObjectManager interface.

get_managed_objects()

Get the objects this object manager in managing.

Returns:

Triple nested dictionary that contains all the objects paths with their properties values.

Dict[ObjectPath, Dict[InterfaceName, Dict[PropertyName, PropertyValue]]]

Return type:

Dict[str, Dict[str, Dict[str, Any]]]

Decorators

@sdbus.dbus_method([input_signature[, flags[, method_name]]])

Define D-Bus method

Decorated function becomes linked to D-Bus method. Always use round brackets () even when not passing any arguments.

Parameters:

  • input_signature (str) – D-Bus input signature. Defaults to “” meaning method takes no arguments. Required if method takes any arguments.

  • flags (int) –

    modifies behavior. No effect on remote connections. Defaults to 0 meaning no special behavior.

    See Flags .

  • method_name (str) – Explicitly define remote method name. Usually not required as remote method name will be constructed based on original method name.

Defining methods example:

from sdbus import DbusInterfaceCommon, dbus_method


class ExampleInterface(DbusInterfaceCommon,
                       interface_name='org.example.my'
                       ):

    # Method that takes an integer and does not return anything
    @dbus_method('u')
    def close_notification(self, an_int: int) -> None:
        raise NotImplementedError

    # Method that does not take any arguments and returns a list of str
    @dbus_method()
    def get_capabilities(self) -> List[str]:
        raise NotImplementedError

    # Method that takes a dict of {str: str} and returns an int
    @dbus_method('a{ss}')
    def count_entries(self, a_dict: Dict[str, str]) -> int:
        raise NotImplementedError

Calling methods example:

# Initialize the object
d = ExampleInterface(
    service_name='org.example.test',
    object_path='/',
)

d.close_notification(1234)

l = d.get_capabilities()

d.count_entries({'a': 'asdasdasd', 'b': 'hgterghead213d'})
@sdbus.dbus_property([property_signature[, flags[, property_name]]])

Define D-Bus property

Property works just like @property decorator would. Always use round brackets () even when not passing any arguments.

Read only property can be indicated by passing empty D-Bus signature “”.

Trying to assign a read only property will raise AttributeError

Parameters:

  • property_signature (str) – D-Bus property signature. Empty signature “” indicates read-only property. Defaults to empty signature “”. Required only for writable properties.

  • flags (int) –

    modifies behavior. No effect on remote connections. Defaults to 0 meaning no special behavior.

    See Flags .

  • property_name (str) – Explicitly define remote property name. Usually not required as remote property name will be constructed based on original method name.

Defining properties example:

from sdbus import DbusInterfaceCommon, dbus_property


class ExampleInterface(DbusInterfaceCommon,
                       interface_name='org.example.myproperty'
                       ):

    # Property of int
    @dbus_property('i')
    def test_int(self) -> int:
        raise NotImplementedError

    # Property of str
    @dbus_property('s')
    def test_string(self) -> str:
        raise NotImplementedError

Properties usage example:

# Initialize the object
d = ExampleInterface(
    service_name='org.example.test',
    object_path='/',
)

# Print the int
print(d.test_int)

# Assign new string
d.test_string = 'some_string'

# Print it
print(d.test_string)