Asyncio API¶
Classes¶
- class sdbus.DbusInterfaceCommonAsync(interface_name)¶
Dbus async interface class. Dbus methods and properties should be defined using
dbus_property_async()
,dbus_signal_async()
, anddbus_method_async()
decorators.Note
Don’t forget to call
super().__init__()
in derived classes init calls as it sets up important attributes.- Parameters
interface_name (str) – Sets the dbus interface name that will be used for all properties, methods and signals defined in the body of the class.
serving_enabled (bool) – If set to
True
the interface will not be served on dbus. Mostly used for interfaces that sd-bus already provides such asorg.freedesktop.DBus.Peer
.
- async dbus_ping()¶
Pings the remote service using dbus.
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.
- async dbus_machine_id()¶
Returns the machine UUID of D-Bus the object is connected to.
- Returns
machine UUID
- Return type
str
- async dbus_introspect()¶
Get dbus introspection XML.
It is users responsibility to parse that data.
- Returns
string with introspection XML
- Return type
str
- properties_changed: Tuple[str, Dict[str, Tuple[str, Any]], List[str]]¶
Signal when one of the objects properties changes.
Signal data is:
- Interface namestr
Name of the interface where property changed
- Changed propertiesDict[str, Tuple[str, Any]]
Dictionary there keys are names of properties changed and values are variants of new value.
- Invalidated propertiesList[str]
List of property names changed but no new value had been provided
- _proxify(bus, service_name, object_path)¶
Begin proxying to a remote dbus object.
- Parameters
service_name (str) – Remote object dbus connection name. For example, systemd uses
org.freedesktop.systemd1
object_path (str) – Remote object dbus path. Should be a forward slash separated path. Starting object is usually
/
. Example:/org/freedesktop/systemd/unit/dbus_2eservice
bus (SdBus) – Optional dbus connection object. If not passed the default dbus will be used.
- classmethod new_proxy(bus, service_name, object_path)¶
Create new proxy object and bypass
__init__
.- Parameters
service_name (str) – Remote object dbus connection name. For example, systemd uses
org.freedesktop.systemd1
object_path (str) – Remote object dbus path. Should be a forward slash separated path. Starting object is usually
/
. Example:/org/freedesktop/systemd/unit/dbus_2eservice
bus (SdBus) – Optional dbus connection object. If not passed the default dbus will be used.
- export_to_dbus(bus, object_path)¶
Object will appear and become callable on dbus.
- Parameters
object_path (str) – Object path that it will be available at.
bus (SdBus) – Optional dbus connection object. If not passed the default dbus will be used.
- class sdbus.DbusObjectManagerInterfaceAsync(interface_name)¶
This class is almost identical to
DbusInterfaceCommonAsync
but implements ObjectManager interface.- async 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]]]
- interfaces_added: Tuple[str, Dict[str, Dict[str, Any]]]¶
Signal when a new object is added or and existing object gains a new interface.
Signal data is:
- Object pathstr
Path to object that was added or modified.
- Object interfaces and propertiesDict[str, Dict[str, Any]]]
Dict[InterfaceName, Dict[PropertyName, PropertyValue]]
- interfaces_removed: Tuple[str, List[str]]¶
Signal when existing object or and interface of existing object is removed.
Signal data is:
- Object pathstr
Path to object that was removed or modified.
- Interfaces listList[str]
Interfaces names that were removed.
Decorators¶
- @sdbus.dbus_method_async([input_signature[, result_signature[, flags[, result_args_names[, input_args_names[, method_name]]]]]])¶
Define a method.
Underlying function must be a coroutine function.
- Parameters
input_signature (str) – dbus input signature. Defaults to “” meaning method takes no arguments. Required if you intend to connect to a remote object.
result_signature (str) – dbus result signature. Defaults to “” meaning method returns empty reply on success. Required if you intend to serve the object.
flags (int) –
modifies behavior. No effect on remote connections. Defaults to 0 meaning no special behavior.
See Flags .
result_args_names (Sequence[str]) –
sequence of result argument names.
These names will show up in introspection data but otherwise have no effect.
Sequence can be list, tuple, etc… Number of elements in the sequence should match the number of result arguments otherwise
SdBusLibraryError
will be raised.Defaults to result arguments being nameless.
input_args_names (Sequence[str]) –
sequence of input argument names.
These names will show up in introspection data but otherwise have no effect.
Sequence can be list, tuple, etc… Number of elements in the sequence should match the number of result arguments otherwise
RuntimeError
will be raised.If
result_args_names
has been passed when Python function argument names will be used otherwise input arguments will be namelessmethod_name (str) – Force specific dbus method name instead of being based on Python function name.
Example:
from sdbus import DbusInterfaceCommonAsync, dbus_method_async class ExampleInterface(DbusInterfaceCommonAsync, interface_name='org.example.test' ): # Method that takes a string # and returns uppercase of that string @dbus_method_async( input_signature='s', result_signature='s', result_args_names=('uppercased', ) # This is optional but # makes arguments have names in # instrospection data. ) async def upper(self, str_to_up: str) -> str: return str_to_up.upper()
- @sdbus.dbus_property_async(property_signature[, flags[, property_name]])¶
Declare a dbus property.
The underlying function has to be a regular
def
function.The property will be read-only or read/write based on if setter was declared.
Warning
Properties are supposed to be lightweight to get or set. Make sure property getter or setter does not perform heavy IO or computation as that will block other methods or properties.
- Parameters
property_signature (str) – Property dbus signature. Has to be a single type or container.
flags (int) –
modifies behavior. No effect on remote connections. Defaults to 0 meaning no special behavior.
See Flags .
property_name (str) – Force specific property name instead of constructing it based on Python function name.
Properties have following methods:
- @sdbus.setter(set_function)¶
Defines the setter function. This makes the property read/write instead of read-only.
See example on how to use.
- async sdbus.get_async()¶
Get the property value.
The property can also be directly
await
ed instead of calling this method.
- async sdbus.set_async(new_value)¶
Set property value.
Example:
from sdbus import DbusInterfaceCommonAsync, dbus_property_async class ExampleInterface(DbusInterfaceCommonAsync, interface_name='org.example.test' ): def __init__(self) -> None: # This is just a generic init self.i = 12345 self.s = 'test' # Read only property. No setter defined. @dbus_property_async('i') def read_only_number(self) -> int: return self.i # Read/write property. First define getter. @dbus_property_async('s') def read_write_str(self) -> str: return self.s # Now create setter. Method name does not matter. @read_write_str.setter # Use the property setter method as decorator def read_write_str_setter(self, new_str: str) -> None: self.s = new_str
- @sdbus.dbus_signal_async([signal_signature[, signal_args_names[, flags[, signal_name]]]])¶
Defines a dbus signal.
Underlying function return type hint is used for signal type hints.
- Parameters
signal_signature (str) – signal dbus signature. Defaults to empty signal.
signal_args_names (Sequence[str]) –
sequence of signal argument names.
These names will show up in introspection data but otherwise have no effect.
Sequence can be list, tuple, etc… Number of elements in the sequence should match the number of result arguments otherwise
RuntimeError
will be raised.Defaults to result arguments being nameless.
flags (int) –
modifies behavior. No effect on remote connections. Defaults to 0 meaning no special behavior.
See Flags .
signal_name (str) – Forces specific signal name instead of being based on Python function name.
Signals have following methods:
- sdbus.__aiter__()¶
Signal can be used as an async generator for loop:
async for x in something.some_signal:
This is main way to await for new events.
Both remote and local objects operate the same way.
- sdbus.emit(args)¶
Emit a new signal with args data.
Example:
from sdbus import DbusInterfaceCommonAsync, dbus_signal_async class ExampleInterface(DbusInterfaceCommonAsync, interface_name='org.example.signal' ): @dbus_signal_async('s') def name_changed(self) -> str: raise NotImplementedError
- @sdbus.dbus_method_async_override¶
Override the method.
Method name should match the super class method name that you want to override.
New method should take same arguments.
You must add round brackets to decorator.
Example:
from sdbus import (DbusInterfaceCommonAsync, dbus_method_async dbus_method_async_override) class ExampleInterface(DbusInterfaceCommonAsync, interface_name='org.example.test' ): # Original call @dbus_method_async('s', 's') async def upper(self, str_to_up: str) -> str: return str_to_up.upper() class ExampleOverride(ExampleInterface): @dbus_method_async_override() async def upper(self, str_to_up: str) -> str: return 'Upper: ' + str_to_up.upper()
- @sdbus.dbus_property_async_override¶
Override property.
You must add round brackets to decorator.
Example:
from sdbus import (DbusInterfaceCommonAsync, dbus_property_async dbus_property_async_override) class ExampleInterface(DbusInterfaceCommonAsync, interface_name='org.example.test' ): def __init__(self) -> None: self.s = 'aaaaaaaaa' # Original property @dbus_property_async('s') def str_prop(self) -> str: return self.s @str_prop.setter def str_prop_setter(self, new_s: str) -> None: self.s = new_s class ExampleOverride(ExampleInterface): @dbus_property_async_override() def str_prop(self) -> str: return 'Test property' + self.s # Setter needs to be decorated again to override @str_prop.setter def str_prop_setter(self, new_s: str) -> None: self.s = new_s.upper()