Method to get python-bootstrap search path to look for a specific file is really not obvious

[jriddy]

Describe the bug The use of explicity binary paths for python-bootstrap.search_path is not documented well in line with how it works. Despite #13278 being active here, using a path directly to a python binary doesn't work like you'd expect.

For example, with this python-bootstrap config,

[python-bootstrap]
search_path = ["/usr/bin/python3.9"]

...I get this error:

11:44:23.36 [ERROR] 1 Exception encountered:

  BinaryNotFoundError: Was not able to locate a Python interpreter to execute rule code.
Please ensure that Python is available in one of the locations identified by `[python-bootstrap] search_path`, which currently expands to:
  ['/usr/bin/python3.9']

In order to get it to recognize that binary name, I need to add the basename of that interpreter binary to names:

[python-bootstrap]
search_path = ["/usr/bin/python3.9"]
names = ["python3.9"]

This is not documented, and kind of defeats the purpose of having explicit binary paths as a feature, as the above config is functionally equivalent to

[python-bootstrap]
search_path = ["/usr/bin"]
names = ["python3.9"]

Really, what I'd like is a simple way to control what interpreter runs my Pants rules. Failing like that, I'd like this behavior to be documented a bit more clearly.

Pants version 2.9.0rc6

OS Linux

Additional info Add any other information about the problem here, such as attachments or links to gists, if relevant.

[cognifloyd]

Now that we use PBS, [python-bootrstrap].names doesn't do much (docs say it is only for selecting the interpreter used to run pants, not for user code). I think that we can use just [python-bootstrap].search_path now.

In order to select a particular python on the command line, I added these aliases in ~/.pants.rc (on my gentoo machine where I have a lot of control over which interpreters are installed in /usr/bin):

[cli.alias]
py27 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python2.7"
py36 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.6"
py37 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.7"
py38 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.8"
py39 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.9"
py310 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.10"
py311 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.11"
py312 = "--python-bootstrap-search-path=[] --python-bootstrap-search-path=/usr/bin/python3.12"

(I'm only using pants 2.17 so far. If I were on 2.18, I would use --py38 instead of py38 as the aliases)

Then, I can export a virtualenv with 2 different python versions by running:

$ pants py38 export --resolve=st2
$ pants py39 export --resolve=st2

Of course, that only works if python3.9 is in /usr/bin instead of pyenv-installed or a GHA-provided interpreter or similar. Since this is specific to my machine, I can't add these aliases to the project-specific pants.toml file for use by others.