[doc] Document VIRTUAL_ENV environment variable (GH-21970)

[andresdelfino]

Automerge-Triggered-By: @vsajip

[miss-islington]

Thanks @andresdelfino for the PR, and @vsajip for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

[miss-islington]

Thanks @andresdelfino for the PR, and @vsajip for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

[bedevere-bot]

GH-24362 is a backport of this pull request to the 3.9 branch.

[bedevere-bot]

GH-24363 is a backport of this pull request to the 3.8 branch.

[pelson]

@vsajip - sorry to drag this up, but I believe this change is incorrect. It would be dangerous to use an environment variable to determine if a virtual environment is being used or not. I would never do this in production, and instead would check sys.base_prefix != sys.prefix.

This recommendation is indeed already explicitly stated in the same file:

When a virtual environment is active (i.e., the virtual environment’s Python interpreter is running), the attributes sys.prefix and sys.exec_prefix point to the base directory of the virtual environment, whereas sys.base_prefix and sys.base_exec_prefix point to the non-virtual environment Python installation which was used to create the virtual environment.

A simple counter example to the documentation would be:

$ python3.9 -m venv /tmp/a-new-venv
$ /tmp/a-new-venv/bin/python -c "import os; print(f'Val: {os.getenv(\"VIRTUAL_ENV\")}')"
Val: None

I therefore recommend that this commit be reverted. I would be happy to file a bug if that is required to revert.

[vsajip]

I therefore recommend that this commit be reverted.

Rather than doing that, I would propose to change the paragraph as follows:

When a virtual environment has been activated using one of the activation scripts, the :envvar:VIRTUAL_ENV environment
variable is set to the path of the virtual environment. Although it might seem that this could be used to check if one is running inside a virtual environment, it is not always present: for example, a script installed in a virtual environment can be run using its absolute path, and the correct environment would then be in effect; however, there would be no VIRTUAL_ENV variable in the environment. It's always safer to use sys.base_prefix != sys.prefix, which will be True when running in a virtual environment. See the note below.

[pelson]

When a virtual environment has been activated using one of the activation scripts, the :envvar:VIRTUAL_ENV environment
variable is set to the path of the virtual environment. Although it might seem that this could be used to check if one is running inside a virtual environment, it is not always present: for example, a script installed in a virtual environment can be run using its absolute path, and the correct environment would then be in effect; however, there would be no VIRTUAL_ENV variable in the environment. It's always safer to use sys.base_prefix != sys.prefix, which will be True when running in a virtual environment. See the note below.

I take your lead on this, but to me that sounds like quite a lot of words for not a lot of new detail. I definitely think the page in question could be reshuffled a bit to make this concise and easier to find the information quickly. Would you like me to submit a proposal?

[vsajip]

Would you like me to submit a proposal?

By all means.

[andresdelfino]

I think we shouldn't remove the mention to VIRTUAL_ENV (reverting this commit would have that effect), as it is helpful.

Of course, I'm all for improving the correctness of the docs.

[vsajip]

Well, I made my suggestion in the way that I did because it

• Informs users about the environment variable (it could be useful to know in some scenarios)
• Warns against relying on it for determining whether code is running in a virtual environment

and it may be wordier than it needs to be, but I was thinking of spelling things out for any inexperienced users / users new to virtual environments.