Added comments to new methods

Author: willgebhardt

ngcsimlib/compilers/process.py

@@ -6,7 +6,44 @@
 from ngcsimlib.utils import get_current_context, infer_context, Set_Compartment_Batch
 
 class Process(object):
+    """
+    The process is an alternate method for compiling transitions of models into
+    pure methods. In general this is the preferred method for doing this over
+    the legacy compiler, however it is not required. The Process composes the
+    methods used as they are added to the process meaning that partial compiling
+    is possible for debugging by stopping adding to the chain of transitions in
+    the process.
+
+    The general use case to create a process is as follows
+    myProcess = (Process("myProcess")
+                 >> myFirstComponent.firstTransition
+                 >> myFirstComponent.secondTransition
+                 >> mySecondComponent.firstTransition
+                 >> mySecondComponent.secondTransition)
+
+    However, the adding of new methods does not need to happen only at the
+    initialization of the Process class. The above example can be added to as
+    follows:
+    myProcess >> myThirdComponent.firstTransition
+    myProcess >> myThirdComponent.secondTransition
+
+    In general once all the transition methods are added to the process there
+    are two ways of actually running the transitions defined in the process.
+    The first is through the use of myProcess.pure(current_state, **kwargs) this
+    executes the process as a pure method doing nothing to update the actual
+    state of the model.
+
+    The other method for running a process is through
+    myProcess.execute(**kwargs). This runs the process with the current state of
+    the model. By default, this also does not update the model with the final
+    state, however this can be changed with the flag "update_state".
+    """
     def __init__(self, name):
+        """
+        Creates and empty process using the provided name
+        Args:
+            name: the name of the process (should be unique per context)
+        """
         self._method = None
         self._calls = []
         self.name = name
@@ -19,6 +56,17 @@ def __init__(self, name):
 
     @staticmethod
     def make_process(process_spec, custom_process_klass=None):
+        """
+        Used the in the creation of a process from a json file. Under normal
+        circumstances this is not normally called by the user.
+
+        Args:
+            process_spec: the parsed json object to create a process from
+            custom_process_klass: a custom subclass of a process to build
+
+        Returns: the created process
+
+        """
         if custom_process_klass is None:
             custom_process_klass = Process
         newProcess = custom_process_klass(process_spec['name'])
@@ -32,12 +80,32 @@ def make_process(process_spec, custom_process_klass=None):
 
     @property
     def pure(self):
+        """
+        Returns: The current compile method for the process as a pure method
+        """
         return self._method
 
     def __rshift__(self, other):
+        """
+        Added wrapper for the transition method
+        Args:
+            other: the transition call for the transition method
+
+        Returns: the process for the use of chaining calls
+        """
         return self.transition(other)
 
     def transition(self, transition_call):
+        """
+        Adds the given transition call to the Process. The argument call must be
+        decorated by the @transition decorator.
+
+        Args:
+            transition_call: Transition method to add to the process
+
+        Returns: the process for the use of chaining calls
+
+        """
         self._calls.append({"path": transition_call.__self__.path, "key": transition_call.resolver_key})
         self._needed_contexts.add(infer_context(transition_call.__self__.path))
         new_step, new_args = compile_component(transition_call)
@@ -48,6 +116,23 @@ def transition(self, transition_call):
         return self
 
     def execute(self, update_state=False, **kwargs):
+        """
+        Executes the process using the current state of the model to run. This
+        method has checks to ensure that the process has transitions added to it
+        as well as that all the keyword arguments required by each of the
+        transition call are in the provided keyword arguments. By default, this
+        does not update the final state of the model but that can be toggled
+        with the flag "update_state".
+
+        Args:
+            update_state: Should this method update the final state of the model
+            **kwargs: The required keyword arguments to execute the process
+
+        Returns: the final state of the process regardless of the model is
+        updated to reflect this. Will return null if either of the above checks
+        fail
+
+        """
         if self._method is None:
             warn("Attempting to execute a process with no transition steps")
             return
@@ -61,25 +146,77 @@ def execute(self, update_state=False, **kwargs):
         return state
 
     def as_obj(self):
+        """
+        Returns: Returns this process as an object to be used with json files
+        """
         return {"name": self.name, "class": self.__class__.__name__, "calls": self._calls}
 
     def get_required_args(self):
+        """
+        Returns: The needed arguments for all the transition calls in this
+        process as a set
+        """
         return self._needed_args
 
     def get_required_state(self, include_special_compartments=False):
+        """
+        Gets the required compartments needed to run this process, important to
+        note that if this is going to be used as an argument to the pure method
+        make sure that the "include_special_compartments" flag is set to True so
+        that special compartments found in certain components are visible.
+        Args:
+            include_special_compartments: A flag to show the compartments that
+            denoted as special compartments by ngcsimlib (this is any
+            compartment with * in their name, these are can only be created
+            dynamically)
+
+        Returns: A subset of the model state based on the required compartments
+
+        """
         compound_state = {}
         for context in self._needed_contexts:
             compound_state.update(context.get_current_state(include_special_compartments))
         return compound_state
 
     def updated_modified_state(self, state):
+        """
+        Updates the model with the provided state. It is important to note that
+        only values that are rquired for the execution of this process will be
+        affected by this call. If all compartments need to be updated, view
+        other options found in ngcsimlib.utils.
+        Args:
+            state: The state to update the model with
+        """
         Set_Compartment_Batch({key: value for key, value in state.items() if key in self.get_required_state(include_special_compartments=True)})
 
 
 def transition(output_compartments, builder=False):
