Cleanup 'factory.declarations'.

Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>

1 files changed, 91 insertions, 19 deletions

diff --git a/factory/containers.py b/factory/containers.py
index d52ca05..e280162 100644
--- a/factory/containers.py
+++ b/factory/containers.py
@@ -20,9 +20,12 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-from declarations import OrderedDeclaration, SubFactory
 
+from factory import declarations
 
+
+#: String for splitting an attribute name into a
+#: (subfactory_name, subfactory_field) tuple.
 ATTR_SPLITTER = '__'
 
 
@@ -31,29 +34,48 @@ class CyclicDefinitionError(Exception):
 
 
 class LazyStub(object):
-    """A generic container that allows for getting but not setting of attributes.
+    """A generic container that only allows getting attributes.
+
+    Attributes are set at instantiation time, values are computed lazily.
 
-    Attributes are set at initialization time."""
+    Attributes:
+        __initialized (bool): whether this object's __init__ as run. If set,
+            setting any attribute will be prevented.
+        __attrs (dict): maps attribute name to their declaration
+        __values (dict): maps attribute name to computed value
+        __pending (str list): names of the attributes whose value is being
+            computed. This allows to detect cyclic lazy attribute definition.
+    """
 
-    initialized = False
+    __initialized = False
 
     def __init__(self, attrs):
         self.__attrs = attrs
         self.__values = {}
         self.__pending = []
-        self.initialized = True
+        self.__initialized = True
 
     def __fill__(self):
+        """Fill this LazyStub, computing values of all defined attributes.
+
+        Retunrs:
+            dict: map of attribute name => computed value
+        """
         res = {}
         for attr in self.__attrs:
             res[attr] = getattr(self, attr)
         return res
 
     def __getattr__(self, name):
+        """Retrieve an attribute's value.
+
+        This will compute it if needed, unless it is already on the list of
+        attributes being computed.
+        """
         if name in self.__pending:
             raise CyclicDefinitionError(
-                    "Cyclic lazy attribute definition for %s. Current cycle is %r." %
-                    (name, self.__pending))
+                "Cyclic lazy attribute definition for %s; cycle found in %r." %
+                (name, self.__pending))
         elif name in self.__values:
             return self.__values[name]
         elif name in self.__attrs:
@@ -66,17 +88,21 @@ class LazyStub(object):
             return val
         else:
             raise AttributeError(
-                "The parameter %s is unknown. Evaluated attributes are %r, definitions are %r." % (name, self.__values, self.__attrs))
+                "The parameter %s is unknown. Evaluated attributes are %r, "
+                "definitions are %r." % (name, self.__values, self.__attrs))
 
 
     def __setattr__(self, name, value):
-        if not self.initialized:
+        """Prevent setting attributes once __init__ is done."""
+        if not self.__initialized:
             return super(LazyStub, self).__setattr__(name, value)
         else:
             raise AttributeError('Setting of object attributes is not allowed')
 
 
 class DeclarationDict(dict):
+    """Slightly extended dict to work with OrderedDeclaration."""
+
     def update_with_public(self, d):
         """Updates the DeclarationDict from a class definition dict.
 
@@ -87,13 +113,18 @@ class DeclarationDict(dict):
         """
         remaining = {}
         for k, v in d.iteritems():
-            if k.startswith('_') and not isinstance(v, OrderedDeclaration):
+            if k.startswith('_') and not isinstance(v, declarations.OrderedDeclaration):
                 remaining[k] = v
             else:
                 self[k] = v
         return remaining
 
     def copy(self, extra=None):
+        """Copy this DeclarationDict into another one, including extra values.
+
+        Args:
+            extra (dict): additional attributes to include in the copy.
+        """
         new = DeclarationDict()
         new.update(self)
         if extra:
@@ -102,12 +133,25 @@ class DeclarationDict(dict):
 
 
 class LazyValue(object):
+    """Some kind of "lazy evaluating" object."""
+
     def evaluate(self, obj):
