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(...)
+    """
     return recipe_api.context
 
+  def get_from_context(self, key, default=None):
+    """Returns |key| from context if present, otherwise |default|."""

[iannucci, 2017/02/01 17:47:00]

Returns |key|'s value from context...

[Paweł Hajdan Jr., 2017/02/01 17:50:25]

Done.

+    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."""

[iannucci, 2017/02/01 17:47:00]

... and returns the combined value.

It would be really good to include all the relevant keys and their 'combine'
functions in the docstring for the context property above. Probably just env and
cwd?

IIRC, cwd's combine is just replacement, but env does a dict.update?

[Paweł Hajdan Jr., 2017/02/01 17:50:25]

Done.
I'm worried about the docstring getting out of sync with reality.

There are more possible keys than just env and cwd.
Yup.

+    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)

[iannucci, 2017/02/01 17:47:00]

ew, I forgot about name. this is used to implement name prefixing, right?

[Paweł Hajdan Jr., 2017/02/01 17:50:25]

Yes, see api.step.nest .

       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)