Manpage wording around `--list` and virtual environments confusing

[defjaf]

Describe the bug py is not finding an inactive (but extant) virtual environment even when a virtual environment has been created in a .venv directory.

To Reproduce

~/Developer/python$ mkdir test_py

~/Developer/python$ cd test_py/

…/python/test_py$ py --list
 3.11 │ /opt/homebrew/bin/python3.11 

…/python/test_py$ py -m venv .venv

…/python/test_py$ py --list                   #### this should show the venv, right?
 3.11 │ /opt/homebrew/bin/python3.11 

…/python/test_py$ source .venv/bin/activate

(.venv) …/python/test_py$ py --list           #### now it shows, when explicitly activated
 3.11 │ /Users/jaffe/Developer/python/test_py/.venv/bin/python3.11 

Expected behaviour py --list should show the venv created previously, even if .venv/bin/activate not explicitly run.

System Details (please complete the following information):

• OS: macOS 13.5, homebrew python 3.11, homebrew py
• Shell: bash
• Launcher Version:

$ py --help
Python Launcher for Unix 1.0.0

[defjaf]

Ok, I think this is user error (or at least, user misunderstanding):

…/python/test_py$ py -c "import sys; print(sys.prefix)"
/Users/jaffe/Developer/python/test_py/.venv

This is, or course, the correct value for the venv.

The different behaviour of --list when a venv is or isn't actually "activated" is confusing, in any case. I don't think this tracks with what the man page actually says:

       --list  List all known interpreters (except activated virtual environment); must be specified on its own.

Note that it says "except activated virtual environment". This seems to be exactly the opposite of what happens: it does list an activated environment, but not an "implicit" (?) environment.

So, perhaps this could be changed into a feature request: is there any way to query py about its "current" python, and/or for it to show up with some sort of notation in the --list output?

[brettcannon]

Note that it says "except activated virtual environment". This seems to be exactly the opposite of what happens: it does list an activated environment, but not an "implicit" (?) environment.

I can see how that wording is a bit awkward. In my head, the virtual environment in .venv will be "activated" by the Python Launcher, so it falls under that wording. If you want to submit a PR to drop the "activated" part then I would happily take it!

So, perhaps this could be changed into a feature request

https://github.com/brettcannon/python-launcher/discussions/74 . It's more of a current technical limitation in how things are designed and to match what the Python Launcher for Windows does as some people parse the output for globally installed interpreters and don't care about the virtual environment helper.

is there any way to query py about its "current" python, and/or for it to show up with some sort of notation in the --list output?

py -c "import sys; print(sys.executable)" is the assumed way people will figure out which interpreter py will select. I would be happy to take a PR to add this to the FAQ for the website.

[defjaf]

I can see how that wording is a bit awkward. In my head, the virtual environment in .venv will be "activated" by the Python Launcher, so it falls under that wording. If you want to submit a PR to drop the "activated" part then I would happily take it!

Well, the past-participle "activated" implies to me that you've actually done something to activated. But in any case the behaviour after explicitly running activate is definitely not as documented, I think.

#74 . It's more of a current technical limitation in how things are designed and to match what the Python Launcher for Windows does as some people parse the output for globally installed interpreters and don't care about the virtual environment helper.

I admit I don't understand this use case (and I've never used python or much of anything else on windows, so that bit of consistency doesn't matter to me...)

To me, a way to see all currently-available environments, virtual or otherwise, seems like a much more obvious use case.

Is it a proper technical limitation of the implementation (i.e., would it be difficult to implement)? Or would --list-all be a possible non-breaking addition?

py -c "import sys; print(sys.executable)" is the assumed way people will figure out which interpreter py will select. I would be happy to take a PR to add this to the FAQ for the website.

This seems like exactly the kind of inside knowledge that py is intending to make less relevant!

[brettcannon]

Is it a proper technical limitation of the implementation (i.e., would it be difficult to implement)?

It requires a (planned) rewrite of the internals in how it handles environment discovery in a more uniform way.

This seems like exactly the kind of inside knowledge that py is intending to make less relevant!

I don't know if the exclamation point is quite necessary (I'm starting to feel overly criticized for doing the best I can with a project I do in my spare time), but for me, the Python Launcher for Unix isn't meant to hide technical details at all. All it's doing is trying to shave off some sharp edges that crop up due to how PATH works and people wanting to just type python3 typically. It also tosses in a nicety around how I manage virtual environments.

As stated at https://python-launcher.app:

The goal of the Python Launcher for Unix is to figure out what Python interpreter you want when your run the py command. Its preference is to find the interpreter using the newest version of Python that is as specific as possible to your current context. This allows you to not have to think about or perform extra work.

There's nothing there about hiding "insider knowledge" and I'm sorry if the docs were not clear about that and you feel misled.

[defjaf]

Hi Brett,

Thanks for your quick responses and willingness to think about my suggestions. I really appreciate the work you put into py and indeed more broadly into the python community! (That's a much more positive exclamation point, I hope... ;-)) No intention to criticize; just trying to wrap my head around py and more broadly see if/how it fits into my python workflow especially as I am tentatively attempting to embrace venvs...

[brettcannon]

Closed as a part of https://github.com/brettcannon/python-launcher/pull/404 .