Formally define step config, pass to stream.

recipe_engine/recipe_api.py

 # Copyright 2016 The LUCI Authors. All rights reserved.
 # Use of this source code is governed under the Apache License, Version 2.0
 # that can be found in the LICENSE file.
 
 from __future__ import absolute_import
 import contextlib
+import collections
 import keyword
 import re
 import types
 
 from functools import wraps
 
 from .recipe_test_api import DisabledTestData, ModuleTestData
 from .config import Single
 
 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.
 
   Raising a StepFailure counts as 'running a step' for the purpose of
   infer_composite_step's logic.
   """
   def __init__(self, name_or_reason, result=None):
     _STEP_CONTEXT['ran_step'][0] = True
     if result:
@@ skipping 633 matching lines @@
     """
     Gets the BoundProperty version of this Property. Requires a name.
     """
     return BoundProperty(
         self._default, self.help, self.kind, name, property_type, module,
         self.param_name)
 
 class UndefinedPropertyException(TypeError):
   pass