Add type decorators for XML generation

The decorators add information about the types a method or property can accept
or return. The XML generator can optionally require that every method and
property has the information defined.

Alternatively it adds the possibility to use annotations instead, but that is
a Python 3 only feature.

Author: xZise

doc/tutorial.rst

@@ -238,24 +238,27 @@ To prepare a class for exporting on the Bus, provide the dbus introspection XML
 in a ''dbus'' class property or in its ''docstring''. For example::
 
     from pydbus.generic import signal
-    from pydbus.xml_generator import interface, signalled, attach_introspection_xml
+    from pydbus.strong_typing import typed_method, typed_property
+    from pydbus.xml_generator import interface, emits_changed_signal, attach_introspection_xml
 
     @attach_introspection_xml
     @interface("net.lew21.pydbus.TutorialExample")
     class Example(object):
 
+      @typed_method(("s", ), "s")
       def EchoString(self, s):
         """returns whatever is passed to it"""
         return s
 
       def __init__(self):
         self._someProperty = "initial value"
 
-      @property
+      @emits_changed_signal
+      @typed_property("s")
       def SomeProperty(self):
         return self._someProperty
 
-      @signalled(SomeProperty)
+      @SomeProperty.setter
       def SomeProperty(self, value):
         self._someProperty = value
         self.PropertiesChanged("net.lew21.pydbus.TutorialExample", {"SomeProperty": self.SomeProperty}, [])

pydbus/strong_typing.py

@@ -0,0 +1,36 @@
+"""Decorators for methods and properties to strongly typed the values."""
+import inspect
+
+from pydbus.xml_generator import get_arguments
+
+
+def typed_property(value_type):
+	"""
+	Decorate a function as a dbus property getter.
+
+	It alreay makes the method a property so another `@property` decorator may
+	not be used.
+	"""
+	def decorate(func):
+		func.prop_type = value_type
+		return property(func)
+	return decorate
+
+
+def typed_method(argument_types, return_type):
+	"""
+	Decorate a function as a dbus method.
+
+	Parameters
+	----------
+	argument_types : tuple
+		Required argument types for each argument except the first
+	return_type : string
+		Type of the returned value, must be None if it returns nothing
+	"""
+	def decorate(func):
+		func.arg_types = argument_types
+		func.ret_type = return_type
+		get_arguments(func)
+		return func
+	return decorate

pydbus/tests/strong_typing.py

@@ -0,0 +1,47 @@
+from pydbus.generic import signal
+from pydbus.strong_typing import typed_method, typed_property
+
+
+def test_signal():
+	@signal
+	@typed_method(("s", ), None)
+	def dummy(self, parameter):
+		pass
+
+	assert hasattr(dummy, 'method')
+	assert dummy.method.arg_types == ("s", )
+	assert dummy.method.ret_type is None
+
+
+def test_count_off():
+	"""Test what happens if to many or to few types are defined in methods."""
+	try:
+		@typed_method(("s", "i", "o"), None)
+		def dummy(self, parameter):
+			pass
+
+		assert False
+	except ValueError as e:
+		assert str(e) == "Number of argument types (3) differs from the number of parameters (1) in function 'dummy'"
+
+	try:
+		@typed_method(("s", "i"), "o")
+		def dummy(self, parameter):
+			pass
+
+		assert False
+	except ValueError as e:
+		assert str(e) == "Number of argument types (2) differs from the number of parameters (1) in function 'dummy'"
+
+	try:
+		@typed_method(tuple(), None)
+		def dummy(self, parameter):
+			pass
+
+		assert False
+	except ValueError as e:
+		assert str(e) == "Number of argument types (0) differs from the number of parameters (1) in function 'dummy'"
+
+
+test_signal()
+test_count_off()

pydbus/tests/xml_generator.py

@@ -1,5 +1,8 @@
+from sys import version_info
+
 from pydbus import xml_generator
 from pydbus.generic import signal
+from pydbus.strong_typing import typed_method, typed_property
 
 
 @xml_generator.attach_introspection_xml
@@ -9,11 +12,20 @@ class Example(object):
 	def __init__(self):
 		self._rw = 42
 
+	@typed_method(("s", ), "i")
 	def OneParamReturn(self, parameter):
 		return 42
 
+	@typed_method(("s", ), None)
+	def OneParamNoReturn(self, parameter):
+		pass
+
+	@typed_property("i")
+	def ReadProperty(self):
+		return 42
+
 	@xml_generator.emits_changed_signal
-	@property
+	@typed_property("i")
 	def RwProperty(self):
 		return self._rw
 