+        """Compute the value, using the given object."""
         raise NotImplementedError("This is an abstract method.")
 
 
 class SubFactoryWrapper(LazyValue):
-    def __init__(self, subfactory, subfields, create):
+    """Lazy wrapper around a SubFactory.
+
+    Attributes:
+        subfactory (declarations.SubFactory): the SubFactory being wrapped
+        subfields (DeclarationDict): Default values to override when evaluating
+            the SubFactory
+        create (bool): whether to 'create' or 'build' the SubFactory.
+    """
+
+    def __init__(self, subfactory, subfields, create, *args, **kwargs):
+        super(SubFactoryWrapper, self).__init__(*args, **kwargs)
         self.subfactory = subfactory
         self.subfields = subfields
         self.create = create
@@ -117,7 +161,17 @@ class SubFactoryWrapper(LazyValue):
 
 
 class OrderedDeclarationWrapper(LazyValue):
-    def __init__(self, declaration, sequence):
+    """Lazy wrapper around an OrderedDeclaration.
+
+    Attributes:
+        declaration (declarations.OrderedDeclaration): the OrderedDeclaration
+            being wrapped
+        sequence (int): the sequence counter to use when evaluatin the
+            declaration
+    """
+
+    def __init__(self, declaration, sequence, *args, **kwargs):
+        super(OrderedDeclarationWrapper, self).__init__(*args, **kwargs)
         self.declaration = declaration
         self.sequence = sequence
 
@@ -126,9 +180,19 @@ class OrderedDeclarationWrapper(LazyValue):
 
 
 class AttributeBuilder(object):
-    """Builds attributes from a factory and extra data."""
+    """Builds attributes from a factory and extra data.
+
+    Attributes:
+        factory (base.Factory): the Factory for which attributes are being
+            built
+        _attrs (DeclarationDict): the attribute declarations for the factory
+        _subfields (dict): dict mapping an attribute name to a dict of
+            overridden default values for the related SubFactory.
+    """
+
+    def __init__(self, factory, extra=None, *args, **kwargs):
+        super(AttributeBuilder, self).__init__(*args, **kwargs)
 
-    def __init__(self, factory, extra=None):
         if not extra:
             extra = {}
         self.factory = factory
@@ -136,30 +200,38 @@ class AttributeBuilder(object):
         self._subfields = self._extract_subfields()
 
     def _extract_subfields(self):
+        """Extract the subfields from the declarations list."""
         sub_fields = {}
         for key in list(self._attrs):
             if ATTR_SPLITTER in key:
+                # Trying to define a default of a subfactory
                 cls_name, attr_name = key.split(ATTR_SPLITTER, 1)
                 if cls_name in self._attrs:
                     sub_fields.setdefault(cls_name, {})[attr_name] = self._attrs.pop(key)
         return sub_fields
 
     def build(self, create):
+        """Build a dictionary of attributes.
+
+        Args:
+            create (bool): whether to 'build' or 'create' the subfactories.
+        """
+        # Setup factory sequence.
         self.factory.sequence = self.factory._generate_next_sequence()
 
+        # Parse attribute declarations, wrapping SubFactory and
+        # OrderedDeclaration.
         wrapped_attrs = {}
         for k, v in self._attrs.iteritems():
-            if isinstance(v, SubFactory):
+            if isinstance(v, declarations.SubFactory):
                 v = SubFactoryWrapper(v, self._subfields.get(k, {}), create)
-            elif isinstance(v, OrderedDeclaration):
+            elif isinstance(v, declarations.OrderedDeclaration):
                 v = OrderedDeclarationWrapper(v, self.factory.sequence)
             wrapped_attrs[k] = v
 
-        stub = LazyStub(wrapped_attrs)
-        return stub.__fill__()
+        return LazyStub(wrapped_attrs).__fill__()
 
 
 class StubObject(object):
     """A generic container."""
-
     pass