From e65b269d101ac5fb687a1c9981596ea3ffd1baa3 Mon Sep 17 00:00:00 2001
From: Marko Kohtala <marko.kohtala@gmail.com>
Date: Sun, 11 Jan 2015 22:27:26 +0200
Subject: [PATCH] Implement dbus.service.property decorator and
 PropertiesInterface

This adds dbus server side support for properties using a decorator.
The decorator automagically adds PropertiesInterface to the object.

It also simplifies the _dbus_class_table shared by all derived classes
and containing them to a _dbus_interface_table on each derived class.
---
 dbus/decorators.py          | 102 ++++++++++++++++++++++++++
 dbus/exceptions.py          |  24 +++++++
 dbus/service.py             | 171 ++++++++++++++++++++++++++++++++++++++------
 examples/example-client.py  |  21 ++++--
 examples/example-service.py |  22 +++++-
 5 files changed, 309 insertions(+), 31 deletions(-)

diff --git a/dbus/decorators.py b/dbus/decorators.py
index b164582..e04fd8a 100644
--- a/dbus/decorators.py
+++ b/dbus/decorators.py
@@ -343,3 +343,105 @@ def signal(dbus_interface, signature=None, path_keyword=None,
         return emit_signal
 
     return decorator
+
+
+class property(object):
+    """A decorator used to mark properties of a `dbus.service.Object`.
+
+    :Since: 1.3.0
+    """
+
+    def __init__(self, dbus_interface, signature,
+                 property_name=None, emits_changed_signal=None,
+                 fget=None, fset=None, doc=None):
+        """Initialize the decorator used to mark properties of a
+        `dbus.service.Object`.
+
+        :Parameters:
+            `dbus_interface` : str
+                The D-Bus interface owning the property.
+
+            `signature` : str
+                The signature of the property in the usual D-Bus
+                notation.  It must be a single complete type,
+                i.e. something that can be be suitable to be placed
+                in a variant.
+
+            `property_name` : str
+                A name for the property. Defaults to the name of the getter or
+                setter function.
+
+            `emits_changed_signal` : True, False, "invalidates", or None
+                Tells for introspection if the object emits PropertiesChanged
+                signal.
+
+            `fget` : func or None
+                Getter function taking the instance from which to read the
+                property.
+
+            `fset` : func or None
+                Setter function taking the instance to which set the property
+                and the property value.
+
+            `doc` : str
+                Documentation string for the property. Defaults to documentation
+                string of getter function.
+        """
+        validate_interface_name(dbus_interface)
+        self._dbus_interface = dbus_interface
+
+        # Keep the given name for later assignment of setter
+        self._init_property_name = property_name
+        if property_name is None:
+            if fget is not None:
+                property_name = fget.__name__
+            elif fset is not None:
+                property_name = fset.__name__
+        if property_name is not None and not isinstance(property_name, str):
+            if not is_py2 or not isinstance(property_name, unicode):
+                raise TypeError("Invalid property name: '%s'" % property_name)
+        self.__name__ = property_name
+
+        self._init_doc = doc
+        if doc is None and fget is not None:
+            doc = getattr(fget, "__doc__", None)
+        self.fget = fget
+        self.fset = fset
+        self.__doc__ = doc
+
+        if emits_changed_signal not in (None, True, False, 'invalidates'):
+            raise ValueError("emits_changed_signal invalid value: '%s'" %
+                             emits_changed_signal)
+        self._emits_changed_signal = emits_changed_signal
+        if len(tuple(Signature(signature))) != 1:
+            raise ValueError('signature must have only one item')
+        self._dbus_signature = signature
+
+    def __get__(self, inst, type=None):
+        if inst is None:
+            return self
+        if self.fget is None:
+            raise AttributeError("unreadable attribute")
+        return self.fget(inst)
+
+    def __set__(self, inst, value):
+        if self.fset is None:
+            raise AttributeError("can't set attribute")
+        self.fset(inst, value)
+
+    def __call__(self, fget):
+        return self.getter(fget)
+
+    def _copy(self, fget=None, fset=None):
+        return property(dbus_interface=self._dbus_interface,
+                        signature=self._dbus_signature,
+                        property_name=self._init_property_name,
+                        emits_changed_signal=self._emits_changed_signal,
+                        fget=fget or self.fget, fset=fset or self.fset,
+                        doc=self._init_doc)
+
+    def getter(self, fget):
+        return self._copy(fget=fget)
+
+    def setter(self, fset):
+        return self._copy(fset=fset)
diff --git a/dbus/exceptions.py b/dbus/exceptions.py
index 0930425..23d5bb2 100644
--- a/dbus/exceptions.py
+++ b/dbus/exceptions.py
@@ -118,6 +118,14 @@ class IntrospectionParserException(DBusException):
     def __init__(self, msg=''):
         DBusException.__init__(self, "Error parsing introspect data: %s"%msg)
 
+class UnknownInterfaceException(DBusException):
+
+    include_traceback = True
+    _dbus_error_name = 'org.freedesktop.DBus.Error.UnknownInterface'
+
+    def __init__(self, interface):
+        DBusException.__init__(self, "Unknown interface: %s" % interface)
+
 class UnknownMethodException(DBusException):
 
     include_traceback = True
@@ -126,6 +134,22 @@ class UnknownMethodException(DBusException):
     def __init__(self, method):
         DBusException.__init__(self, "Unknown method: %s"%method)
 
+class UnknownPropertyException(DBusException):
+
+    include_traceback = True
+    _dbus_error_name = 'org.freedesktop.DBus.Error.UnknownProperty'
+
+    def __init__(self, property):
+        DBusException.__init__(self, "Unknown property: %s" % property)
+
+class PropertyReadOnlyException(DBusException):
+
+    include_traceback = True
+    _dbus_error_name = 'org.freedesktop.DBus.Error.PropertyReadOnly'
+
+    def __init__(self, property):
+        DBusException.__init__(self, "Property is read only: %s" % property)
+
 class NameExistsException(DBusException):
 
     include_traceback = True
diff --git a/dbus/service.py b/dbus/service.py
index b1fc21d..4d5fcec 100644
--- a/dbus/service.py
+++ b/dbus/service.py
@@ -23,7 +23,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-__all__ = ('BusName', 'Object', 'method', 'signal')
+__all__ = ('BusName', 'Object', 'PropertiesInterface', 'method', 'property', 'signal')
 __docformat__ = 'restructuredtext'
 
 import sys
@@ -34,11 +34,14 @@ from collections import Sequence
 
 import _dbus_bindings
 from dbus import (
-    INTROSPECTABLE_IFACE, ObjectPath, SessionBus, Signature, Struct,
-    validate_bus_name, validate_object_path)
-from dbus.decorators import method, signal
+    INTROSPECTABLE_IFACE, ObjectPath, PROPERTIES_IFACE, SessionBus, Signature,
+    Struct, validate_bus_name, validate_object_path)
+_builtin_property = property
+from dbus.decorators import method, signal, property
 from dbus.exceptions import (
-    DBusException, NameExistsException, UnknownMethodException)
+    DBusException, NameExistsException, UnknownInterfaceException,
+    UnknownMethodException, UnknownPropertyException,
+    PropertyReadOnlyException)
 from dbus.lowlevel import ErrorMessage, MethodReturnMessage, MethodCallMessage
 from dbus.proxies import LOCAL_PATH
 from dbus._compat import is_py2
