From 87fabaa7177140cf0a934e0f05a6a4b4295fc1d0 Mon Sep 17 00:00:00 2001
From: Jason Gerard DeRose <jderose@redhat.com>
Date: Tue, 26 Aug 2008 01:07:24 +0000
Subject: [PATCH] 195: Started on docstring for public.DefaultFrom

---
 ipalib/public.py            | 20 ++++++++++++++++++++
 ipalib/tests/test_public.py |  6 ++++++
 2 files changed, 26 insertions(+)

diff --git a/ipalib/public.py b/ipalib/public.py
index d008e9d57..edb4641f9 100644
--- a/ipalib/public.py
+++ b/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)
diff --git a/ipalib/tests/test_public.py b/ipalib/tests/test_public.py
index 37a92cbec..d809b0743 100644
--- a/ipalib/tests/test_public.py
+++ b/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')