195: Started on docstring for public.DefaultFrom

ipalib/public.py

@@ -41,8 +41,28 @@ def is_rule(obj):
 
 
 class DefaultFrom(plugable.ReadOnly):
+    """
+    Derives a default for one value using other supplied values.
+
+    Here is an example:
+
+    >>> df = DefaultFrom(lambda f, l: f[0] + l[0], 'first', 'last')
+    >>> df(first='John', last='Doe') # Both keys
+    'JD'
+    >>> df() is None # Returns None if any key is missing
+    True
+    >>> df(first='John', middle='Q') is None # Still returns None
+    True
+    """
     def __init__(self, callback, *keys):
+        """
+        :param callback: The callable to call when all ``keys`` are present.
+        :param keys: The keys used to map from keyword to position arguments.
+        """
         assert callable(callback), 'not a callable: %r' % callback
+        assert len(keys) > 0, 'must have at least one key'
+        for key in keys:
+            assert type(key) is str, 'not an str: %r' % key
         self.callback = callback
         self.keys = keys
         lock(self)

ipalib/tests/test_public.py

@@ -73,6 +73,9 @@ class test_DefaltFrom(ClassChecker):
         assert self.cls.__bases__ == (plugable.ReadOnly,)
 
     def test_init(self):
+        """
+        Tests the `public.DefaultFrom.__init__` method.
+        """
         def callback(*args):
             return args
         keys = ('givenname', 'sn')
@@ -81,6 +84,9 @@ class test_DefaltFrom(ClassChecker):
         assert read_only(o, 'keys') == keys
 
     def test_call(self):
+        """
+        Tests the `public.DefaultFrom.__call__` method.
+        """
         def callback(givenname, sn):
             return givenname[0] + sn[0]
         keys = ('givenname', 'sn')