doc

theano/gof/fg.py

@@ -449,21 +449,29 @@ class FunctionGraph(utils.object2):
         Adds a gof.toolbox.Feature to this function_graph
         and triggers its on_attach callback
         """
+
+        # Filter out literally identical features
         if feature in self._features:
             return # the feature is already present
 
-        #it would be nice if we could require a specific class instead of
-        #a "workalike" so we could do actual error checking
-        #if not isinstance(feature, toolbox.Feature):
-        #    raise TypeError("Expected gof.toolbox.Feature instance, got "+\
-        #            str(type(feature)))
-
+        # Filter out functionally identical features.
+        # Features may use their on_attach method to raise
+        # toolbox.AlreadyThere if they detect that some
+        # installed feature does the same thing already
         attach = getattr(feature, 'on_attach', None)
         if attach is not None:
             try:
                 attach(self)
             except toolbox.AlreadyThere:
                 return
+
+        #it would be nice if we could require a specific class instead of
+        #a "workalike" so we could do actual error checking
+        #if not isinstance(feature, toolbox.Feature):
+        #    raise TypeError("Expected gof.toolbox.Feature instance, got "+\
+        #            str(type(feature)))
+
+        # Add the feature
         self._features.append(feature)
 
     def remove_feature(self, feature):

theano/gof/toolbox.py

@@ -7,6 +7,9 @@ import graph
 
 
 class AlreadyThere(Exception):
+    """Raised by a Feature's on_attach callback method if the FunctionGraph
+    attempting to attach the feature already has a functionally identical
+    feature."""
     pass
 
 
@@ -32,13 +35,18 @@ class Feature(object):
 
     def on_attach(self, function_graph):
         """
-        Called by FunctionGraph.attach_feature, the method that attaches the feature
-        to the FunctionGraph. Since this is called after the FunctionGraph
-        is initially populated, this is where you should run checks on the
-        initial contents of the FunctionGraph.
-        The feature has great freedom in what
-        it can do with the function_graph: it may, for example, add methods
-        to it dynamically.
+        Called by FunctionGraph.attach_feature, the method that attaches
+        the feature to the FunctionGraph. Since this is called after the
+        FunctionGraph is initially populated, this is where you should
+        run checks on the initial contents of the FunctionGraph.
+
+        The on_attach method may raise the AlreadyThere exception to cancel
+        the attach operation if it detects that another Feature instance
+        implementing the same functionality is already atttached to the
+        FunctionGraph.
+
+        The feature has great freedom in what it can do with the
+        function_graph: it may, for example, add methods to it dynamically.
         """
 
     def on_detach(self, function_graph):