@@ -53,20 +65,43 @@ def arguments(self, arg1, arg2):
 	def ctx_argument(self, arg, dbus_context):
 		pass
 
-	assert xml_generator.get_arguments(nothing) == []
-	assert xml_generator.get_arguments(arguments) == ["arg1", "arg2"]
-	assert xml_generator.get_arguments(ctx_argument) == ["arg"]
+	@typed_method(tuple(), None)
+	def typed_nothing(self):
+		pass
+
+	@typed_method(("s", "i"), None)
+	def typed_arguments(self, arg1, arg2):
+		pass
+
+	assert xml_generator.get_arguments(nothing) == (tuple(), None)
+	assert xml_generator.get_arguments(arguments) == ((("arg1", None), ("arg2", None)), None)
+	assert xml_generator.get_arguments(ctx_argument) == ((("arg", None), ), None)
+
+	assert xml_generator.get_arguments(typed_nothing) == (tuple(), None)
+	assert xml_generator.get_arguments(typed_arguments) == ((("arg1", "s"), ("arg2", "i")), None)
 
 
 def test_valid():
 	assert not hasattr(Example.OneParamReturn, "dbus_interface")
+	assert Example.OneParamReturn.arg_types == ("s", )
+	assert Example.OneParamReturn.ret_type == "i"
+
+	assert not hasattr(Example.OneParamNoReturn, "dbus_interface")
+	assert Example.OneParamNoReturn.arg_types == ("s", )
+	assert Example.OneParamNoReturn.ret_type is None
+
+	assert not hasattr(Example.ReadProperty, "dbus_interface")
+	assert isinstance(Example.ReadProperty, property)
+	assert Example.ReadProperty.fget.prop_type == "i"
+	assert Example.ReadProperty.fset is None
 
 	assert not hasattr(Example.RwProperty, "dbus_interface")
 	assert isinstance(Example.RwProperty, property)
 	assert Example.RwProperty.fget.causes_signal is True
+	assert Example.RwProperty.fget.prop_type == "i"
 	assert Example.RwProperty.fset is not None
 
-	assert Example.dbus == b'<node><interface name="net.lvht.Foo1"><method name="OneParamReturn"><arg direction="in" name="parameter" /></method><property access="readwrite" name="RwProperty"><annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true" /></property></interface></node>'
+	assert Example.dbus == b'<node><interface name="net.lvht.Foo1"><method name="OneParamNoReturn"><arg direction="in" name="parameter" type="s" /></method><method name="OneParamReturn"><arg direction="in" name="parameter" type="s" /><arg direction="out" name="return" type="i" /></method><property access="read" name="ReadProperty" type="i" /><property access="readwrite" name="RwProperty" type="i"><annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true" /></property></interface></node>'
 
 
 def test_multiple_interfaces():
@@ -89,8 +124,13 @@ def Dummy(self, param=None):
 	except ValueError as e:
 		assert str(e) == "Default values are not allowed for method 'Dummy'"
 
-	E_NO_VARGS = (
+	if version_info[0] == 2:
+		E_NO_VARGS = (
 			"Variable arguments arguments are not allowed for method 'Dummy'")
+	else:
+		E_NO_VARGS = E_NO_KWARGS = (
+			"Variable arguments or keyword only arguments are not allowed for "
+			"method 'Dummy'")
 
 	def Dummy(self, *vargs):
 		pass
@@ -111,7 +151,42 @@ def Dummy(self, **kwargs):
 		assert str(e) == E_NO_VARGS
 
 
+def test_require_strong_typing():
+	try:
+		@xml_generator.attach_introspection_xml(True)
+		@xml_generator.interface("net.lvht.Foo1")
+		class Example(object):
+
+			def Dummy(self, param):
+				pass
+	except ValueError as e:
+		assert str(e) == "No argument types defined for method 'Dummy'"
+
+	@xml_generator.attach_introspection_xml(True)
+	@xml_generator.interface("net.lvht.Foo1")
+	class RequiredExample(object):
+
+		@typed_method(("s", ), None)
+		def Dummy(self, param):
+			pass
+
+	assert RequiredExample.Dummy.arg_types == ("s", )
+	assert RequiredExample.Dummy.ret_type is None
+
+	@xml_generator.attach_introspection_xml(False)
+	@xml_generator.interface("net.lvht.Foo1")
+	class OptionalExample(object):
+
+		@typed_method(("s", ), None)
+		def Dummy(self, param):
+			pass
+
+	assert OptionalExample.dbus == RequiredExample.dbus
+	assert OptionalExample is not RequiredExample
+
+
 test_get_arguments()
 test_valid()
 test_multiple_interfaces()
 test_invalid_function()
+test_require_strong_typing()