@@ -297,20 +300,25 @@ def _method_reply_error(connection, message, exception):
 
 
 class InterfaceType(type):
-    def __init__(cls, name, bases, dct):
-        # these attributes are shared between all instances of the Interface
-        # object, so this has to be a dictionary that maps class names to
-        # the per-class introspection/interface data
-        class_table = getattr(cls, '_dbus_class_table', {})
-        cls._dbus_class_table = class_table
-        interface_table = class_table[cls.__module__ + '.' + name] = {}
+    def __new__(cls, name, bases, dct):
+        # Properties require the PropertiesInterface base.
+        for func in dct.values():
+            if isinstance(func, property):
+                for b in bases:
+                    if issubclass(b, PropertiesInterface):
+                        break
+                else:
+                    bases += (PropertiesInterface,)
+                break
+
+        interface_table = dct.setdefault('_dbus_interface_table', {})
 
         # merge all the name -> method tables for all the interfaces
         # implemented by our base classes into our own
         for b in bases:
-            base_name = b.__module__ + '.' + b.__name__
-            if getattr(b, '_dbus_class_table', False):
-                for (interface, method_table) in class_table[base_name].items():
+            base_interface_table = getattr(b, '_dbus_interface_table', False)
+            if base_interface_table:
+                for (interface, method_table) in base_interface_table.items():
                     our_method_table = interface_table.setdefault(interface, {})
                     our_method_table.update(method_table)
 
