step: expose get_context() to get the context object

recipe_modules/step/api.py

 # Copyright 2013 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 contextlib
 import datetime
 
 from recipe_engine import recipe_api
 
 
@@ skipping 56 matching lines @@
         raise
       finally:
         if result.json.output:
           new_step_text = result.json.output['step_text']
           api.step.active_result.presentation.step_text = new_step_text
     """
     return self.step_client.previous_step_result()
 
   @property
   def context(self):
-    """ See recipe_api.py for docs. """
+    """Returns a context manager which can set values applying to all steps
+    within the block.
+
+    Example usage:
+      with api.step.context({'cwd': api.path['checkout']}):
+        api.step(...)
+
+    Valid keys:
+      cwd - working directory

[iannucci, 2017/02/01 17:59:10]

(Path object from api.path)

+      env - environment variables

[iannucci, 2017/02/01 17:59:10]

({var -> pattern})

+      infra_step - whether the step failure should be marked as infra failure

[iannucci, 2017/02/01 17:59:10]

(bool)

+      name - step name

[iannucci, 2017/02/01 17:59:10]

(str)

Isn't this the step name prefix?

+      nest_level - level of step nesting (see api.step.nest)

[iannucci, 2017/02/01 17:59:10]

I would remove this one; users should use api.step.nest instead, I think?

+
+    See recipe_api.py for more info.
+    """
     return recipe_api.context
 
+  def get_from_context(self, key, default=None):
+    """Returns |key|'s value from context if present, otherwise |default|."""
+    return recipe_api._STEP_CONTEXT.get(key, default)
+
+  def combine_with_context(self, key, value):
+    """Combines |value| with the value for |key| in current context, if any.
+    Returns the combined value."""
+    return recipe_api._STEP_CONTEXT.get_with_context(key, value)
+
   @contextlib.contextmanager
   def nest(self, name):
     """Nest is the high-level interface to annotated hierarchical steps.
 
     Calling
 
         with api.step.nest(<name>):
           ...
 
     will generate a dummy step and implicitly create a new context (as
@@ skipping 74 matching lines @@
       ok_ret = set(range(-256, 256))
 
     if cmd is not None:
       command = list(wrapper)
       command += cmd
       kwargs['cmd'] = command
 
     kwargs['timeout'] = timeout
     kwargs['ok_ret'] = ok_ret
 
-    # Obtain information from composite step parent.
-    compositor = recipe_api._STEP_CONTEXT
-
     # Calculate our full step name. If a step already has that name, add an
     # index to the end of it.
     #
     # Note that another step could exist with that index already added to it
     # by the user. If this happens, we'll continue appending indexes until we
     # have a unique step name.
     while True:
-      full_name = compositor.get_with_context('name', name)
+      full_name = self.combine_with_context('name', name)
       if full_name not in self._seen_steps:
         break
 
       step_count = self._step_names.setdefault(full_name, 1) + 1
       self._step_names[full_name] = step_count
       name = "%s (%d)" % (name, step_count)
     self._seen_steps.add(full_name)
 
     if 'cwd' not in kwargs:
-      kwargs['cwd'] = compositor.get('cwd')
-    kwargs['env'] = compositor.get_with_context('env', kwargs.get('env', {}))
-    kwargs['infra_step'] = compositor.get_with_context(
+      kwargs['cwd'] = self.get_from_context('cwd')
+    kwargs['env'] = self.combine_with_context('env', kwargs.get('env', {}))
+    kwargs['infra_step'] = self.combine_with_context(
         'infra_step', bool(infra_step))
-    kwargs['step_nest_level'] = compositor.get_with_context('nest_level', 0)
+    kwargs['step_nest_level'] = self.combine_with_context('nest_level', 0)
     kwargs['name'] = full_name
     kwargs['base_name'] = name
 
     schema = self.make_config()
     schema.set_val(kwargs)
     return self.run_from_dict(schema.as_jsonish())
 
   # TODO(martiniss) delete, and make generator_script use **kwargs on step()
   @recipe_api.composite_step
   def run_from_dict(self, dct):
     return self.step_client.run_step(dct)