Provided by: python3-dasbus_1.7-2_all bug

NAME

       dasbus - dasbus

       Dasbus  is  a DBus library written in Python 3, based on GLib and inspired by pydbus.  The
       code used to be part of the Anaconda  Installer  project.  It  was  based  on  the  pydbus
       library,  but  we  replaced  it  with  our  own  solution because its upstream development
       stalled. The dasbus library is a result of this effort.

REQUIREMENTS

       • Python 3.6+

       • PyGObject 3

       You can install PyGObject provided by your  operating  system  or  use  PyPI.  The  system
       package  is usually called python3-gi, python3-gobject or pygobject3. See the instructions
       for your platform (only for PyGObject, you don't need cairo or GTK).

       The library is known to work with Python 3.8, PyGObject 3.34 and GLib 2.63, but these  are
       not the required minimal versions.

INSTALLATION

       Install  the package from PyPI or install the package provided by your operating system if
       available.

   Install from PyPI
       Follow the instructions above to install the requirements before you install  dasbus  with
       pip. The required dependencies has to be installed manually in this case.

          pip3 install dasbus

   Install on Arch Linux
       Build  and  install  the  community  package  from  the  Arch User Repository.  Follow the
       guidelines.

          git clone https://aur.archlinux.org/python-dasbus.git
          cd python-dasbus
          makepkg -si

   Install on Debian / Ubuntu
       Install the system package on Debian 11+ or Ubuntu 22.04+.

          sudo apt install python3-dasbus

   Install on Fedora / CentOS / RHEL
       Install the system package on Fedora 31+, CentOS Stream 8+ or RHEL 8+.

          sudo dnf install python3-dasbus

   Install on openSUSE
       Install the system package on openSUSE Tumbleweed or openSUSE Leap 15.2+.

          sudo zypper install python3-dasbus

   Development and testing
       Install podman and use the following command to run all tests in a container.  It  doesn't
       require any additional dependencies:

          make container-ci

       Use the command below to run only the unit tests:

          make container-ci CI_CMD="make test"

   dasbus vs pydbus
       The  dasbus  library  used  to be based on pydbus, but it was later reimplemented. We have
       changed the API and the implementation of the library based on our experience with pydbus.
       However,  it  should  be  possible to modify dasbus classes to work the same way as pydbus
       classes.

   What is new
       • Support for asynchronous DBus calls: DBus methods can be called asynchronously.

       • Support for Unix file  descriptors:  It  is  possible  to  send  or  receive  Unix  file
         descriptors.

       • Mapping  DBus  errors  to exceptions: Use Python exceptions to propagate and handle DBus
         errors.  Define your own rules for mapping  errors  to  exceptions  and  back.  See  the
         ErrorMapper class

       • Support for type hints: Use Python type hints from dasbus.typing to define DBus types.

       • Generating  XML  specifications:  Automatically  generate XML specifications from Python
         classes with the dbus_interface decorator.

       • Support for DBus structures: Represent DBus structures  (dictionaries  of  variants)  by
         Python objects. See the DBusData class.

       • Support  for groups of DBus objects: Use DBus containers from dasbus.server.container to
         publish groups of Python objects.

       • Composition over inheritance: The library follows  the  principle  of  composition  over
         inheritance. It allows to easily change the default behaviour.

       • Lazy DBus connections: DBus connections are established on demand.

       • Lazy DBus proxies: Attributes of DBus proxies are created on demand.

   What is different
       • No context managers: There are no context managers in dasbus. Context managers and event
         loops don't work very well together.

       • No auto-completion: There is no support for  automatic  completion  of  DBus  names  and
         paths.   We  recommend  to work with constants defined by classes from dasbus.identifier
         instead of strings.

       • No unpacking of variants: The dasbus library doesn't  unpack  variants  by  default.  It
         means  that values received from DBus match the types declared in the XML specification.
         Use the get_native function to unpack the values.

       • Obtaining proxy objects: Call the get_proxy method to get a proxy of the specified  DBus
         object.

       • No  single-interface  view:  DBus  proxies don't support single-interface views. Use the
         InterfaceProxy class to access a specific interface of a DBus object.

       • Higher priority of standard interfaces:  If  there  is  a  DBus  interface  in  the  XML
         specification  that  redefines  a  member  of  a standard interface, the DBus proxy will
         choose a member of the standard interface. Use the  InterfaceProxy  class  to  access  a
         specific interface of a DBus object.

       • No  support  for  help: Members of DBus proxies are created lazily, so the build-in help
         function doesn't return useful information about the DBus interfaces.

       • Watching DBus names: Use a service observer to watch a DBus name.

       • Acquiring DBus names: Call the register_service method to acquire a DBus name.

       • Providing XML  specifications:  Use  the  __dbus_xml__  attribute  to  provide  the  XML
         specification  of  a  DBus  object.  Or  you  can  generate  it  from the code using the
         dbus_interface decorator.

       • No   support   for   polkit:   There   is   no   support   for    the    DBus    service
         org.freedesktop.PolicyKit1.

   What is the same (for now)
       • No support for other event loops: Dasbus uses GLib as its backend, so it requires to use
         the GLib event loop. However, the GLib part of dasbus is separated from the rest of  the
         code,  so it shouldn't be too difficult to add support for a different backend. It would
         be necessary to replace dasbus.typing.Variant and dasbus.typing.VariantType  with  their
         abstractions and reorganize the code.

       • No  support  for  org.freedesktop.DBus.ObjectManager:  There  is  no  support for object
         managers, however the DBus containers could be a good starting point.

   Public API
   dasbus.client package
   dasbus.client.handler module
       class AbstractClientObjectHandler(message_bus, service_name, object_path)
              Bases: object

              The abstract handler of a remote DBus object.

              create_member(interface_name, member_name)
                     Create a member of the DBus object.

                     Parametersinterface_name -- a name of the interface

                            • member_name -- a name of the member

                     Returns
                            a signal, a method or a property

              abstract disconnect_members()
                     Disconnect members of the DBus object.

                     Unsubscribe from DBus signals and disconnect all registered callbacks of the
                     proxy signals.

              property object_path
                     DBus object path.

                     Returns
                            a DBus path

              property service_name
                     DBus service name.

                     Returns
                            a DBus name

              property specification
                     DBus specification.

       class   ClientObjectHandler(message_bus,   service_name,  object_path,  error_mapper=None,
       client=<class          'dasbus.client.handler.GLibClient'>,          signal_factory=<class
       'dasbus.signal.Signal'>)
              Bases: AbstractClientObjectHandler

              The client handler of a DBus object.

              disconnect_members()
                     Disconnect members of the DBus object.

       class GLibClient
              Bases: object

              The low-level DBus client library based on GLib.

              DBUS_TIMEOUT_NONE = 2147483647

              classmethod   async_call(connection,   service_name,  object_path,  interface_name,
              method_name,   parameters,   reply_type,   callback,   callback_args=(),   flags=0,
              timeout=2147483647)
                     Asynchronously call a DBus method.

              classmethod get_remote_error_message(error)
                     Get a message of the remote DBus error.

              classmethod get_remote_error_name(error)
                     Get a DBus name of the remote DBus error.

              classmethod is_remote_error(error)
                     Is it a remote DBus error?

              classmethod is_timeout_error(error)
                     Is it a timeout error?

              classmethod subscribe_signal(connection, service_name, object_path, interface_name,
              signal_name, callback, callback_args=(), flags=0)
                     Subscribe to a signal.

                     Returns
                            a callback to unsubscribe

              classmethod  sync_call(connection,   service_name,   object_path,   interface_name,
              method_name, parameters, reply_type, flags=0, timeout=2147483647)
                     Synchronously call a DBus method.

                     Returns
                            a result of the DBus call

   dasbus.client.observer module
       class          DBusObserver(message_bus,          service_name,          monitoring=<class
       'dasbus.client.observer.GLibMonitoring'>)
              Bases: object

              Base class for DBus observers.

              This class is recommended to use only to watch the availability  of  a  service  on
              DBus. It doesn't provide any support for accessing objects provided by the service.

              Usage:

                 # Create the observer and connect to its signals.
                 observer = DBusObserver(SystemBus, "org.freedesktop.NetworkManager")

                 def callback1(observer):
                     print("Service is available!")

                 def callback2(observer):
                     print("Service is unavailable!")

                 observer.service_available.connect(callback1)
                 observer.service_unavailable.connect(callback2)

                 # Connect to the service once it is available.
                 observer.connect_once_available()

                 # Disconnect the observer.
                 observer.disconnect()

              connect_once_available()
                     Connect to the service once it is available.

                     The   observer   is  not  connected  to  the  service  until  it  emits  the
                     service_available signal.

              disconnect()
                     Disconnect from the service.

                     Disconnect from the service  if  it  is  connected  and  stop  watching  its
                     availability.

              property is_service_available
                     The proxy can be accessed.

              property service_available
                     Signal that emits when the service is available.

                     Signal emits this class as an argument. You have to call the watch method to
                     activate the signals.

              property service_name
                     Returns a DBus name.

              property service_unavailable
                     Signal that emits when the service is unavailable.

                     Signal emits this class as an argument. You have to call the watch method to
                     activate the signals.

       exception DBusObserverError
              Bases: Exception

              Exception class for the DBus observers.

       class GLibMonitoring
              Bases: object

              The low-level DBus monitoring library based on GLib.

              classmethod     watch_name(connection,     name,    flags=0,    name_appeared=None,
              name_vanished=None)
                     Watch a service name on the DBus connection.

   dasbus.client.property module
       class PropertyProxy(getter, setter)
              Bases: object

              Proxy of a remote DBus property.

              It can be used to define instance attributes.

              get()  Get the value of the DBus property.

              set(value)
                     Set the value of the DBus property.

   dasbus.client.proxy module
       class AbstractObjectProxy(message_bus, service_name,  object_path,  handler_factory=<class
       'dasbus.client.handler.ClientObjectHandler'>, **handler_arguments)
              Bases: object

              Abstract proxy of a remote DBus object.

       class   InterfaceProxy(message_bus,   service_name,  object_path,  interface_name,  *args,
       **kwargs)
              Bases: AbstractObjectProxy

              Proxy of a remote DBus interface.

       class ObjectProxy(*args, **kwargs)
              Bases: AbstractObjectProxy

              Proxy of a remote DBus object.

       disconnect_proxy(proxy)
              Disconnect the DBus proxy from the remote object.

              Parameters
                     proxy -- a DBus proxy

       get_object_path(proxy)
              Get an object path of the remote DBus object.

              Parameters
                     proxy -- a DBus proxy

              Returns
                     a DBus path

   dasbus.server package
   dasbus.server.container module
       class DBusContainer(message_bus, namespace, basename=None)
              Bases: object

              The container of DBus objects.

              A DBus container should be used to dynamically publish Publishable  objects  within
              the  same namespace. It generates a unique DBus path for each object. It is able to
              resolve a DBus path into an object and an object into a DBus path.

              Example:

                 # Create a container of tasks.
                 container = DBusContainer(
                     namespace=("my", "project"),
                     basename="Task",
                     message_bus=DBus
                 )

                 # Publish a task.
                 path = container.to_object_path(MyTask())

                 # Resolve an object path into a task.
                 task = container.from_object_path(path)

              from_object_path(object_path: ObjPath)
                     Convert a DBus path to a published object.

                     If  no  published  object  is  found  for  the  given   DBus   path,   raise
                     DBusContainerError.

                     Parameters
                            object_path -- a DBus path

                     Returns
                            a published object

              from_object_path_list(object_paths: List[ObjPath])
                     Convert DBus paths to published objects.

                     Parameters
                            object_paths -- a list of DBus paths

                     Returns
                            a list of published objects

              set_namespace(namespace)
                     Set the namespace.

                     All  DBus  objects  from the container should use the same namespace, so the
                     namespace should be set up before any of the DBus objects are published.

                     Parameters
                            namespace -- a sequence of names

              to_object_path(obj) -> ObjPath
                     Convert a publishable object to a DBus path.

                     If no DBus path is found for the given object, publish  the  object  on  the
                     container  message  bus with a unique DBus path generated from the container
                     namespace.

                     Parameters
                            obj -- a publishable object

                     Returns
                            a DBus path

              to_object_path_list(objects) -> List[ObjPath]
                     Convert publishable objects to DBus paths.

                     Parameters
                            objects -- a list of publishable objects

                     Returns
                            a list of DBus paths

       exception DBusContainerError
              Bases: Exception

              General exception for DBus container errors.

   dasbus.server.handler module
       class AbstractServerObjectHandler(message_bus, object_path, obj)
              Bases: object

              The abstract handler of a published object.

              abstract connect_object()
                     Connect the object to DBus.

                     Handle emitted signals of the object with the _emit_signal method and handle
                     incoming DBus calls with the _handle_call method.

              abstract disconnect_object()
                     Disconnect the object from DBus.

                     Unregister the object and disconnect all signals.

              property specification
                     DBus specification.

       class GLibServer
              Bases: object

              The low-level DBus server library based on GLib.

              classmethod   emit_signal(connection,   object_path,  interface_name,  signal_name,
              parameters, destination=None)
                     Emit a DBus signal.

              classmethod get_call_info(invocation)
                     Get information about the DBus call.

                     Supported items:
                        sender str: The bus name that invoked the method

                     There can be more supported items in the future.

                     Parameters
                            invocation -- an invocation of a DBus call

                     Returns
                            a dictionary of information about the DBus call

              classmethod   register_object(connection,   object_path,   object_xml,    callback,
              callback_args=())
                     Register an object on DBus.

              classmethod set_call_error(invocation, error_name, error_message)
                     Set the error of the DBus call.

                     Parametersinvocation -- an invocation of a DBus call

                            • error_name -- a DBus name of the error

                            • error_message -- an error message

              classmethod set_call_reply(invocation, out_type, out_value)
                     Set the reply of the DBus call.

                     Parametersinvocation -- an invocation of a DBus call

                            • out_type -- a type of the reply

                            • out_value -- a value of the reply

       class  ServerObjectHandler(message_bus, object_path, obj, error_mapper=None, server=<class
       'dasbus.server.handler.GLibServer'>, signal_factory=<class 'dasbus.signal.Signal'>)
              Bases: AbstractServerObjectHandler

              The handler of an object published on DBus.

              connect_object()
                     Connect the object to DBus.

              disconnect_object()
                     Disconnect the object from DBus.

   dasbus.server.interface module
       accepts_additional_arguments(method)
              Decorator for accepting extra arguments in a DBus method.

              The decorator allows the server object handler to propagate additional  information
              about the DBus call into the decorated method.

              Use a dictionary of keyword arguments:

                 @accepts_additional_arguments
                 def Method(x: Int, y: Str, **info):
                     pass

              Or use keyword only parameters:

                 @accepts_additional_arguments
                 def Method(x: Int, y: Str, *, call_info):
                     pass

              At  this  moment,  the  library  provides  only the call_info argument generated by
              GLibServer.get_call_info, but the additional arguments can  be  customized  in  the
              _get_additional_arguments method of the server object handler.

              Parameters
                     method -- a DBus method

              Returns
                     a DBus method with a flag

       are_additional_arguments_supported(method)
              Does the given DBus method accept additional arguments?

              Parameters
                     method -- a DBus method

              Returns
                     True or False

       dbus_class(cls)
              DBus class.

              A new DBus class can be defined as:

                 @dbus_class
                 class Class(Interface):
                     ...

              DBus class can implement DBus interfaces, but it cannot define a new interface.

              The   DBus   XML  specification  will  be  generated  from  implemented  interfaces
              (inherited) and it will be accessible as:

                 Class.__dbus_xml__

       dbus_interface(interface_name, namespace=())
              DBus interface.

              A new DBus interface can be defined as:

                 @dbus_interface
                 class Interface():
                     ...

              The interface will be generated from the given class cls with a name interface_name
              and added to the DBus XML specification of the class.

              The XML specification is accessible as: .. code-block:: python
                 Interface.__dbus_xml__

              It is conventional for member names on DBus to consist of capitalized words with no
              punctuation. The generator of the XML specification  enforces  this  convention  to
              prevent   unintended  changes  in  the  specification.  You  can  provide  the  XML
              specification yourself, or override  the  generator  class  to  work  around  these
              constraints.

              Parametersinterface_name -- a DBus name of the interface

                     • namespace -- a sequence of strings

       class dbus_signal(definition=None, factory=<class 'dasbus.signal.Signal'>)
              Bases: object

              DBus signal.

              Can be used as:

                 Signal = dbus_signal()

              Or as a method decorator:

                 @dbus_signal
                 def Signal(x: Int, y: Double):
                     pass

              Signal  is  defined  by  the  type  hints  of  a  decorated method.  This method is
              accessible as: signal.definition

              If the signal is not defined by a method, it is expected to have no  arguments  and
              signal.definition is equal to None.

       get_xml(obj)
              Return XML specification of an object.

              Parameters
                     obj -- an object decorated with @dbus_interface or @dbus_class

              Returns
                     a string with XML specification

   dasbus.server.property module
       exception PropertiesException
              Bases: Exception

              Exception for DBus properties.

       class PropertiesInterface
              Bases: object

              Standard DBus interface org.freedesktop.DBus.Properties.

              DBus  objects  don't  have to inherit this class, because the DBus library provides
              support for this interface by default.  This class only extends this support.

              Report the changed property:

                 self.report_changed_property('X')

              Emit all changes when the method is done:

                 @emits_properties_changed
                 def SetX(x: Int):
                     self.set_x(x)

              PropertiesChanged
                     DBus signal.

                     Can be used as:

                        Signal = dbus_signal()

                     Or as a method decorator:

                        @dbus_signal
                        def Signal(x: Int, y: Double):
                            pass

                     Signal is defined by the type hints of a decorated method.  This  method  is
                     accessible as: signal.definition

                     If  the  signal  is  not  defined  by  a  method,  it is expected to have no
                     arguments and signal.definition is equal to None.

              flush_changes()
                     Flush properties changes.

              report_changed_property(property_name)
                     Reports changed DBus property.

                     Parameters
                            property_name -- a name of a DBus property

       emits_properties_changed(method)
              Decorator for emitting properties changes.

              The  decorated  method  has  to  be   a   member   of   a   class   that   inherits
              PropertiesInterface.

              Parameters
                     method -- a DBus method of a class that inherits PropertiesInterface

              Returns
                     a wrapper of a DBus method that emits PropertiesChanged

   dasbus.server.publishable module
       class Publishable
              Bases: object

              Abstract class for Python objects that can be published on DBus.

              Example:

                 # Define a publishable class.
                 class MyObject(Publishable):

                     def for_publication(self):
                         return MyDBusInterface(self)

                 # Create a publishable object.
                 my_object = MyObject()

                 # Publish the object on DBus.
                 DBus.publish_object("/org/project/x", my_object.for_publication())

              abstract for_publication()
                     Return a DBus representation of this object.

                     Returns
                            an instance of @dbus_interface or @dbus_class

   dasbus.server.template module
       class BasicInterfaceTemplate(implementation)
              Bases: object

              Basic template for a DBus interface.

              This template uses a software design pattern called proxy.

              This  class  provides  a  recommended  way how to define DBus interfaces and create
              publishable DBus objects. The class that defines a DBus  interface  should  inherit
              this  class  and  be  decorated  with @dbus_class or @dbus_interface decorator. The
              implementation of this interface will be  provided  by  a  separate  object  called
              implementation.  Therefore the methods of this class should call the methods of the
              implementation,  the  signals  should  be  connected  to   the   signals   of   the
              implementation  and  the  getters  and  setters  of  properties  should  access the
              properties of the implementation.

                 @dbus_interface("org.myproject.X")
                 class InterfaceX(BasicInterfaceTemplate):
                     def DoSomething(self) -> Str:
                         return self.implementation.do_something()

                 class X(object):
                     def do_something(self):
                         return "Done!"

                 x = X()
                 i = InterfaceX(x)

                 DBus.publish_object("/org/myproject/X", i)

              connect_signals()
                     Interconnect the signals.

                     You should connect the emit methods of the interface signals to the  signals
                     of  the  implementation.  Every time the implementation emits a signal, this
                     interface reemits the signal on DBus.

              property implementation
                     Return the implementation of this interface.

                     Returns
                            an implementation

       class InterfaceTemplate(implementation)
              Bases: BasicInterfaceTemplate, PropertiesInterface

              Template for a DBus interface.

              The   interface   provides    the    support    for    the    standard    interface
              org.freedesktop.DBus.Properties.

              Usage:

                 def connect_signals(self):
                     super().connect_signals()
                     self.implementation.module_properties_changed.connect(
                         self.flush_changes
                     )
                     self.watch_property("X", self.implementation.x_changed)

                 @property
                 def X(self, x) -> Int:
                     return self.implementation.x

                 @emits_properties_changed
                 def SetX(self, x: Int):
                     self.implementation.set_x(x)

              watch_property(property_name, signal)
                     Watch a DBus property.

                     Report a change when the property is changed.

                     Parametersproperty_name -- a name of a DBus property

                            • signal -- a signal that emits when the property is changed

   dasbus.connection module
       class AddressedMessageBus(address, *args, **kwargs)
              Bases: MessageBus

              Representation of a connection for the specified address.

              property address
                     The bus address.

       class GLibConnection
              Bases: object

              The low-level DBus connection library based on GLib.

              DEFAULT_FLAGS     =    <flags    G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT    |
              G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION of type Gio.DBusConnectionFlags>

              static            get_addressed_bus_connection(bus_address,            flags=<flags
              G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT                                     |
              G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION  of  type  Gio.DBusConnectionFlags>,
              observer=None, cancellable=None)
                     Get a connection to a bus at the specified address.

              static get_session_bus_connection(cancellable=None)
                     Get a session bus connection.

              static get_system_bus_connection(cancellable=None)
                     Get a system bus connection.

       class MessageBus(error_mapper=None, provider=<class 'dasbus.connection.GLibConnection'>)
              Bases: AbstractMessageBus

              Representation of a message bus based on D-Bus.

              property connection
                     The DBus connection.

              disconnect()
                     Disconnect from DBus.

              get_proxy(service_name,   object_path,   interface_name=None,   proxy_factory=None,
              **proxy_arguments)
                     Returns a proxy of a remote DBus object.

                     If the proxy factory is not specified, we will use a  default  one.  If  the
                     interface name is set, we will choose InterfaceProxy, otherwise ObjectProxy.

                     If the interface name is set, we will add it to the additional arguments for
                     the proxy factory.

                     Parametersservice_name -- a DBus name of a service

                            • object_path -- a DBus path of an object

                            • interface_name -- a DBus name of an interface or None

                            • proxy_factory -- a factory of a DBus object proxy

                            • proxy_arguments -- additional arguments for the proxy factory

                     Returns
                            a proxy object

              property proxy
                     The proxy of DBus.

              publish_object(object_path,               obj,                server_factory=<class
              'dasbus.server.handler.ServerObjectHandler'>, **server_arguments)
                     Publish an object on DBus.

                     Parametersobject_path -- a DBus path of an object

                            • obj -- an instance of @dbus_interface or @dbus_class

                            • server_factory -- a factory of a DBus server object handler

                            • server_arguments -- additional arguments for the server factory

              register_service(service_name, flags=1)
                     Register a service on DBus.

                     Parametersservice_name -- a DBus name of a service

                            • flags -- the flags argument of the RequestName DBus method

              unpublish_object(object_path)

              unregister_service(object_path)

       class                 SessionMessageBus(error_mapper=None,                 provider=<class
       'dasbus.connection.GLibConnection'>)
              Bases: MessageBus

              Representation of a session bus connection.

       class                 SystemMessageBus(error_mapper=None,                  provider=<class
       'dasbus.connection.GLibConnection'>)
              Bases: MessageBus

              Representation of a system bus connection.

   dasbus.constants module
   dasbus.error module
       class AbstractErrorRule
              Bases: object

              Abstract rule for mapping a Python exception to a DBus error.

              abstract get_name(exception_type)
                     Get a DBus name for the given exception type.

                     Parameters
                            exception_type -- a type of the Python error

                     Returns
                            a name of the DBus error

              abstract get_type(error_name)
                     Get an exception type of the given DBus error.

                     param  error_name:  a  name  of the DBus error :return: a type of the Python
                     error

              abstract match_name(error_name)
                     Is this rule matching the given DBus error?

                     Parameters
                            error_name -- a name of the DBus error

                     Returns
                            True or False

              abstract match_type(exception_type)
                     Is this rule matching the given exception type?

                     Parameters
                            exception_type -- a type of the Python error

                     Returns
                            True or False

       exception DBusError
              Bases: Exception

              A default DBus error.

       class DefaultErrorRule(default_type, default_namespace)
              Bases: AbstractErrorRule

              Default rule for mapping a Python exception to a DBus error.

              get_name(exception_type)
                     Get a DBus name for the given exception type.

              get_type(error_name)
                     Get an exception type of the given DBus error.

              match_name(error_name)
                     Is this rule matching the given DBus error?

              match_type(exception_type)
                     Is this rule matching the given exception type?

       class ErrorMapper
              Bases: object

              Class for mapping Python exceptions to DBus errors.

              add_rule(rule: AbstractErrorRule)
                     Add a rule to the error mapper.

                     The new rule will have a higher priority than the rules already contained in
                     the error mapper.

                     Parameters
                            rule (an instance of AbstractErrorRule) -- an error rule

              get_error_name(exception_type)
                     Get a DBus name of the Python exception.

                     Try  to  find  a  matching  rule in the error mapper.  If a rule matches the
                     given exception type, use the rule to get the name of the DBus error.

                     The rules in the error mapper are processed in the reversed order to respect
                     the priority of the rules.

                     Parameters
                            exception_type  (a  subclass  of  Exception)  -- a type of the Python
                            error

                     Returns
                            a name of the DBus error

                     Raises LookupError -- if no name is found

              get_exception_type(error_name)
                     Get a Python exception type of the DBus error.

                     Try to find a matching rule in the error mapper.   If  a  rule  matches  the
                     given  name  of  a  DBus  error,  use  the  rule to get the type of a Python
                     exception.

                     The rules in the error mapper are processed in the reversed order to respect
                     the priority of the rules.

                     Parameters
                            error_name -- a name of the DBus error

                     Returns
                            a type of the Python exception

                     Return type
                            a subclass of Exception

                     Raises LookupError -- if no type is found

              reset_rules()
                     Reset rules in the error mapper.

                     Reset the error rules to the initial state.  All rules will be replaced with
                     the default ones.

       class ErrorRule(exception_type, error_name)
              Bases: AbstractErrorRule

              Rule for mapping a Python exception to a DBus error.

              get_name(exception_type)
                     Get a DBus name for the given exception type.

              get_type(error_name)
                     Get an exception type of the given DBus error.

              match_name(error_name)
                     Is this rule matching the given DBus error?

              match_type(exception_type)
                     Is this rule matching the given exception type?

       get_error_decorator(error_mapper)
              Generate a decorator for DBus errors.

              Create a function for decorating Python exception classes.  The decorator will  add
              a new rule to the given error mapper that will map the class to the specified error
              name.

              Definition of the decorator:

                 decorator(error_name, namespace=())

              The decorator accepts a name of the DBus error and optionally a  namespace  of  the
              DBus name. The namespace will be used as a prefix of the DBus name.

              Usage:

                 # Create an error mapper.
                 error_mapper = ErrorMapper()

                 # Create a decorator for DBus errors and use it to map
                 # the class ExampleError to the name my.example.Error.
                 dbus_error = create_error_decorator(error_mapper)

                 @dbus_error("my.example.Error")
                 class ExampleError(DBusError):
                     pass

              Parameters
                     error_mapper -- an error mapper

              Returns
                     a decorator

   dasbus.identifier module
       class DBusInterfaceIdentifier(namespace, basename=None, interface_version=None)
              Bases: DBusBaseIdentifier

              Identifier of a DBus interface.

              property interface_name
                     Full name of the DBus interface.

       class      DBusObjectIdentifier(namespace,      basename=None,     interface_version=None,
       object_version=None)
              Bases: DBusInterfaceIdentifier

              Identifier of a DBus object.

              property object_path
                     Full path of the DBus object.

       class DBusServiceIdentifier(message_bus, namespace, basename=None, interface_version=None,
       object_version=None, service_version=None)
              Bases: DBusObjectIdentifier

              Identifier of a DBus service.

              get_proxy(object_path=None, interface_name=None, **bus_arguments)
                     Returns a proxy of the DBus object.

                     If  no  object  path  is specified, we will use the object path of this DBus
                     service.

                     If no interface name is specified, we will use none and create a proxy  from
                     all interfaces of the DBus object.

                     Parametersobject_path -- an object identifier or a DBus path or None

                            • interface_name -- an interface identifier or a DBus name or None

                            • bus_arguments -- additional arguments for the message bus

                     Returns
                            a proxy object

              property message_bus
                     Message bus of the DBus service.

                     Returns
                            a message bus

                     Return type
                            an instance of the MessageBus class

              property service_name
                     Full name of a DBus service.

   dasbus.loop module
       class AbstractEventLoop
              Bases: object

              The abstract representation of the event loop.

              It  is  necessary  to run the event loop to handle emitted DBus signals or incoming
              DBus calls (in the DBus service).

              Example:

                 # Create the event loop.
                 loop = EventLoop()

                 # Start the event loop.
                 loop.run()

                 # Run loop.quit() to stop.

              abstract quit()
                     Stop the event loop.

              abstract run()
                     Start the event loop.

       class EventLoop
              Bases: AbstractEventLoop

              The representation of the event loop.

              quit() Stop the event loop.

              run()  Start the event loop.

   dasbus.namespace module
       get_dbus_name(*namespace)
              Create a DBus name from the given names.

              Parameters
                     namespace -- a sequence of names

              Returns
                     a DBus name

       get_dbus_path(*namespace)
              Create a DBus path from the given names.

              Parameters
                     namespace -- a sequence of names

              Returns
                     a DBus path

       get_namespace_from_name(name)
              Return a namespace of the DBus name.

              Parameters
                     name -- a DBus name

              Returns
                     a sequence of names

   dasbus.signal module
       class Signal
              Bases: object

              Default representation of a signal.

              connect(callback)
                     Connect to a signal.

                     Parameters
                            callback -- a function to register

              disconnect(callback=None)
                     Disconnect from a signal.

                     If no callback is specified, then all functions will  be  unregistered  from
                     the signal.

                     If the specified callback isn't registered, do nothing.

                     Parameters
                            callback -- a function to unregister or None

              emit(*args, **kwargs)
                     Emit a signal with the given arguments.

   dasbus.specification module
       class DBusSpecification
              Bases: object

              DBus XML specification.

              ACCESS_READ = 'read'

              ACCESS_READWRITE = 'readwrite'

              ACCESS_WRITE = 'write'

              DIRECTION_IN = 'in'

              DIRECTION_OUT = 'out'

              class Method(name, interface_name, in_type, out_type)
                     Bases: tuple

                     in_type
                            Alias for field number 2

                     interface_name
                            Alias for field number 1

                     name   Alias for field number 0

                     out_type
                            Alias for field number 3

              class Property(name, interface_name, readable, writable, type)
                     Bases: tuple

                     interface_name
                            Alias for field number 1

                     name   Alias for field number 0

                     readable
                            Alias for field number 2

                     type   Alias for field number 4

                     writable
                            Alias for field number 3

              RETURN_PARAMETER = 'return'

              STANDARD_INTERFACES           =           '\n          <node>\n          <interface
              name="org.freedesktop.DBus.Introspectable">\n  <method  name="Introspect">\n   <arg
              type="s"  name="xml_data" direction="out"/>\n </method>\n </interface>\n <interface
              name="org.freedesktop.DBus.Peer">\n      <method      name="Ping"/>\n       <method
              name="GetMachineId">\n   <arg   type="s"   name="machine_uuid"  direction="out"/>\n
              </method>\n  </interface>\n  <interface   name="org.freedesktop.DBus.Properties">\n
              <method  name="Get">\n  <arg type="s" name="interface_name" direction="in"/>\n <arg
              type="s"  name="property_name"  direction="in"/>\n   <arg   type="v"   name="value"
              direction="out"/>\n    </method>\n    <method    name="GetAll">\n   <arg   type="s"
              name="interface_name"  direction="in"/>\n   <arg   type="a{sv}"   name="properties"
              direction="out"/>\n     </method>\n    <method    name="Set">\n    <arg    type="s"
              name="interface_name"   direction="in"/>\n   <arg   type="s"   name="property_name"
              direction="in"/>\n   <arg   type="v"  name="value"  direction="in"/>\n  </method>\n
              <signal name="PropertiesChanged">\n <arg  type="s"  name="interface_name"/>\n  <arg
              type="a{sv}"          name="changed_properties"/>\n          <arg         type="as"
              name="invalidated_properties"/>\n </signal>\n </interface>\n </node>\n '

              class Signal(name, interface_name, type)
                     Bases: tuple

                     interface_name
                            Alias for field number 1

                     name   Alias for field number 0

                     type   Alias for field number 2

              add_member(member)
                     Add a member of a DBus interface.

              classmethod from_xml(xml)
                     Return a DBus specification for the given XML.

              get_member(interface_name, member_name)
                     Get a member of a DBus interface.

              property interfaces
                     Interfaces of the DBus specification.

              property members
                     Members of the DBus specification.

       exception DBusSpecificationError
              Bases: Exception

              Exception for the DBus specification errors.

       class DBusSpecificationParser
              Bases: object

              Class for parsing DBus XML specification.

              classmethod                 parse_specification(xml,                 factory=<class
              'dasbus.specification.DBusSpecification'>)
                     Generate a representation of a DBus XML specification.

                     Parametersxml -- the XML specification to parse

                            • factory -- the DBus specification factory

                     Returns
                            a representation od the DBus specification

              xml_parser
                     alias of XMLParser

   dasbus.structure module
       class DBusData
              Bases: object

              Object representation of data in a DBus structure.

              Classes derived from this class should represent specific types of DBus structures.
              They will support a conversion from a DBus structure  of  this  type  to  a  Python
              object and back.

              classmethod from_structure(structure: Dict[str, Variant])
                     Convert a DBus structure to a data object.

                     Parameters
                            structure -- a DBus structure

                     Returns
                            a data object

              classmethod from_structure_list(structures: List[Dict[str, Variant]])
                     Convert DBus structures to data objects.

                     Parameters
                            structures -- a list of DBus structures

                     Returns
                            a list of data objects

              classmethod to_structure(data) -> Dict[str, Variant]
                     Convert this data object to a DBus structure.

                     Returns
                            a DBus structure

              classmethod to_structure_list(objects) -> List[Dict[str, Variant]]
                     Convert data objects to DBus structures.

                     Parameters
                            objects -- a list of data objects

                     Returns
                            a list of DBus structures

       exception DBusStructureError
              Bases: Exception

              General exception for DBus structure errors.

       compare_data(obj, other)
              Compare data of the given data objects.

              Parametersobj -- a data object

                     • other -- another data object

              Returns
                     True if the data is equal, otherwise False

       generate_string_from_data(obj, skip=None, add=None)
              Generate a string representation of a data object.

              Set the argument 'skip' to skip attributes with sensitive data.

              Set  the  argument  'add'  to  add  other  values to the string representation. The
              attributes in the string representation will be sorted alphabetically.

              Parametersobj -- a data object

                     • skip -- a list of names that should be skipped or None

                     • add -- a dictionary of attributes to add or None

              Returns
                     a string representation of the data object

   dasbus.typing module
       Bool   alias of bool

       Double alias of float

       Int    alias of int

       Str    alias of str

       class Variant(format_string, value)
              Bases: Variant

              Constructors

                 new_array(child_type:GLib.VariantType=None, children:list=None) -> GLib.Variant
                 new_boolean(value:bool) -> GLib.Variant
                 new_byte(value:int) -> GLib.Variant
                 new_bytestring(string:list) -> GLib.Variant
                 new_bytestring_array(strv:list) -> GLib.Variant
                 new_dict_entry(key:GLib.Variant, value:GLib.Variant) -> GLib.Variant
                 new_double(value:float) -> GLib.Variant
                 new_fixed_array(element_type:GLib.VariantType, elements=None, n_elements:int, element_size:int) -> GLib.Variant
                 new_from_bytes(type:GLib.VariantType, bytes:GLib.Bytes, trusted:bool) -> GLib.Variant
                 new_from_data(type:GLib.VariantType, data:list, trusted:bool, notify:GLib.DestroyNotify, user_data=None) -> GLib.Variant
                 new_handle(value:int) -> GLib.Variant
                 new_int16(value:int) -> GLib.Variant
                 new_int32(value:int) -> GLib.Variant
                 new_int64(value:int) -> GLib.Variant
                 new_maybe(child_type:GLib.VariantType=None, child:GLib.Variant=None) -> GLib.Variant
                 new_object_path(object_path:str) -> GLib.Variant
                 new_objv(strv:list) -> GLib.Variant
                 new_signature(signature:str) -> GLib.Variant
                 new_string(string:str) -> GLib.Variant
                 new_strv(strv:list) -> GLib.Variant
                 new_tuple(children:list) -> GLib.Variant
                 new_uint16(value:int) -> GLib.Variant
                 new_uint32(value:int) -> GLib.Variant
                 new_uint64(value:int) -> GLib.Variant
                 new_variant(value:GLib.Variant) -> GLib.Variant

              get_string(self) -> str, length:int

              keys()

              static new_tuple(children: list) -> GLib.Variant

              classmethod split_signature(signature)
                     Return a list of the element signatures of the topmost signature tuple.

                     If the signature is not a tuple, it returns  one  element  with  the  entire
                     signature. If the signature is an empty tuple, the result is [].

                     This  is  useful for e. g. iterating over method parameters which are passed
                     as a single Variant.

              unpack()
                     Decompose a GVariant into a native Python object.

       class VariantType(**kwargs)
              Bases: Boxed

              Constructors

                 new(type_string:str) -> GLib.VariantType
                 new_array(element:GLib.VariantType) -> GLib.VariantType
                 new_dict_entry(key:GLib.VariantType, value:GLib.VariantType) -> GLib.VariantType
                 new_maybe(element:GLib.VariantType) -> GLib.VariantType
                 new_tuple(items:list) -> GLib.VariantType

              checked_ = gi.FunctionInfo(checked_, bound=None)

              copy = gi.FunctionInfo(copy, bound=None)

              dup_string = gi.FunctionInfo(dup_string, bound=None)

              element = gi.FunctionInfo(element, bound=None)

              equal = gi.FunctionInfo(equal, bound=None)

              first = gi.FunctionInfo(first, bound=None)

              free = gi.FunctionInfo(free, bound=None)

              get_string_length = gi.FunctionInfo(get_string_length, bound=None)

              hash = gi.FunctionInfo(hash, bound=None)

              is_array = gi.FunctionInfo(is_array, bound=None)

              is_basic = gi.FunctionInfo(is_basic, bound=None)

              is_container = gi.FunctionInfo(is_container, bound=None)

              is_definite = gi.FunctionInfo(is_definite, bound=None)

              is_dict_entry = gi.FunctionInfo(is_dict_entry, bound=None)

              is_maybe = gi.FunctionInfo(is_maybe, bound=None)

              is_subtype_of = gi.FunctionInfo(is_subtype_of, bound=None)

              is_tuple = gi.FunctionInfo(is_tuple, bound=None)

              is_variant = gi.FunctionInfo(is_variant, bound=None)

              key = gi.FunctionInfo(key, bound=None)

              n_items = gi.FunctionInfo(n_items, bound=None)

              new = gi.FunctionInfo(new, bound=<class 'gi.repository.GLib.VariantType'>)

              new_array           =            gi.FunctionInfo(new_array,            bound=<class
              'gi.repository.GLib.VariantType'>)

              new_dict_entry         =        gi.FunctionInfo(new_dict_entry,        bound=<class
              'gi.repository.GLib.VariantType'>)

              new_maybe           =            gi.FunctionInfo(new_maybe,            bound=<class
              'gi.repository.GLib.VariantType'>)

              new_tuple            =            gi.FunctionInfo(new_tuple,           bound=<class
              'gi.repository.GLib.VariantType'>)

              next = gi.FunctionInfo(next, bound=None)

              string_get_depth_ = gi.FunctionInfo(string_get_depth_, bound=None)

              string_is_valid = gi.FunctionInfo(string_is_valid, bound=None)

              string_scan = gi.FunctionInfo(string_scan, bound=None)

              value = gi.FunctionInfo(value, bound=None)

       class VariantUnpacker
              Bases: VariantUnpacking

              Class for unpacking variants.

              classmethod apply(variant)
                     Unpack the specified variant.

                     Parameters
                            variant -- a variant to unpack

                     Returns
                            an unpacked value

       class VariantUnpacking
              Bases: object

              Set of functions of unpacking a variant.

              This class is doing the same as the unpack method of  the  Variant  class,  but  it
              allows to reuse the code for other variant modifications.

       class VariantUnwrapper
              Bases: VariantUnpacking

              Class for unwrapping variants.

              classmethod apply(variant)
                     Unwrap the specified variant.

                     Parameters
                            variant -- a variant to unwrap

                     Returns
                            a unwrapped value

       get_dbus_type(type_hint)
              Return DBus representation of a type hint.

              Parameters
                     type_hint -- a type hint

              Returns
                     a string with DBus representation

       get_native(value)
              Decompose a DBus value into a native Python object.

              This  function  is  useful  for  testing,  when  the DBus library doesn't decompose
              arguments and return values of DBus calls.

              Parameters
                     value -- a DBus value

              Returns
                     a native Python object

       get_type_arguments(type_hint)
              Get the arguments of the type hint.

              For example, Str and Int are arguments of the type hint Tuple(Str, Int).

              Parameters
                     type_hint -- a type hint

              Returns
                     a type arguments

       get_variant(type_hint, value)
              Return a variant data type.

              The type of a variant is specified with a type hint.

              Example:

                 v1 = get_variant(Bool, True)
                 v2 = get_variant(List[Int], [1,2,3])

              Parameterstype_hint -- a type hint or a type string

                     • value -- a value of the variant

              Returns
                     an instance of Variant

       get_variant_type(type_hint)
              Return a type of a variant data type.

              Parameters
                     type_hint -- a type hint or a type string

              Returns
                     an instance of VariantType

       is_base_type(type_hint, base_type)
              Is the given base type a base of the specified type hint?

              For example, List is a base of the type hint List[Int] and Int is  a  base  of  the
              type hint Int. A class is a base of itself and of every subclass of this class.

              Parameterstype_hint -- a type hint

                     • base_type -- a base type

              Returns
                     True or False

       is_tuple_of_one(type_hint)
              Is the type hint a tuple of one item?

              Parameters
                     type_hint -- a type hint or a type string

              Returns
                     True or False

       unwrap_variant(variant)
              Unwrap a variant data type.

              Unlike  the  unpack  method of the Variant class, this function doesn't recursively
              unpacks all variants in the data  structure.   It  will  unpack  only  the  topmost
              variant.

              The implementation is inspired by the unpack method.

              Parameters
                     variant -- a variant

              Returns
                     a value

   dasbus.xml module
       class XMLGenerator
              Bases: XMLParser

              Class for generating XML.

              static add_child(parent_element, child_element)
                     Append the child element to the parent element.

              static add_comment(element, comment)

              static create_interface(name)
                     Create an interface element.

              static create_method(name)
                     Create a method element.

              static create_node()
                     Create a node element called node.

              static create_parameter(name, param_type, direction)
                     Create a parameter element.

              static create_property(name, property_type, access)
                     Create a property element.

              static create_signal(name)
                     Create a signal element.

              static element_to_xml(element)
                     Return XML of the element.

              static prettify_xml(xml)
                     Return pretty printed normalized XML.

                     Python  3.8  changed the order of the attributes and introduced the function
                     canonicalize that should be used to normalize XML.

       class XMLParser
              Bases: object

              Class for parsing XML.

              static get_access(node)

              static get_direction(node)

              static get_interfaces_from_node(node_element)
                     Return a dictionary of interfaces defined in a node element.

              static get_name(node)

              static get_type(node)

              static has_name(node, node_name)

              static is_interface(member_node)

              static is_member(member_node)

              static is_method(member_node)

              static is_parameter(member_node)

              static is_property(member_node)

              static is_signal(member_node)

              static xml_to_element(xml)

   Examples
       Look at the complete examples  or  DBus  services  of  the  Anaconda  Installer  for  more
       inspiration.

   Basic usage
       Show the current hostname.

          from dasbus.connection import SystemMessageBus
          bus = SystemMessageBus()

          proxy = bus.get_proxy(
              "org.freedesktop.hostname1",
              "/org/freedesktop/hostname1"
          )

          print(proxy.Hostname)

       Send a notification to the notification server.

          from dasbus.connection import SessionMessageBus
          bus = SessionMessageBus()

          proxy = bus.get_proxy(
              "org.freedesktop.Notifications",
              "/org/freedesktop/Notifications"
          )

          id = proxy.Notify(
              "", 0, "face-smile", "Hello World!",
              "This notification can be ignored.",
              [], {}, 0
          )

          print("The notification {} was sent.".format(id))

       Handle a closed notification.

          from dasbus.loop import EventLoop
          loop = EventLoop()

          from dasbus.connection import SessionMessageBus
          bus = SessionMessageBus()

          proxy = bus.get_proxy(
              "org.freedesktop.Notifications",
              "/org/freedesktop/Notifications"
          )

          def callback(id, reason):
              print("The notification {} was closed.".format(id))

          proxy.NotificationClosed.connect(callback)
          loop.run()

       Asynchronously fetch a list of network devices.

          from dasbus.loop import EventLoop
          loop = EventLoop()

          from dasbus.connection import SystemMessageBus
          bus = SystemMessageBus()

          proxy = bus.get_proxy(
              "org.freedesktop.NetworkManager",
              "/org/freedesktop/NetworkManager"
          )

          def callback(call):
              print(call())

          proxy.GetDevices(callback=callback)
          loop.run()

       Define the org.example.HelloWorld service.

          class HelloWorld(object):
              __dbus_xml__ = """
              <node>
                  <interface name="org.example.HelloWorld">
                      <method name="Hello">
                          <arg direction="in" name="name" type="s" />
                          <arg direction="out" name="return" type="s" />
                      </method>
                  </interface>
              </node>
              """

              def Hello(self, name):
                  return "Hello {}!".format(name)

       Define   the   org.example.HelloWorld   service   with   an  automatically  generated  XML
       specification.

          from dasbus.server.interface import dbus_interface
          from dasbus.typing import Str

          @dbus_interface("org.example.HelloWorld")
          class HelloWorld(object):

              def Hello(self, name: Str) -> Str:
                  return "Hello {}!".format(name)

          print(HelloWorld.__dbus_xml__)

       Publish the org.example.HelloWorld service on the session message bus.

          from dasbus.connection import SessionMessageBus
          bus = SessionMessageBus()
          bus.publish_object("/org/example/HelloWorld", HelloWorld())
          bus.register_service("org.example.HelloWorld")

          from dasbus.loop import EventLoop
          loop = EventLoop()
          loop.run()

   Support for Unix file descriptors
       The support for Unix file descriptors is disabled by default. It needs  to  be  explicitly
       enabled  when  you create a DBus proxy or publish a DBus object that could send or receive
       Unix file descriptors.

       WARNING:
          This functionality is supported only on UNIX.

       Send and receive Unix file descriptors with a DBus proxy.

          import os
          from dasbus.connection import SystemMessageBus
          from dasbus.unix import GLibClientUnix
          bus = SystemMessageBus()

          proxy = bus.get_proxy(
              "org.freedesktop.login1",
              "/org/freedesktop/login1",
              client=GLibClientUnix
          )

          fd = proxy.Inhibit(
              "sleep", "my-example", "Running an example", "block"
          )

          proxy.ListInhibitors()
          os.close(fd)

       Allow to send and receive Unix file descriptors within  the  /org/example/HelloWorld  DBus
       object.

          from dasbus.unix import GLibServerUnix
          bus.publish_object(
              "/org/example/HelloWorld",
              HelloWorld(),
              server=GLibServerUnix
          )

   Management of DBus names and paths
       Use constants to define DBus services and objects.

          from dasbus.connection import SystemMessageBus
          from dasbus.identifier import DBusServiceIdentifier, DBusObjectIdentifier

          NETWORK_MANAGER_NAMESPACE = (
              "org", "freedesktop", "NetworkManager"
          )

          NETWORK_MANAGER = DBusServiceIdentifier(
              namespace=NETWORK_MANAGER_NAMESPACE,
              message_bus=SystemMessageBus()
          )

          NETWORK_MANAGER_SETTINGS = DBusObjectIdentifier(
              namespace=NETWORK_MANAGER_NAMESPACE,
              basename="Settings"
          )

       Create a proxy of the org.freedesktop.NetworkManager service.

          proxy = NETWORK_MANAGER.get_proxy()
          print(proxy.NetworkingEnabled)

       Create a proxy of the /org/freedesktop/NetworkManager/Settings object.

          proxy = NETWORK_MANAGER.get_proxy(NETWORK_MANAGER_SETTINGS)
          print(proxy.Hostname)

       See a complete example.

   Error handling
       Use exceptions to propagate and handle DBus errors. Create an error mapper and a decorator
       for mapping Python exception classes to DBus error names.

          from dasbus.error import ErrorMapper, DBusError, get_error_decorator
          error_mapper = ErrorMapper()
          dbus_error = get_error_decorator(error_mapper)

       Use the decorator  to  register  Python  exceptions  that  represent  DBus  errors.  These
       exceptions  can  be  raised  by DBus services and caught by DBus clients in the try-except
       block.

          @dbus_error("org.freedesktop.DBus.Error.InvalidArgs")
          class InvalidArgs(DBusError):
              pass

       The message bus will use the specified error  mapper  to  automatically  transform  Python
       exceptions to DBus errors and back.

          from dasbus.connection import SessionMessageBus
          bus = SessionMessageBus(error_mapper=error_mapper)

       See a complete example.

   Timeout for a DBus call
       Call DBus methods with a timeout (specified in milliseconds).

          proxy = NETWORK_MANAGER.get_proxy()

          try:
              proxy.CheckConnectivity(timeout=3)
          except TimeoutError:
              print("The call timed out!")

   Support for DBus structures
       Represent  DBus  structures  by  Python  objects.  A  DBus  structure  is  a dictionary of
       attributes that maps attribute names to variants with attribute values. Use Python objects
       to define such structures. They can be easily converted to a dictionary, send via DBus and
       converted back to an object.

          from dasbus.structure import DBusData
          from dasbus.typing import Str, get_variant

          class UserData(DBusData):
              def __init__(self):
                  self._name = ""

              @property
              def name(self) -> Str:
                  return self._name

              @name.setter
              def name(self, name):
                  self._name = name

          data = UserData()
          data.name = "Alice"

          print(UserData.to_structure(data))
          print(UserData.from_structure({
              "name": get_variant(Str, "Bob")
          }))

       See a complete example.

   Management of dynamic DBus objects
       Create Python objects that can be automatically  published  on  DBus.  These  objects  are
       usually managed by DBus containers and published on demand.

          from dasbus.server.interface import dbus_interface
          from dasbus.server.template import InterfaceTemplate
          from dasbus.server.publishable import Publishable
          from dasbus.typing import Str

          @dbus_interface("org.example.Chat")
          class ChatInterface(InterfaceTemplate):

              def Send(self, message: Str):
                  return self.implementation.send()

          class Chat(Publishable):

              def for_publication(self):
                  return ChatInterface(self)

              def send(self, message):
                  print(message)

       Use  DBus  containers  to automatically publish dynamically created Python objects. A DBus
       container converts publishable Python objects into  DBus  paths  and  back.  It  generates
       unique  DBus  paths in the specified namespace and assigns them to objects. Each object is
       published when its DBus path is requested for the first time.

          from dasbus.connection import SessionMessageBus
          from dasbus.server.container import DBusContainer

          container = DBusContainer(
              namespace=("org", "example", "Chat"),
              message_bus=SessionMessageBus()
          )

          print(container.to_object_path(Chat()))

       See a complete example.

INDICES AND TABLES

IndexModule IndexSearch Page

AUTHOR

       Vendula Poncova

COPYRIGHT

       2023, Vendula Poncova

                                           Jul 31, 2023                                 DASBUS(1)