Add better documentation, trigger namedtuple.

recipe_engine/step_runner.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.
 
 import StringIO
 import collections
 import contextlib
 import datetime
 import json
 import os
@@ skipping 336 matching lines @@
         for line in buf.get_buffered():
           outstreams[pipe].write_line(line)
     else:
       proc.wait(timeout)
 
     return proc.returncode
 
   def _trigger_builds(self, step, trigger_specs):
     assert trigger_specs is not None
     for trig in trigger_specs:
-      builder_name = trig.get('builder_name')
+      builder_name = trig.builder_name
       if not builder_name:
         raise ValueError('Trigger spec: builder_name is not set')
 
-      changes = trig.get('buildbot_changes', [])
+      changes = trig.buildbot_changes or []
       assert isinstance(changes, list), 'buildbot_changes must be a list'
       changes = map(self._normalize_change, changes)
 
       step.trigger(json.dumps({
           'builderNames': [builder_name],
-          'bucket': trig.get('bucket'),
+          'bucket': trig.bucket,
           'changes': changes,
           # if True and triggering fails asynchronously, fail entire build.
-          'critical': trig.get('critical', True),
-          'properties': trig.get('properties'),
-          'tags': trig.get('tags'),
+          'critical': trig.critical,
+          'properties': trig.properties,
+          'tags': trig.tags,
       }, sort_keys=True))
 
   def _normalize_change(self, change):
     assert isinstance(change, dict), 'Change is not a dict'
     change = change.copy()
 
     # Convert when_timestamp to UNIX timestamp.
     when = change.get('when_timestamp')
     if isinstance(when, datetime.datetime):
       when = calendar.timegm(when.utctimetuple())
       change['when_timestamp'] = when
 
     return change
 
 
 class SimulationStepRunner(StepRunner):
   """Pretends to run steps, instead recording what would have been run.
 
   This is the main workhorse of recipes.py simulation_test.  Returns the log of
   steps that would have been run in steps_ran.  Uses test_data to mock return
   values.
   """
 
-  # List of attributes in a recipe_api.StepConfig to omit when rendering
-  # step history.
-  _STEP_CONFIG_RENDER_BLACKLIST = set((
-      'nest_level',
-      'ok_ret',
-      'infra_step',
-      'step_test_data',
-  ))
-
   def __init__(self, stream_engine, test_data, annotator):
     self._test_data = test_data
     self._stream_engine = stream_engine
     self._annotator = annotator
     self._step_history = collections.OrderedDict()
 
   @property
   def stream_engine(self):
     return self._stream_engine
 
@@ skipping 17 matching lines @@
         # Install a placeholder for order.
         self._step_history[rendered_step.config.name] = None
         return construct_step_result(rendered_step, step_test.retcode)
 
       def finalize(inner):
         rs = rendered_step
 
         # note that '~' sorts after 'z' so that this will be last on each
         # step. also use _step to get access to the mutable step
         # dictionary.
-        buf = self._annotator.step_buffer(rendered_step.config.name)
+        buf = self._annotator.step_buffer(rs.config.name)
         lines = filter(None, buf.getvalue()).splitlines()
         lines = [stream.encode_str(x) for x in lines]
         if lines:
           # This magically floats into step_history, which we have already
           # added step_config to.
           rs = rs._replace(followup_annotations=lines)
         step_stream.close()
-        self._step_history[rendered_step.config.name] = rs
+        self._step_history[rs.config.name] = rs
 
       @property
       def stream(inner):
         return step_stream
 
     return ReturnOpenStep()
 
   def run_recipe(self, universe, recipe, properties):
     return self._test_data.depend_on_data.pop(types.freeze((recipe, properties),))
 
   @contextlib.contextmanager
   def run_context(self):
     try:
       yield
     except Exception as ex:
       with self._test_data.should_raise_exception(ex) as should_raise:
         if should_raise:
           raise
 
     assert self._test_data.consumed, (
         "Unconsumed test data for steps: %s, (exception %s)" % (
             self._test_data.step_data.keys(),
             self._test_data.expected_exception))
 
   def _rendered_step_to_dict(self, rs):
-    d = dict((k, v) for k, v in rs.config._asdict().iteritems()
-             if v and k not in self._STEP_CONFIG_RENDER_BLACKLIST)
+    d = rs.config.render_to_dict()
     if rs.followup_annotations:
       d['~followup_annotations'] = rs.followup_annotations
     return d
 
   @property
   def steps_ran(self):
     return [self._rendered_step_to_dict(rs)
             for rs in self._step_history.itervalues()]
 
 
@@ skipping 192 matching lines @@
   supplied command, and only uses the |env| kwarg for modifying the environment
   of the child process.
   """
   saved_path = os.environ['PATH']
   try:
     if path is not None:
       os.environ['PATH'] = path
     yield
   finally:
     os.environ['PATH'] = saved_path