+    """
+    The decorator to be paired with the Process call. This method does
+    everything that the now outdated resolver did to ensure backward
+    compatability. This decorator expects to decorate a static method on a
+    class.
+
+    Through normal patterns these decorated method will never be directly called
+    by the end user, but if they are for the purpose of debugging there are a
+    few things to keep in mind. While the process compiler will automatically
+    link values in the component to the different values to be passed into the
+    method that does not exist if they are directly called. In addition, if the
+    method is going to be called at a class level the first value passed into
+    the method must be None to not mess up the internal decoration.
+    Args:
+        output_compartments: The string name of the output compartments the
+        outputs of this method will be assigned to in the order they are output.
+        builder: A boolean flag for if this method is a builder method for the
+        compiler. A builder method is a method that returns the static method to
+        use in the transition.
+
+    Returns: the wrapped method
+
+    """
     def _wrapper(f):
         @wraps(f)
-        def inner(*args, **kwargs):
+        def inner(self, *args, **kwargs):
             return f(*args, **kwargs)
 
 

ngcsimlib/compilers/process_compiler/component_compiler.py

@@ -1,3 +1,13 @@
+"""
+This file contains the methods used to compile methods for the use of Processes.
+The general methodology behind this compiler is that if all transitions can be
+expressed as f(current_state, **kwargs) -> final_state they can then be composed
+together as f(g(current_state, **kwargs) **kwargs) -> final_state. While it is
+technically possible to use the compiler outside the process its intended use
+case is through the process and thus if error occur though other uses support
+may be minimal.
+"""
+
 from ngcsimlib.compilers.process_compiler.op_compiler import compile as op_compile
 from ngcsimlib.compartment import Compartment
 from ngcsimlib.compilers.utils import compose
@@ -11,19 +21,31 @@ def __make_get_param(p, component):
 def __make_get_comp(c, component):
     return lambda current_state, **kwargs: current_state.get(component.__dict__[c].path, None)
 
-def builder(transition_method_to_build):
+def _builder(transition_method_to_build):
     component = transition_method_to_build.__self__
     builder_method = transition_method_to_build.f
     # method, output_compartments, args, params, input_compartments
     return builder_method(component)
 
 
 def compile(transition_method):
+    """
+    This method is the main compile method for the process compiler. Unlike the
+    legacy compiler this compiler is designed to be self-contained and output
+    the methods that are composed together to make the process compiler function
+    Args:
+        transition_method: a method usually component.method that has been
+        decorated by the @transition decorator.
+
+    Returns: the pure compiled method of the form
+    f(current_state, **kwargs) -> final_state)
+
+    """
     composition = None
     component = transition_method.__self__
 
     if transition_method.builder:
-        pure_fn, output, args, parameters, compartments = builder(transition_method)
+        pure_fn, output, args, parameters, compartments = _builder(transition_method)
     else:
 
         pure_fn = transition_method.f

ngcsimlib/compilers/process_compiler/op_compiler.py

@@ -5,13 +5,13 @@ def _make_lambda(s):
 
 def compile(op):
     """
-        compiles the operation down to its execution order
+        compiles root operation down to a single method of
+        f(current_state, **kwargs) -> final_state
 
     Args:
         op: the operation to compile
 
-    Returns:
-        the execution order needed to run this operation compiled
+    Returns: the compiled operation
     """
     arg_methods = []
     for s in op.sources:

ngcsimlib/context.py

@@ -207,6 +207,14 @@ def register_component(self, component, *args, **kwargs):
         self._json_objects['components'][c_path] = obj
 
     def register_process(self, process):
+        """
+        Adds a process to the list of processes to be saved by the context.
+        Unlike with the other saved parts of the context the actual json objects
+        for the processes have to be calculated as time of save since they are
+        constantly changing.
+        Args:
+            process: The process to add
+        """
         self._json_objects['processes'].append(process)
 
     def add_component(self, component):
@@ -476,6 +484,11 @@ def _make_op(self, op_spec):
             dest << obj
 
     def make_process(self, path_to_process_file):
+        """
+        Will load the processes saved in the provided json file into the model
+        Args:
+            path_to_process_file: the path to the saved json file
+        """
         with open(path_to_process_file, 'r') as file:
             process_spec = json.load(file)
             for p in process_spec:
@@ -666,8 +679,27 @@ def _get_state_keys(self, include_special_compartments=False):
         return all_keys
 
     def get_current_state(self, include_special_compartments=False):
+        """
+        Get the current state of the model based on the components found in this
+        context.
+        Args:
+            include_special_compartments: Should this method include
+            compartments denotes as special compartments by ngcsimlib. These are
+            all compartments that include * in their path. (Only creatable
+            dynamically)
+
+        Returns: All the compartments found in this context.
+
+        """
         return Get_Compartment_Batch(self._get_state_keys(include_special_compartments))
 
     def update_current_state(self, state):
+        """
+        Updates the compartments found in this context. While this method can
+        take a model state that includes compartments from other contexts it
+        will only update the compartments found in this context.
+        Args:
+            state: The state to update the model to
+        """
         Set_Compartment_Batch({key: value for key, value in state.items() if key in self._get_state_keys()})