From ce9820f94ecc59707af6dfe14831a09c5fbfb49e Mon Sep 17 00:00:00 2001
From: Marko Kohtala <marko.kohtala@cef.fi>
Date: Fri, 17 Jun 2011 15:47:24 +0300
Subject: [PATCH] Add support for properties.

---
 dbus/decorators.py |   94 +++++++++++++++++++++++++++++++++++++++++
 dbus/service.py    |  118 +++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 206 insertions(+), 6 deletions(-)

diff --git a/dbus/decorators.py b/dbus/decorators.py
index a5ca281..3977c68 100644
--- a/dbus/decorators.py
+++ b/dbus/decorators.py
@@ -338,3 +338,97 @@ 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`.
+    """
+
+    def __init__(self, dbus_interface=None, signature=None,
+                 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. The
+                signature must be suitable to be carried 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
+                Getter function taking the instance from which to read the
+                property.
+
+            `fset` : func
+                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.
+
+                :Since: 0.85.0
+        """
+        validate_interface_name(dbus_interface)
+        self._dbus_interface = dbus_interface
+
+        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:
+            validate_member_name(property_name)
+        self.__name__ = property_name
+
+        if doc is None and fget is not None:
+            doc = getattr(fget, "__doc__", None)
+        self.fget = fget
+        self.fset = fset
+        self.__doc__ = doc
+
+        self._emits_changed_signal = emits_changed_signal
+        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 getter(self, fget):
+        # TODO Could check the name of fget and do similar to builtin property()
+        if self.__name__ is None:
+            property_name = fget.__name__
+            validate_member_name(property_name)
+            self.__name__ = property_name
+        self.fget = fget
+        return self
+
+    def setter(self, fset):
+        # TODO Could check the name of fset and do similar to builtin property()
+        if self.__name__ is None:
+            property_name = fset.__name__
+            validate_member_name(property_name)
+            self.__name__ = property_name
+        self.fset = fset
+        return self
diff --git a/dbus/service.py b/dbus/service.py
index b92d840..76cc443 100644
--- a/dbus/service.py
+++ b/dbus/service.py
@@ -37,8 +37,10 @@ except ImportError:
 
 import _dbus_bindings
 from dbus import SessionBus, Signature, Struct, validate_bus_name, \
-                 validate_object_path, INTROSPECTABLE_IFACE, ObjectPath
-from dbus.decorators import method, signal
+                 validate_object_path, INTROSPECTABLE_IFACE, \
+                 PROPERTIES_IFACE, ObjectPath
+_builtin_property = property
+from dbus.decorators import method, signal, property
 from dbus.exceptions import DBusException, \
                             NameExistsException, \
                             UnknownMethodException
@@ -296,6 +298,18 @@ def _method_reply_error(connection, message, exception):
 
 class InterfaceType(type):
     def __init__(cls, name, bases, dct):
+        # Verify the user remembered to inherit PropertiesInterface when using properties
+        # TODO Could we add the base class here automagically?
+        # TODO Should we check the signatures here to be ok for a variant.
+        for func in dct.values():
+            if isinstance(func, property):
+                for b in bases:
+                    if issubclass(b, PropertiesInterface):
+                        break
+                else:
+                    raise ValueError("A property defined without base class PropertiesInterface")
+                break
+
         # 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
@@ -320,7 +334,7 @@ class InterfaceType(type):
 
         super(InterfaceType, cls).__init__(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
 
@@ -368,9 +382,99 @@ class InterfaceType(type):
 
         return reflection_data
 
+    def _reflect_on_property(cls, descriptor):
+        signature = descriptor._dbus_signature
+        if signature is None:
+            signature = 'v'
+
+        if descriptor.fget:
+            if descriptor.fset:
+                access = "readwrite"
+            else:
+                access = "read"
+        elif descriptor.fset:
+            access = "write"
+        else:
+            return ""
+        reflection_data = '    <property name="%s" type="%s" access="%s"' % (descriptor.__name__, signature, access)
+        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
+
 class Interface(object):
     __metaclass__ = InterfaceType
 
+def _filter_properties(ifdict):
+    return filter(lambda t: isinstance(t[1], property), ifdict.iteritems())
+
+class PropertiesInterface(Interface):
+    """An object with properties must inherit from this interface."""
+
+    def _get_decorator(self, interface_name, property_name):
+        interfaces = self._dbus_class_table[self.__class__.__module__ + '.' + self.__class__.__name__]
+        if interface_name:
+            interface = interfaces.get(interface_name)
+            if interface is None:
+                raise DBusException("No interface %s on object" % interface_name)
+            prop = interface.get(property_name)
+            if prop is None:
+                raise DBusException("No property %s on object interface %s" % (property_name, interface_name))
+            if not isinstance(prop, property):
+                raise DBusException("Name %s on object interface %s is not a property" % (property_name, interface_name))
+            return prop
+        else:
+            for interface in interfaces.itervalues():
+                prop = interface.get(property_name)
+                if prop and isinstance(prop, property):
+                    return prop
+            raise DBusException("No property %s found" % (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 not readable" % property_name)
+        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 DBusException("Property %s not writable" % 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_class_table[self.__class__.__module__ + '.' + self.__class__.__name__]
+        if interface_name:
+            iface = interfaces.get(interface_name)
+            if iface is None:
+                raise DBusException("No interface %s on object" % interface_name)
+            ifaces = [iface]
+        else:
+            ifaces = interfaces.values()
+        properties = {}
+        for iface in ifaces:
+            for name, prop in _filter_properties(iface):
+                if not prop.fget or name in properties:
+                    continue
+                properties[name] = prop.fget(self)
+        return properties
+
 #: 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()
@@ -479,7 +583,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
@@ -495,7 +599,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
@@ -511,7 +615,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.
@@ -765,6 +869,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'
 
-- 
1.7.3.4