# ServiceInterface

class dbus_fast.service.ServiceInterface(name: str)

  An abstract class that can be extended by the user to define DBus services.

  Instances of `ServiceInterface` can be exported on a path of the bus with the `export` method of a `MessageBus`.

  Use the `@dbus_method`, `@dbus_property`, and `@dbus_signal` decorators to mark class methods as DBus methods, properties, and signals respectively.

  Variables:

    name (str) – The name of this interface as it appears to clients. Must be a valid interface name.

  emit_properties_changed(changed_properties: dict[str, Any], invalidated_properties: list[str] = []) → None

    Emit the `org.freedesktop.DBus.Properties.PropertiesChanged` signal.

    This signal is intended to be used to alert clients when a property of the interface has changed.

    Parameters:

      - changed_properties (dict(str, Any)) – The keys must be the names of properties exposed by this bus. The values must be valid for the signature of those properties.

      - invalidated_properties (list(str)) – A list of names of properties that are now invalid (presumably for clients who cache the value).

  introspect() → Interface

    Get introspection information for this interface.

    This might be useful for creating clients for the interface or examining the introspection output of an interface.

    Returns:

      The introspection data for the interface.

    Return type:

      `dbus_fast.introspection.Interface`

@dbus_fast.service.dbus_property(access: PropertyAccess = PropertyAccess.READWRITE, name: str | None = None, disabled: bool = False) → Callable[[Callable[[...], Any]], _Property]

  A decorator to mark a class method of a `ServiceInterface` to be a DBus property.

  The class method must be a Python getter method with a return annotation that is a signature string of a single complete DBus type. When a client gets the property through the `org.freedesktop.DBus.Properties` interface, the getter will be called and the resulting value will be returned to the client.

  If the property is writable, it must have a setter method that takes a single parameter that is annotated with the same signature. When a client sets the property through the `org.freedesktop.DBus.Properties` interface, the setter will be called with the value from the calling client.

  The parameters of the getter and the setter must conform to the dbus-fast type system. The getter or the setter may raise a `DBusError` to return an error to the client.

  Parameters:

    - name (str) – The name that DBus clients will use to interact with this property on the bus.

    - disabled (bool) – If set to true, the property will not be visible to clients.

  Example:

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

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

  If you use Python annotations for type hints, you can use `typing.Annotated` to specify the Python type and the D-Bus signature at the same time like this:

      from dbus_fast.annotations import DBusStr

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

      @string_prop.setter
      def string_prop(self, val: DBusStr):
          self._string_prop = val

  Changed in version v4.0.0: `typing.Annotated` can now be used to provide type hints and the D-Bus signature at the same time. Older versions require D-Bus signature strings to be used.

@dbus_fast.service.dbus_method(name: str | None = None, disabled: bool = False) → Callable[[Callable[[_P], Any]], Callable[[_P], None]]

  A decorator to mark a class method of a `ServiceInterface` to be a DBus service method.

  The parameters and return value must each be annotated with a signature string of a single complete DBus type.

  This class method will be called when a client calls the method on the DBus interface. The parameters given to the function come from the calling client and will conform to the dbus-fast type system. The parameters returned will be returned to the calling client and must conform to the dbus-fast type system. If multiple parameters are returned, they must be contained within a `tuple`.

  The decorated method may raise a `DBusError` to return an error to the client.

  Parameters:

    - name (str) – The member name that DBus clients will use to call this method. Defaults to the name of the class method.

    - disabled (bool) – If set to true, the method will not be visible to clients.

  Example:

      @dbus_method()
      def echo(self, val: 's') -> 's':
          return val

      @dbus_method()
      def echo_two(self, val1: 's', val2: 'u') -> 'su':
          return val1, val2

  If you use Python annotations for type hints, you can use `typing.Annotated` to specify the Python type and the D-Bus signature at the same time like this:

      from dbus_fast.annotations import DBusSignature, DBusStr, DBusUInt32

      @dbus_method()
      def echo(self, val: DBusStr) -> DBusStr:
          return val

      @dbus_method()
      def echo_two(
          self, val1: DBusStr, val2: DBusUInt32
      ) -> Annotated[tuple[str, int], DBusSignature("su")]:
          return val1, val2

  Changed in version v4.0.0: `typing.Annotated` can now be used to provide type hints and the D-Bus signature at the same time. Older versions require D-Bus signature strings to be used.

  Added in version v2.46.0: In older versions, this was named `@method`. The old name still exists.

@dbus_fast.service.dbus_signal(name: str | None = None, disabled: bool = False) → Callable[[Callable[[Concatenate[_TInterface, _P]], Any]], Callable[[Concatenate[_TInterface, _P]], Any]]

  A decorator to mark a class method of a `ServiceInterface` to be a DBus signal.

  The signal is broadcast on the bus when the decorated class method is called by the user.

  If the signal has an out argument, the class method must have a return type annotation with a signature string of a single complete DBus type and the return value of the class method must conform to the dbus-fast type system. If the signal has multiple out arguments, they must be returned within a `tuple`.

  Parameters:

    - name (str) – The member name that will be used for this signal. Defaults to the name of the class method.

    - disabled (bool) – If set to true, the signal will not be visible to clients.

  Example:

      @dbus_signal()
      def string_signal(self, val) -> 's':
          return val

      @dbus_signal()
      def two_strings_signal(self, val1, val2) -> 'ss':
          return val1, val2

  If you use Python annotations for type hints, you can use `typing.Annotated` to specify the Python type and the D-Bus signature at the same time like this:

      from dbus_fast.annotations import DBusSignature, DBusStr

      @dbus_signal()
      def string_signal(self, val: str) -> DBusStr:
          return val

      @dbus_signal()
      def two_strings_signal(
          self, val1: str, val2: str
      ) -> Annotated[tuple[str, str], DBusSignature("ss")]:
          return val1, val2

  Changed in version v4.0.0: `typing.Annotated` can now be used to provide type hints and the D-Bus signature at the same time. Older versions require D-Bus signature strings to be used.

  Added in version v2.46.0: In older versions, this was named `@signal`. The old name still exists.