Rename things, comment others

A pass at using "workflow_class", not "workflow", when this is what we
use. (We unfortunately can't use "workflow_type" since it's a term of
art on SWF).

Also, add some [PEP 484](https://www.python.org/dev/peps/pep-0484/) type
hints.

Signed-off-by: Yves Bastide <yves@botify.com>

Author: ybastide

simpleflow/command.py

@@ -26,16 +26,21 @@
 from simpleflow.utils import json_dumps
 from simpleflow import __version__
 
+if False:
+    from typing import Text, Type
+    from simpleflow import Workflow
+    from swf.models import WorkflowType
+
+
 logger = logging.getLogger(__name__)
 
 
 def get_workflow(clspath):
+    # type: (Text) -> Type[Workflow]
     """
     Import a workflow class.
     :param clspath: class path
-    :type clspath: str
     :return:
-    :rtype: simpleflow.workflow.Workflow
     """
     modname, clsname = clspath.rsplit('.', 1)
     module = __import__(modname, fromlist=['*'])
@@ -78,19 +83,17 @@ def cli(ctx, header, format):
     ctx.params['header'] = header
 
 
-def get_workflow_type(domain_name, workflow):
+def get_workflow_type(domain_name, workflow_class):
+    # type: (Text, Type[Workflow]) -> WorkflowType
     """
-    Get or create the given workflow.
+    Get or create the given workflow on SWF.
     :param domain_name:
-    :type domain_name: str
-    :param workflow:
-    :type workflow: simpleflow.workflow.Workflow
+    :param workflow_class:
     :return:
-    :rtype: swf.models.WorkflowType
     """
     domain = swf.models.Domain(domain_name)
     query = swf.querysets.WorkflowTypeQuerySet(domain)
-    return query.get_or_create(workflow.name, workflow.version)
+    return query.get_or_create(workflow_class.name, workflow_class.version)
 
 
 def load_input(input_fp):
@@ -164,24 +167,24 @@ def start_workflow(workflow,
                    input,
                    input_file,
                    local):
-    workflow_definition = get_workflow(workflow)
+    workflow_class = get_workflow(workflow)
 
     wf_input = get_or_load_input(input_file, input)
 
     if local:
         from .local import Executor
 
-        Executor(workflow_definition).run(wf_input)
+        Executor(workflow_class).run(wf_input)
 
         return
 
     if not domain:
         raise ValueError('*domain* must be set when not running in local mode')
 
-    workflow_type = get_workflow_type(domain, workflow_definition)
+    workflow_type = get_workflow_type(domain, workflow_class)
     execution = workflow_type.start_execution(
         workflow_id=workflow_id,
-        task_list=task_list or workflow_definition.task_list,
+        task_list=task_list or workflow_class.task_list,
         execution_timeout=execution_timeout,
         input=wf_input,
         tag_list=tags,

simpleflow/executor.py

@@ -3,6 +3,11 @@
 
 from ._decorators import deprecated
 
+
+if False:
+    from typing import Text, Type
+    from simpleflow import Workflow
+
 __all__ = ['Executor']
 
 
@@ -33,7 +38,8 @@ class Executor(object):
     """
     __metaclass__ = abc.ABCMeta
 
-    def __init__(self, workflow):
+    def __init__(self, workflow_class):
+        # type: (Type[Workflow]) -> None
         """
         Binds the workflow's definition.
 
@@ -42,7 +48,7 @@ def __init__(self, workflow):
         as a program, the workflow, and an interpreter, the executor.
 
         """
-        self._workflow = workflow(self)
+        self._workflow = workflow_class(self)
 
     @property
     def workflow(self):

simpleflow/local/executor.py

@@ -22,8 +22,8 @@ class Executor(executor.Executor):
     Executes all tasks synchronously in a single local process.
 
     """
-    def __init__(self, workflow):
-        super(Executor, self).__init__(workflow)
+    def __init__(self, workflow_class):
+        super(Executor, self).__init__(workflow_class)
         self.nb_activities = 0
         self.signals_sent = set()
 
@@ -111,6 +111,8 @@ def run(self, input=None):
         self.before_replay()
         result = self.run_workflow(*args, **kwargs)
 
+        # Hack: self._history must be available to the callback as a
+        # simpleflow.history.History, not a swf.models.history.builder.History
         self._history = History(self._history)
         self._history.parse()
         self.after_replay()

simpleflow/swf/executor.py

@@ -161,9 +161,9 @@ class Executor(executor.Executor):
 
     """
 
-    def __init__(self, domain, workflow, task_list=None, repair_with=None,
+    def __init__(self, domain, workflow_class, task_list=None, repair_with=None,
                  force_activities=None):
-        super(Executor, self).__init__(workflow)
+        super(Executor, self).__init__(workflow_class)
         self._history = None
         self._execution_context = {}
         self.domain = domain