ENH: Feature base class in gof.fg

theano/gof/fg.py

@@ -19,6 +19,7 @@ class InconsistencyError(Exception):
     """
     pass
 
+
 class MissingInputError(Exception):
     """
     A symbolic input needed to compute the outputs is missing.
@@ -26,66 +27,80 @@ class MissingInputError(Exception):
     pass
 
 
+class Feature(object):
+    """
+    Base class for FunctionGraph extensions.
 
-class FunctionGraph(utils.object2):
-    """ WRITEME
-    A FunctionGraph represents a subgraph bound by a set of input variables and a
-    set of output variables, ie a subgraph that specifies a theano function.
-    The inputs list should contain all the inputs
-    on which the outputs depend. Variables of type Constant are
-    not counted as inputs.
-
-    The FunctionGraph supports the replace operation which allows to replace a
-    variable in the subgraph by another, e.g. replace (x + x).out by (2
-    * x).out. This is the basis for optimization in theano.
-
-    This class is also reponsible for verifying that a graph is valid
-    (ie, all the dtypes and broadcast patterns are compatible with the
-    way the the Variables are used) and for annotating the Variables with
-    a .clients field that specifies which Apply nodes use the variable.
-    The .clients field combined with the .owner field and the Apply nodes'
-    .inputs field allows the graph to be traversed in both directions.
-
-    It can also be "extended" using function_graph.extend(some_object). See the
-    toolbox and ext modules for common extensions.
-
-    Features added with the`extend` function can handle the following events:
+    See toolbox and ext modules for common extensions.
+    """
 
-    - feature.on_attach(function_graph)
+    def on_attach(self, function_graph):
+        """
         Called by extend. The feature has great freedom in what
         it can do with the function_graph: it may, for example, add methods
         to it dynamically.
+        """
 
-    - feature.on_detach(function_graph)
+    def on_detach(self, function_graph):
+        """
         Called by remove_feature(feature).  Should remove any dynamically-added
         functionality that it installed into the function_graph.
+        """
 
-    - feature.on_import(function_graph, node)*
+    def on_import(self, function_graph, node):
+        """
         Called whenever a node is imported into function_graph, which is
         just before the node is actually connected to the graph.
+        """
 
-    - feature.on_prune(function_graph, node)*
+    def on_prune(self, function_graph, node):
+        """
         Called whenever a node is pruned (removed) from the function_graph,
         after it is disconnected from the graph.
+        """
 
-    - feature.on_change_input(function_graph, node, i, r, new_r, [reason=None])*
+    def on_change_input(self, function_graph, node, i, r, new_r, reason=None):
+        """
         Called whenever node.inputs[i] is changed from r to new_r.
         At the moment the callback is done, the change has already
         taken place.
 
-    - feature.orderings(function_graph)
+        If you raise an exception in this function, the state of the graph
+        might be broken for all intents and purposes.
+        """
+
+    def orderings(self, function_graph):
+        """
         Called by toposort. It should return a dictionary of
         {node: predecessors} where predecessors is a list of
         nodes that should be computed before the key node.
 
-        * If you raise an exception in the functions marked with an
-          asterisk, the state of the graph might be inconsistent.
+        If you raise an exception in this function, the state of the graph
+        might be broken for all intents and purposes.
+        """
+
 
-    - feature.on_setup_node(function_graph, node):
-        WRITEME
+class FunctionGraph(utils.object2):
+    """ WRITEME
+    A FunctionGraph represents a subgraph bound by a set of input variables and a
+    set of output variables, ie a subgraph that specifies a theano function.
+    The inputs list should contain all the inputs
+    on which the outputs depend. Variables of type Constant are
+    not counted as inputs.
+
+    The FunctionGraph supports the replace operation which allows to replace a
+    variable in the subgraph by another, e.g. replace (x + x).out by (2
+    * x).out. This is the basis for optimization in theano.
+
+    This class is also reponsible for verifying that a graph is valid
+    (ie, all the dtypes and broadcast patterns are compatible with the
+    way the the Variables are used) and for annotating the Variables with
+    a .clients field that specifies which Apply nodes use the variable.
+    The .clients field combined with the .owner field and the Apply nodes'
+    .inputs field allows the graph to be traversed in both directions.
 
-    - feature.on_setup_variable(function_graph, variable):
-        WRITEME
+    It can also be "extended" using function_graph.extend(some_object).
+    See Feature above for event types and documentation.
 
     Historically, the FunctionGraph was called an Env. Keep this in mind
     while reading out-of-date documentation, e-mail support threads, etc.