@@ -320,9 +328,9 @@ class InterfaceType(type):
                 method_table = interface_table.setdefault(func._dbus_interface, {})
                 method_table[func.__name__] = func
 
-        super(InterfaceType, cls).__init__(name, bases, dct)
+        return type.__new__(cls, name, bases, dct)
 
-    # methods are different to signals, so we have two functions... :)
+    # methods are different to signals and properties, so we have three functions... :)
     def _reflect_on_method(cls, func):
         args = func._dbus_args
 
@@ -370,12 +378,110 @@ class InterfaceType(type):
 
         return reflection_data
 
+    def _reflect_on_property(cls, descriptor):
+        signature = descriptor._dbus_signature
+
+        if descriptor.fget:
+            if descriptor.fset:
+                access = "readwrite"
+            else:
+                access = "read"
+        elif descriptor.fset:
+            access = "write"
+        else:
+            return ""
+        reflection_data = '    <property access="%s" type="%s" name="%s"' % (access, signature, descriptor.__name__)
+        if descriptor._emits_changed_signal is not None:
+            value = {True: "true", False: "false", "invalidates": "invalidates"}[descriptor._emits_changed_signal]
+            reflection_data += '>\n      <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="%s"/>\n    </property>\n' % (value,)
+        else:
+            reflection_data += ' />\n'
+        return reflection_data
+
 
 # Define Interface as an instance of the metaclass InterfaceType, in a way
 # that is compatible across both Python 2 and Python 3.
 Interface = InterfaceType('Interface', (object,), {})
 
 
