Add motivational blurb to command_stack docstring.

[hooke.git] / hooke / command_stack.py

diff --git a/hooke/command_stack.py b/hooke/command_stack.py
index 6e84a913f1ff9731ad2da74927bb7694361b946d..69bee4ba60e47170b9d711bacc137553f5dd2855 100644 (file)
--- a/hooke/command_stack.py
+++ b/hooke/command_stack.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
+# Copyright (C) 2010-2011 W. Trevor King <wking@drexel.edu>
 #
 # This file is part of Hooke.
 #
@@ -18,6 +18,16 @@
 
 """The ``command_stack`` module provides tools for managing and
 executing stacks of :class:`~hooke.engine.CommandMessage`\s.
+
+In experiment analysis, the goal is to construct a
+:class:`~hooke.command_stack.CommandStack` that starts with your raw
+experiment data and ends with your analyzed results.  These
+:class:`~hooke.command_stack.CommandStack`\s are stored in your
+:class:`~hooke.playlist.FilePlaylist`, so they are saved to disk with
+the analysis results.  This means you will always have a record of
+exactly how you processed the raw data to produce your analysis
+results, which makes it easy to audit your approach or go back and
+reanalyze older data.
 """
 
 import os
@@ -118,24 +128,29 @@ class CommandStack (list):
        <CommandMessage CommandB {param: D}>,
        <CommandMessage CommandC {param: E}>]}>
     >>> import yaml
-    >>> print yaml.dump(c)
+    >>> print yaml.dump(c)  # doctest: +REPORT_UDIFF
     !!python/object/new:hooke.command_stack.CommandStack
     listitems:
     - !!python/object:hooke.engine.CommandMessage
       arguments: {param: A}
       command: CommandA
+      explicit_user_call: true
     - !!python/object:hooke.engine.CommandMessage
       arguments: {param: B}
       command: CommandB
+      explicit_user_call: true
     - !!python/object:hooke.engine.CommandMessage
       arguments: {param: C}
       command: CommandA
+      explicit_user_call: true
     - !!python/object:hooke.engine.CommandMessage
       arguments: {param: D}
       command: CommandB
+      explicit_user_call: true
     - !!python/object:hooke.engine.CommandMessage
       arguments: {param: E}
       command: CommandC
+      explicit_user_call: true
     - !!python/object:hooke.engine.CommandMessage
       arguments:
         param: !!python/object/new:hooke.command_stack.CommandStack
@@ -143,19 +158,25 @@ class CommandStack (list):
           - !!python/object:hooke.engine.CommandMessage
             arguments: {param: A}
             command: CommandA
+            explicit_user_call: true
           - !!python/object:hooke.engine.CommandMessage
             arguments: {param: B}
             command: CommandB
+            explicit_user_call: true
           - !!python/object:hooke.engine.CommandMessage
             arguments: {param: C}
             command: CommandA
+            explicit_user_call: true
           - !!python/object:hooke.engine.CommandMessage
             arguments: {param: D}
             command: CommandB
+            explicit_user_call: true
           - !!python/object:hooke.engine.CommandMessage
             arguments: {param: E}
             command: CommandC
+            explicit_user_call: true
       command: CommandD
+      explicit_user_call: true
     <BLANKLINE>
 
     There is also a convenience function for clearing the stack.
@@ -163,6 +184,20 @@ class CommandStack (list):
     >>> c.clear()
     >>> print [repr(cm) for cm in c]
     []
+
+    YAMLize a curve argument.
+
+    >>> from .curve import Curve
+    >>> c.append(CommandMessage('curve info', {'curve': Curve(path=None)}))
+    >>> print yaml.dump(c)  # doctest: +REPORT_UDIFF
+    !!python/object/new:hooke.command_stack.CommandStack
+    listitems:
+    - !!python/object:hooke.engine.CommandMessage
+      arguments:
+        curve: !!python/object:hooke.curve.Curve {}
+      command: curve info
+      explicit_user_call: true
+    <BLANKLINE>
     """
     def execute(self, hooke, filter=None, stack=False):
         """Execute a stack of commands.
@@ -207,7 +242,7 @@ class FileCommandStack (CommandStack):
 
     def __setstate__(self, state):
         self.name = self.path = None
-        for key,value in state.items:
+        for key,value in state.items():
             setattr(self, key, value)
         self.set_path(state.get('path', None))