feat(pex): support building PEX archives to inherit from the sys.path (#619)

By default PEX archives are built to operate fully hermetically, which
is usually a good idea. However, sometimes it is necessary to use
packages from the hosting environment. One such example is AWS Lambda;
the recommended approach for using PEX to run on Lambda is to build in
this way.[^1]

Mapping of this flag through from the build system largely follows the
equivalent feature in Pants.[^2]

---

### Changes are visible to end-users: yes

- Searched for relevant documentation and updated as needed: yes
- Breaking change (forces users to change their own code or config):no
- Suggested release notes appear below: no

### Test plan

- Covered by existing test cases
- Manual testing; please provide instructions so we can reproduce:

1. Edit `//py/tests/py-pex-binary:print_modules_pex` to have an explicit
`inherit_path` of a chosen value (e.g. "prefer").
2. `bazel build //py/tests/py-pex-binary:print_modules_pex`.
3. `tar xfO bazel-bin/py/tests/py-pex-binary/print_modules_pex.pex
PEX-INFO | jq '.inherit_path'`
4. Expect result: `"prefer"`.

Do above except without passing an explicit `inherit_path` should give
`"false"`, which confirms the default semantics are preserved.

[^1]: https://github.com/pex-tool/lambdex/blob/main/MIGRATING.md
[^2]:
https://www.pantsbuild.org/stable/reference/targets/pex_binary#inherit_path

Author: plobsing

docs/pex.md

@@ -106,6 +106,9 @@ def _py_python_pex_impl(ctx):
     args.add(ctx.attr.python_shebang, format = "--python-shebang=%s")
     args.add(py_toolchain.python, format = "--python=%s")
 
+    if ctx.attr.inherit_path != "":
+        args.add(ctx.attr.inherit_path, format = "--inherit-path=%s")
+
     py_version = py_toolchain.interpreter_version_info
     args.add_all(
         [
@@ -135,6 +138,15 @@ _attrs = dict({
         doc = "Environment variables to set when running the pex binary.",
         default = {},
     ),
+    "inherit_path": attr.string(
+        doc = """\
+Whether to inherit the `sys.path` (aka PYTHONPATH) of the environment that the binary runs in.
+
+Use `false` to not inherit `sys.path`; use `fallback` to inherit `sys.path` after packaged
+dependencies; and use `prefer` to inherit `sys.path` before packaged dependencies.
+""",
+        values = ["false", "fallback", "prefer"],
+    ),
     "python_shebang": attr.string(default = "#!/usr/bin/env python3"),
     "python_interpreter_constraints": attr.string_list(
         default = ["CPython=={major}.{minor}.*"],

py/private/py_pex_binary.bzl

@@ -9,6 +9,7 @@
 
 import sys
 from pex.pex_builder import Check,PEXBuilder
+from pex.inherit_path import InheritPath
 from pex.interpreter import PythonInterpreter
 from pex.interpreter_constraints import InterpreterConstraint
 from pex.layout import Layout
@@ -26,6 +27,13 @@ def __call__(self, parser, namespace, value, option_str=None):
             )
         self.default.append(tuple(components))
 
+
+class InheritPathAction(Action):
+    def __call__(self, parser, namespace, value, option_str=None):
+        value = InheritPath.for_value(value)
+        setattr(namespace, self.dest, value)
+
+
 parser = ArgumentParser(fromfile_prefix_chars='@')
 
 parser.add_argument(
@@ -107,6 +115,13 @@ def __call__(self, parser, namespace, value, option_str=None):
     action="append",
 )
 
+parser.add_argument(
+    "--inherit-path",
+    dest="inherit_path",
+    default=None,
+    action=InheritPathAction,
+)
+
 options = parser.parse_args(args = sys.argv[1:])
 
 # Monkey patch bootstrap template to inject some templated environment variables.
@@ -157,6 +172,8 @@ def __call__(self, parser, namespace, value, option_str=None):
     InterpreterConstraint.parse(constraint) 
     for constraint in options.constraints
 ]
+if options.inherit_path is not None:
+    pex_info.inherit_path = options.inherit_path
 
 for dep in options.dependencies:
     dist = Distribution.load(dep)