.. py:currentmodule:: sdbus
.. py:class:: DbusInterfaceCommon(interface_name)
D-Bus interface class.
D-Bus methods and properties should be defined using
:py:func:`dbus_property` and :py:func:`dbus_method` decorators.
:param str interface_name: Sets the D-Bus interface
name that will be used for all properties and methods
defined in the body of the class
.. py:method:: __init__(service_name, object_path, [bus])
Init will create a proxy to a remote object
:param str service_name:
Remote object D-Bus connection name.
For example, systemd uses ``org.freedesktop.systemd1``
:param str object_path:
Remote object D-Bus path.
Should be a forward slash separated path.
Starting object is usually ``/``.
Example: ``/org/freedesktop/systemd/unit/dbus_2eservice``
:param SdBus bus:
Optional D-Bus connection object.
If not passed the default D-Bus will be used.
.. py:method:: 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.
.. py:method:: dbus_machine_id()
Returns the machine UUID of D-Bus the object is connected to.
:return: machine UUID
:rtype: str
.. py:method:: dbus_introspect()
Get D-Bus introspection XML.
It is users responsibility to parse that data.
:return: string with introspection XML
:rtype: str
.. py:method:: 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)
:param str on_unknown_member: 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.
:return: dictionary of properties
:rtype: 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
.. py:class:: DbusObjectManagerInterface(interface_name)
This class is almost identical to :py:class:`DbusInterfaceCommon`
but implements `ObjectManager <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager>`_
interface.
.. py:method:: get_managed_objects()
Get the objects this object manager in managing.
:return:
Triple nested dictionary that contains all the objects
paths with their properties values.
dict[ObjectPath, dict[InterfaceName, dict[PropertyName, PropertyValue]]]
:rtype: dict[str, dict[str, dict[str, Any]]]
.. py:decorator:: 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.
:param str input_signature: D-Bus input signature.
Defaults to "" meaning method takes no arguments.
Required if method takes any arguments.
:param int flags: modifies behavior.
No effect on remote connections.
Defaults to 0 meaning no special behavior.
See :ref:`dbus-flags` .
:param str method_name: 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'})
.. py:decorator:: 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 :py:exc:`AttributeError`
:param str property_signature: D-Bus property signature.
Empty signature "" indicates read-only property.
Defaults to empty signature "".
Required only for writable properties.
:param int flags: modifies behavior.
No effect on remote connections.
Defaults to 0 meaning no special behavior.
See :ref:`dbus-flags` .
:param str property_name: 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)