+class PropertiesInterface(Interface):
+    """An object with properties must inherit from this interface.
+
+    This interface is added automatically to the class when the
+    @\ `dbus.decorators.property` decorator is used.
+
+    :Since: 1.3.0
+    """
+
+    def _get_decorator(self, interface_name, property_name):
+        interfaces = self._dbus_interface_table
+        if interface_name:
+            interface = interfaces.get(interface_name)
+            if interface is None:
+                raise UnknownInterfaceException(interface_name)
+            prop = interface.get(property_name)
+            if prop is None or not isinstance(prop, property):
+                raise UnknownPropertyException(property_name)
+            return prop
+        else:
+            for interface in interfaces.itervalues():
+                prop = interface.get(property_name)
+                if prop and isinstance(prop, property):
+                    return prop
+            raise UnknownPropertyException(property_name)
+
+    @method(PROPERTIES_IFACE, in_signature="ss", out_signature="v")
+    def Get(self, interface_name, property_name):
+        """Get the value of the property on named interface. interface_name
+        may be empty, but if there are many properties with the same name the
+        behaviour is undefined.
+        """
+        prop = self._get_decorator(interface_name, property_name)
+        if not prop.fget:
+            raise DBusException("Property '%s' is not readable" % property_name,
+                                name="org.freedesktop.DBus.Error.InvalidArgs")
+        return prop.fget(self)
+
+    @method(PROPERTIES_IFACE, in_signature="ssv")
+    def Set(self, interface_name, property_name, value):
+        """Set value of property on named interface to value. interface_name
+        may be empty, but if there are many properties with the same name the
+        behaviour is undefined.
+        """
+        prop = self._get_decorator(interface_name, property_name)
+        if not prop.fset:
+            raise PropertyReadOnlyException(property_name)
+        return prop.fset(self, value)
+
+    @method(PROPERTIES_IFACE, in_signature="s", out_signature="a{sv}")
+    def GetAll(self, interface_name):
+        """Return a dictionary of all property names and values. Returns only
+        readable properties.
+        """
+        interfaces = self._dbus_interface_table
+        if interface_name:
+            iface = interfaces.get(interface_name)
+            if iface is None:
+                raise UnknownInterfaceException(interface_name)
+            ifaces = [iface]
+        else:
+            ifaces = interfaces.values()
+        properties = {}
+        for iface in ifaces:
+            for name, prop in iface.items():
+                if not isinstance(prop, property):
+                    continue
+                if not prop.fget or name in properties:
+                    continue
+                properties[name] = prop.fget(self)
+        return properties
+
+    @signal(PROPERTIES_IFACE, signature='sa{sv}as')
+    def PropertiesChanged(self, interface_name, changed_properties,
+                          invalidated_properties):
+        pass
+
+
 #: A unique object used as the value of Object._object_path and
 #: Object._connection if it's actually in more than one place
 _MANY = object()
@@ -384,11 +490,12 @@ class Object(Interface):
     r"""A base class for exporting your own Objects across the Bus.
 
     Just inherit from Object and mark exported methods with the
-    @\ `dbus.service.method` or @\ `dbus.service.signal` decorator.
+    @\ `dbus.service.method`, @\ `dbus.service.signal` or
+    @\ `dbus.service.property` decorator.
 
     Example::
 
-        class Example(dbus.service.object):
+        class Example(dbus.service.Object):
             def __init__(self, object_path):
                 dbus.service.Object.__init__(self, dbus.SessionBus(), path)
                 self._last_input = None
@@ -397,6 +504,8 @@ class Object(Interface):
                                  in_signature='v', out_signature='s')
             def StringifyVariant(self, var):
                 self.LastInputChanged(var)      # emits the signal
+                # Emit the property changed signal
+                self.PropertiesChanged('com.example.Sample', {'LastInput': var}, [])
                 return str(var)
 
             @dbus.service.signal(interface='com.example.Sample',
@@ -410,6 +519,20 @@ class Object(Interface):
                                  in_signature='', out_signature='v')
             def GetLastInput(self):
                 return self._last_input
+
+            @dbus.service.property(interface='com.example.Sample',
+                                   signature='s')
+            def LastInput(self):
+                return self._last_input
+
+            @LastInput.setter
+            def LastInput(self, value):
+                self._last_input = value
+                # By default a property is expected to send the
+                # PropertiesChanged signal when value changes.
+                self.PropertiesChanged('com.example.Sample',
+                                       {'LastInput': var}, [])
+
     """
 
     #: If True, this object can be made available at more than one object path.
@@ -484,7 +607,7 @@ class Object(Interface):
         if conn is not None and object_path is not None:
             self.add_to_connection(conn, object_path)
 
-    @property
+    @_builtin_property
     def __dbus_object_path__(self):
         """The object-path at which this object is available.
         Access raises AttributeError if there is no object path, or more than
@@ -500,7 +623,7 @@ class Object(Interface):
         else:
             return self._object_path
 
-    @property
+    @_builtin_property
     def connection(self):
         """The Connection on which this object is available.
         Access raises AttributeError if there is no Connection, or more than
@@ -516,7 +639,7 @@ class Object(Interface):
         else:
             return self._connection
 
