[context] Split "env" values and prefixes.

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 bisect
 import collections
 import contextlib
 import copy
 import json
 import keyword
+import os
 import re
 import types
 
 from functools import wraps
 
 from .recipe_test_api import DisabledTestData, ModuleTestData
 from .config import Single
 from .util import ModuleInjectionSite, Placeholder
 
 
@@ skipping 144 matching lines @@
     return copy.deepcopy(self._engine.properties)
 
 
 class StepClient(object):
   """A recipe engine client representing step running and introspection."""
 
   IDENT = 'step'
 
 
   class StepConfig(collections.namedtuple('_StepConfig', (
-      'name', 'base_name', 'cmd', 'cwd', 'env', 'allow_subannotations',
-      'trigger_specs', 'timeout', 'infra_step', 'stdout', 'stderr', 'stdin',
-      'ok_ret', 'step_test_data', 'nest_level'))):
+      'name', 'base_name', 'cmd', 'cwd', 'env', 'env_prefixes',
+      'allow_subannotations', 'trigger_specs', 'timeout', 'infra_step',
+      'stdout', 'stderr', 'stdin', 'ok_ret', 'step_test_data', 'nest_level'))):
 
     """
     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.
 
     Fields:
       name (str): name of the step, will appear in buildbots waterfall
       base_name (str): the base name of the step. If the step has a derived
           name (e.g., nested may be concatenated with its parent), this is the
           name component of just this step. If None, this will be set to "name".
       cmd: command to run. Acceptable types: str, Path, Placeholder, or None.
       cwd (str or None): absolute path to working directory for the command
       env (dict): overrides for environment variables, described above.
+      env_prefixes (dict): environment prefix variables, mapping environment
+        variable names to EnvPrefix values.
       allow_subannotations (bool): if True, lets the step emit its own
           annotations. 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.
       timeout: if not None, a datetime.timedelta for the step timeout.
       infra_step: if True, this is an infrastructure step. Failures will raise
           InfraFailure instead of StepFailure.
       stdout: Placeholder to put step stdout into. If used, stdout won't appear
           in annotator's stdout (and |allow_subannotations| is ignored).
@@ skipping 11 matching lines @@
 
     The optional "env" parameter provides optional 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",
       }
+
+    The optional "env_prefixes" parameter contains values that, if specified,
+    will transform an environment variable into a "pathsep"-delimited sequence
+    of items:
+      - If an environment variable is also specified for this key, it will be
+        appended as the last element: <prefix0>:...:<prefixN>:ENV
+      - If no environment variable is specified, the current environment's value
+        will be appended, unless it's empty: <prefix0>:...:<prefixN>[:ENV]?
+      - If an environment variable with a value of None (delete) is specified,
+        nothing will be appeneded: <prefix0>:...:<prefixN>
+
+    There is currently no way to remove prefix paths; once they're there,
+    they're there for good. If you think you need to remove paths from the
+    prefix lists, please talk to infra-dev@chromium.org.
     """
 
+    class EnvPrefix(collections.namedtuple('_EnvPrefix', (
+        'prefixes', 'pathsep'))):
+      """Expresses a series of environment prefixes.
+
+      This is used as StepConfig's "env_prefix" value.
+      """
+
+      @classmethod
+      def empty(cls):
+        return cls(prefixes={}, pathsep=None)
+
+
     _RENDER_WHITELIST=frozenset((
       'cmd',
     ))
 
     _RENDER_BLACKLIST=frozenset((
       'base_name',
       'nest_level',
       'ok_ret',
       'step_test_data',
     ))
 
     def __new__(cls, **kwargs):
       for field in cls._fields:
         kwargs.setdefault(field, None)
       sc = super(StepClient.StepConfig, cls).__new__(cls, **kwargs)
 
       return sc._replace(
           cmd=[(x if isinstance(x, Placeholder) else str(x))
                for x in (sc.cmd or ())],
           cwd=(str(sc.cwd) if sc.cwd else (None)),
+          env=sc.env or {},
+          env_prefixes=sc.env_prefixes or cls.EnvPrefix.empty(),
           base_name=sc.base_name or sc.name,
           allow_subannotations=bool(sc.allow_subannotations),
           trigger_specs=sc.trigger_specs or (),
           infra_step=bool(sc.infra_step),
           ok_ret=frozenset(sc.ok_ret or (0,)),
           nest_level=int(sc.nest_level or 0),
       )
 
     def render_to_dict(self):
       sc = self._replace(
+          env_prefixes={k: list(str(e) for e in v)
+                        for k, v in self.env_prefixes.prefixes.iteritems()},
           trigger_specs=[trig._render_to_dict()
                          for trig in (self.trigger_specs or ())],
       )
       return dict((k, v) for k, v in sc._asdict().iteritems()
                   if (v or k in sc._RENDER_WHITELIST)
                   and k not in sc._RENDER_BLACKLIST)
 
 
   class TriggerSpec(collections.namedtuple('_TriggerSpec', (
       'bucket', 'builder_name', 'properties', 'buildbot_changes', 'tags',
@@ skipping 787 matching lines @@
   def bind(self, name, property_type, full_decl_name):
     """
     Gets the BoundProperty version of this Property. Requires a name.
     """
     return BoundProperty(
       self._default, self.help, self.kind, name, property_type, full_decl_name,
       self.param_name)
 
 class UndefinedPropertyException(TypeError):
   pass