Formally define step config, pass to stream.

recipe_engine/recipe_api.py

Index: recipe_engine/recipe_api.py
diff --git a/recipe_engine/recipe_api.py b/recipe_engine/recipe_api.py
index 1bc509a09126d8f2cffd7b23948a8f08305beca4..fef517232a4354792d4b93efbf0850b62dee1280 100644
--- a/recipe_engine/recipe_api.py
+++ b/recipe_engine/recipe_api.py
@@ -4,6 +4,7 @@
 
 from __future__ import absolute_import
 import contextlib
+import collections
 import keyword
 import re
 import types
@@ -18,6 +19,59 @@ from .util import ModuleInjectionSite
 from . import field_composer
 
 
+_StepConfig = collections.namedtuple('StepConfig',

[iannucci, 2016/09/12 19:41:07]

I would name this inner class _StepConfig too. Otherwise type errors may be hard
to debug.

+    ('name', 'cmd', 'cwd', 'env', 'allow_subannotations', 'trigger_specs',
+      'timeout', 'infra_step', 'stdout', 'stderr', 'stdin', 'ok_ret',
+      'step_test_data', 'nest_level'))
+
+class StepConfig(_StepConfig):
+  """

[iannucci, 2016/09/12 19:41:07]

StepConfig is the representation of a raw step as the recipe_engine sees it. You
should use the standard 'step' recipe module, which will construct and pass this
data to the engine for you, instead. The only reason why you would need to worry
about this object is if you're modifying the step module itself.

+  StepConfig parameters:
+    name: name of the step, will appear in buildbots waterfall

[iannucci, 2016/09/12 19:41:07]

let's add types to these, e.g.

name (str): ...

+    cmd: command to run, list of one or more strings

[iannucci, 2016/09/12 19:41:07]

cmd (list): command to run. Acceptable types: str, Path, Placeholder

+    cwd: absolute path to working directory for the command

[iannucci, 2016/09/12 19:41:07]

cwd (Path): ...

+    env: dict with overrides for environment variables

[iannucci, 2016/09/12 19:41:07]

env (dict): overrides for environment variables. Each value is % formatted with
the entire existing os.environ. A value of `None` will remove that envvar from
the environ. e.g.
  {"envvar": "%(envvar)s;%(envvar2)s;extra",
   "delete_this": None,
   "static_value": "something" }

+    allow_subannotations: if True, lets the step emit its own annotations

[iannucci, 2016/09/12 19:41:07]

NOTE: Enabling this can cause some buggy behavior. Please strongly consider
using step_result.presentation instead. If you have questions, please contact
infra-dev@chromium.org.

+    trigger_specs: a list of trigger specifications, see also _trigger_builds.

[iannucci, 2016/09/12 19:41:07]

example schema? Actually... maybe another named tuple?

+    timeout: if not None, a datetime.timedelta for the step timeout.
+    infra_step: if True, this is an infrastructure step.

[iannucci, 2016/09/12 19:41:07]

...... will raise InfraFailure instead of StepFailure.

+    stdout: Path to a file to put step stdout into. If used, stdout won't
+        appear in annotator's stdout (and |allow_subannotations| is
+        ignored).

[iannucci, 2016/09/12 19:41:07]

I think this (and stdin+stderr) actually must be Placeholders

+    stderr: Path to a file to put step stderr into. If used, stderr won't
+        appear in annotator's stderr.
+    stdin: Path to a file to read step stdin from.
+    ok_ret: Allowed return code list.

[iannucci, 2016/09/12 19:41:07]

set of return codes allowed. If the step process returns something not on this
list, it will raise a StepFailure (or InfraFailure if infra_step==True).

+    step_test_data: Possible associated step test data.

[iannucci, 2016/09/12 19:41:07]

step_test_data (func -> recipe_test_api.StepTestData): A factory which returns a
StepTestData object that will be used as the default test data for this step.
The recipe author can override/augment this object in the GenTests function.

+    nest_level: the step's nesting level.

[iannucci, 2016/09/12 19:41:07]

int?

+  """
+
+
+def _make_step_config(**step):
+  """Galvanize a step dictionary into a formal StepConfig."""
+  step_config = StepConfig(
+      name=step.pop('name'),
+      cmd=step.pop('cmd', None),
+      cwd=step.pop('cwd', None),
+      env=step.pop('env', None),
+      allow_subannotations=step.pop('allow_subannotations', False),
+      trigger_specs=step.pop('trigger_specs', ()),
+      timeout=step.pop('timeout', None),
+      infra_step=step.pop('infra_step', False),
+      stdout=step.pop('stdout', None),
+      stderr=step.pop('stderr', None),
+      stdin=step.pop('stdin', None),
+      ok_ret=step.pop('ok_ret', {0}),
+      step_test_data=step.pop('step_test_data', None),
+      nest_level=step.pop('step_nest_level', 0),
+  )
+  if step:
+    unknown_keys = sorted(step.iterkeys())
+    raise KeyError('Unknown step dictionary keys: %s' % (
+        ', '.join(unknown_keys)))
+  return step_config
+
+
 class StepFailure(Exception):
   """
   This is the base class for all step failures.