-    @property
+    @_builtin_property
     def locations(self):
         """An iterable over tuples representing locations at which this
         object is available.
@@ -762,7 +885,7 @@ class Object(Interface):
         reflection_data = _dbus_bindings.DBUS_INTROSPECT_1_0_XML_DOCTYPE_DECL_NODE
         reflection_data += '<node name="%s">\n' % object_path
 
-        interfaces = self._dbus_class_table[self.__class__.__module__ + '.' + self.__class__.__name__]
+        interfaces = self._dbus_interface_table
         for (name, funcs) in interfaces.items():
             reflection_data += '  <interface name="%s">\n' % (name)
 
@@ -771,6 +894,8 @@ class Object(Interface):
                     reflection_data += self.__class__._reflect_on_method(func)
                 elif getattr(func, '_dbus_is_signal', False):
                     reflection_data += self.__class__._reflect_on_signal(func)
+                elif isinstance(func, property):
+                    reflection_data += self.__class__._reflect_on_property(func)
 
             reflection_data += '  </interface>\n'
 
diff --git a/examples/example-client.py b/examples/example-client.py
index 262f892..29281ed 100644
--- a/examples/example-client.py
+++ b/examples/example-client.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
 
 usage = """Usage:
 python example-service.py &
@@ -46,30 +47,38 @@ def main():
             dbus_interface = "com.example.SampleInterface")
     except dbus.DBusException:
         print_exc()
-        print usage
+        print(usage)
         sys.exit(1)
 
-    print (hello_reply_list)
+    print(hello_reply_list)
 
     # ... or create an Interface wrapper for the remote object
     iface = dbus.Interface(remote_object, "com.example.SampleInterface")
 
     hello_reply_tuple = iface.GetTuple()
 
-    print hello_reply_tuple
+    print(hello_reply_tuple)
 
     hello_reply_dict = iface.GetDict()
 
-    print hello_reply_dict
+    print(hello_reply_dict)
 
     # D-Bus exceptions are mapped to Python exceptions
     try:
         iface.RaiseException()
     except dbus.DBusException as e:
-        print str(e)
+        print(str(e))
+
+    # D-Bus properties are implemented on server, but client needs to access
+    # them directly.
+    properties = dbus.Interface(remote_object, dbus.PROPERTIES_IFACE)
+    property_value = properties.Get("com.example.SampleInterface", "Property")
+    print(property_value)
+
+    print(properties.Get("com.example.SampleInterface", "Pöö"))
 
     # introspection is automatically supported
-    print remote_object.Introspect(dbus_interface="org.freedesktop.DBus.Introspectable")
+    print(remote_object.Introspect(dbus_interface="org.freedesktop.DBus.Introspectable"))
 
     if sys.argv[1:] == ['--exit-service']:
         iface.Exit()
diff --git a/examples/example-service.py b/examples/example-service.py
index c42b526..c4ac3f7 100644
--- a/examples/example-service.py
+++ b/examples/example-service.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
 
 usage = """Usage:
 python example-service.py &
@@ -69,6 +70,23 @@ class SomeObject(dbus.service.Object):
     def Exit(self):
         mainloop.quit()
 
+    _property_default = "Hello world!"
+    @dbus.service.property("com.example.SampleInterface",
+                           signature='s')
+    def Property(self):
+        """Sample property"""
+        return self._property_default
+
+    @Property.setter
+    def Property(self, value):
+        self._property_default = value
+
+    @dbus.service.property("com.example.SampleInterface", 's',
+                           property_name=u"Pöö")
+    def Property_unicode_name(self):
+        """Sample property"""
+        return "Unicode property"
+
 
 if __name__ == '__main__':
     dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)
@@ -78,6 +96,6 @@ if __name__ == '__main__':
     object = SomeObject(session_bus, '/SomeObject')
 
     mainloop = gobject.MainLoop()
-    print "Running example service."
-    print usage
+    print("Running example service.")
+    print(usage)
     mainloop.run()
-- 
1.9.1