http://docs.python.org/dev/library/venv.html

More detail needed regarding the original python environment

The article explains how to use venv to create a new python installation with independent libraries etc, and a means to activate one or another virtual python environment. However, there are some points regarding the original python environment which are cloudy.

(1) After pyvenv, what status does the original python installation have? Does pyvenv turn it into just one of now two or more virtual environments? Or is the original one special? Must it be specifically deactivated in order to activate a (different) virtual environment?

(2) The motivation behind venv seems to be to create virtual enviroments that can be substantially or completely separate from the system site directories or from the original python that pyvenv was run from.  Yet elsewhere the doc discusses how  pyvenv creates a pyvenv.cfg file with a home key pointing back to the originating Python installation, and "sys.base_prefix and sys.base_exec_prefix point to the non-venv Python installation which was used to create the venv."... which suggest that a venv is _not_ independent of its creating Python installation.

It would be helpful to provide some context for this seemingly contradictory information.  Perhaps there are scenarios with differing degrees of independence, in which these pointers back to the originating Python installation may or may not be relevant?

(3) How do you proceed to create virtual environments from scratch when you have no initial python installation, or no python installation of that python version?

-- Hope these suggestions help.

Additionally on the subject of venv docs:  I would encourage making it more clear regarding how activate changes the user's PATH. Both http://www.python.org/dev/peps/pep-0405/  and http://docs.python.org/3.3/library/venv.html  talk about how activate adds the activated python binary to the path, but doesn't mention what path:  The one for the current console session? The system PATH environment variable (Windows) or one of the bash startup scripts (unix)? This is important, because it determines how far-reaching is activation of a particular virtual environment.

Hmm.  It seems to me that that document is indeed not clear as to what is really going on.  My understanding has always been that there is only one Python interpreter, but that it behaves differently when invoked through the symlink in the venv.  I suppose that on Windows platforms where symlink isn't available it must actually copy the whole binary, but I don't use Windows so I don't know for sure.  (So, to answer one of your questions, you *can't* create a venv for a Python you don't already have installed.)

It should also mention that the activation is per-shell-session, which would answer some of your other questions.

Thanks R. David for your comments.

> It should also mention that the activation is per-shell-session,

.. which also has implications (or lack of effect) for launching from Windows Explorer, for example.

Seems like in practical use, one would need to set up a batch file or shell script to run a particular venv activate command and launch a command shell with that python environment already set up. "Shell for python 2.7.5 and library XYZ" etc.

Advice along these lines would be helpful.

The venv documentation does assume that the reader knows what virtual environments are and how they work. More details are available in PEP 405, which is not referenced in this documentation - I will rectify that.

New changeset ad09332f856f by Vinay Sajip in branch '3.3':
Issue #18939: Updated venv documentation with some clarifications.
http://hg.python.org/cpython/rev/ad09332f856f

New changeset 408b6b3dcf9a by Vinay Sajip in branch 'default':
Closes #18939: Merged documentation update from 3.3.
http://hg.python.org/cpython/rev/408b6b3dcf9a

@Vinay Sajip  Thanks for looking at this issue and adding the link to PEP 405, and your explanation "When working..." with helpful shebang comments.

That said, the combination of PEP 405 and this updated page doesn't clear things up completely.

Vinay remarks "The venv documentation does assume that the reader knows what virtual environments are and how they work."

If so, let's have a link to where the reader can get up to speed on how they work. PEP 405 is a help, but doesn't detail the topics I raised in earlier thread messages. Also, different legacy virtual environment schemes work differently, so prior knowledge doesn't necessarily help.

But the article already has a link to "virtual environments"... to a box in the same article, which is at the heart of not bringing clarity to the topics at hand.

One problem is lack of clarity about what "active" and "activate" means. Here is what I currently believe:

In connection with venv, the term "active" is used in two relatively trivial but subtly different ways. 

(1) "First on PATH": The phrase "active environment" may be used to simply indicate the python environment which will be found first via the user's shell PATH. Further, each venv-configured python virtual environment installation includes an "activate" script whose main effect is just to add that environment's bin or Scripts directory to the beginning of the user's PATH. This makes the selected python environment the default when the user types the 'python' command. This use of "active" or "activate" might better be termed "default or "make default".

(2) "Actually running": A second meaning of "active" refers to an actually running instance of a python interpreter and its associated environment, whether or not it is first in the user's PATH. Any installed python (virtual or not) may be launched by explicitly invoking the complete path to its executable (eg: C:\python33\python.exe), whereupon that version of python will run, with its associated sys.path and so on.

These two meanings are obviously related. The particular python environment (virtual or not) that is "active" in the first sense, when invoked by a plain "python" command, will become "active" in the second sense.  But a running python ("active" in the second sense) will not necessarily be the "active" one in the first sense.

Implications for installers: A library installer invoked from the command line, unless told otherwise, will presumably install its payload into the python environment found via PATH. Consequently, in preparation, the intended target python should be made "active" in the first sense.

I have not elaborated here on my other concern (since I don't understand the details) -- clarification of different degrees of isolation/autonomy which can be established for each virtual environment. I still believe that's important to understand, and the current article and PEP 405 don't cover it successfully, in my view.

You have understood correctly, after reading the now-existing documentation.  Do you have a suggestion for how they could be further improved, given that they currently seem to convey accurate information?

For the "autonomy" question, as far as I know the only option that affects that is whether or not the installed Python's site-packages is included in sys.path or not, and I'm sure that is documented.  Perhaps you were confused by how trivial indeed "activation" is?

If there are other things you still don't understand, it would help if you could pose specific questions.

Closing, as documentation has now been updated.