From c5a4e544e1abf11ffa8378a4a03df92e40137cff Mon Sep 17 00:00:00 2001
From: mike <michael.jmontcalm@gmail.com>
Date: Sat, 03 Oct 2009 14:43:29 +0000
Subject: LP 439980 : Redoing addon list comparison, adding comments

---
(limited to 'tutorius/properties.py')

diff --git a/tutorius/properties.py b/tutorius/properties.py
index 6d30a8d..7bfbad0 100644
--- a/tutorius/properties.py
+++ b/tutorius/properties.py
@@ -96,25 +96,40 @@ class TPropContainer(object):
         return object.__getattribute__(self, "_props").keys()
 
     def is_identical(self, otherContainer):
+        """
+        Compare this property container to the other one and returns True only if
+        the every property of the first one can be found in the other container, with
+        the same name and the same value.
+        
+        This is an approximation of identity because we are really looking to see 
+        if this container is at least a subset of the other.
+
+        @param otherContainer The other container that we wish to test for equality.
+        @returns True if every property in the first container can be found with the same
+                    value and the same name in the second container.
+        """
+        # For every property in this container
         for prop in self._props.keys():
             found = False
+            # Try to match it with another property present in the other container
             for otherProp in otherContainer._props.keys():
+                # If we were able to match the name, then we look up the value
                 if prop == otherProp:
                     this_type = getattr(type(self), prop).type
                     other_type = getattr(type(otherContainer), prop).type
                     if this_type != other_type:
                         return False
+                    
+                    # If this is an addon list, then we need to make sure that
+                    # every element of the list is also present in the other list
                     if this_type == "addonlist":
-                        for inner_cont in self._props[prop]:
-                            inner_found = False
-                            for other_inner in otherContainer._props[prop]:
-                                if inner_cont.is_identical(other_inner):
-                                    inner_found = True
-                                    break
-                            if inner_found == False:  
-                                return False
+                        if not self._are_lists_identical(self._props[prop], otherContainer._props[prop]):
+                            return False
                         found = True
                         break
+
+                    # If this is just an embedded / decorated container, then we want to 
+                    # make sure the sub component are identical.
                     elif this_type == "addon":
                         if not self._props[prop].is_identical(otherContainer._props[prop]):
                             return False
@@ -124,10 +139,41 @@ class TPropContainer(object):
                         if self._props[prop]== otherContainer._props[prop]:
                             found = True
                             break
+            # If we arrive here, then we couldn't find any property in the second 
+            # container that matched the current one. We know that the two containers are
+            # not equal.
             if found == False:
                 return False
         return True
     
+    def _are_lists_identical(self, myList, otherList):
+        """
+        Compares two lists of property containers to see if they are identical (
+        they have the same properties
+        
+        @param myList The first list of properties containers
+        @param otherList The second list of properties containers
+        @return True if all of the properties inside the list are identical. False otherwise.
+        """
+        # For each property in the first list,
+        for container in myList:
+            found = False
+            # Attempt to match it with every property in the other list
+            for other_container in otherList:
+                # If the containers are identical,
+                if container.is_identical(other_container):
+                    # We found a matching container. We don't need to search in the
+                    # second list anymore, so we break
+                    found = True
+                    break
+            # In the case the property was not found inside the second list
+            if found == False:  
+                # We know right away that the two lists are not identical
+                return False
+        # If we were able to match each property in the first list, then we
+        # can say the lists are equal.
+        return True
+    
 class TutoriusProperty(object):
     """
     The base class for all actions' properties. The interface is the following :
--
cgit v0.9.1