diff options
author | Vinay Sajip <vinay_sajip@yahoo.co.uk> | 2012-07-10 07:21:07 (GMT) |
---|---|---|
committer | Vinay Sajip <vinay_sajip@yahoo.co.uk> | 2012-07-10 07:21:07 (GMT) |
commit | c4618e33b2ef1c6f1cb2d8d3c2e23dfcca9f5f44 (patch) | |
tree | 1b107453dc558edbdb961b7123c6eda8755ef451 /Doc/library | |
parent | 7d39055f7faa7650b474113eda813b48baeab5b2 (diff) | |
download | cpython-c4618e33b2ef1c6f1cb2d8d3c2e23dfcca9f5f44.zip cpython-c4618e33b2ef1c6f1cb2d8d3c2e23dfcca9f5f44.tar.gz cpython-c4618e33b2ef1c6f1cb2d8d3c2e23dfcca9f5f44.tar.bz2 |
Factored out common venv documentation and added more information about Distribute/pip.
Diffstat (limited to 'Doc/library')
-rw-r--r-- | Doc/library/venv.rst | 89 |
1 files changed, 7 insertions, 82 deletions
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index f761a00..592a0d9 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -25,88 +25,8 @@ independent set of installed Python packages in its site directories. Creating virtual environments ----------------------------- -Creation of virtual environments is simplest executing the ``pyvenv`` script:: +.. include:: /using/venv-create.inc - pyvenv /path/to/new/virtual/environment - -Running this command creates the target directory (creating any parent -directories that don't exist already) and places a ``pyvenv.cfg`` file in it -with a ``home`` key pointing to the Python installation the command was run -from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory -containing a copy of the ``python`` binary (or binaries, in the case of -Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages`` -subdirectory (on Windows, this is ``Lib\site-packages``). - -.. highlight:: none - -On Windows, you may have to invoke the ``pyvenv`` script as follows, if you -don't have the relevant PATH and PATHEXT settings:: - - c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv - -or equivalently:: - - c:\Temp>c:\Python33\python -m venv myenv - -The command, if run with ``-h``, will show the available options:: - - usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear] - [--upgrade] ENV_DIR [ENV_DIR ...] - - Creates virtual Python environments in one or more target directories. - - positional arguments: - ENV_DIR A directory to create the environment in. - - optional arguments: - -h, --help show this help message and exit - --system-site-packages Give access to the global site-packages dir to the - virtual environment. - --symlinks Try to use symlinks rather than copies, when symlinks - are not the default for the platform. - --clear Delete the environment directory if it already exists. - If not specified and the directory exists, an error is - raised. - --upgrade Upgrade the environment directory to use this version - of Python, assuming Python has been upgraded in-place. - -If the target directory already exists an error will be raised, unless the -``--clear`` or ``--upgrade`` option was provided. - -The created ``pyvenv.cfg`` file also includes the -``include-system-site-packages`` key, set to ``true`` if ``venv`` is run with -the ``--system-site-packages`` option, ``false`` otherwise. - -Multiple paths can be given to ``pyvenv``, in which case an identical virtualenv -will be created, according to the given options, at each provided path. - -Once a venv has been created, it can be "activated" using a script in the -venv's binary directory. The invocation of the script is platform-specific: on -a Posix platform, you would typically do:: - - $ source <venv>/bin/activate - -whereas on Windows, you might do:: - - C:\> <venv>/Scripts/activate - -if you are using the ``cmd.exe`` shell, or perhaps:: - - PS C:\> <venv>/Scripts/Activate.ps1 - -if you use PowerShell. - -You don't specifically *need* to activate an environment; activation just -prepends the venv's binary directory to your path, so that "python" invokes the -venv's Python interpreter and you can run installed scripts without having to -use their full path. However, all scripts installed in a venv should be -runnable without activating it, and run with the venv's Python automatically. - -You can deactivate a venv by typing "deactivate" in your shell. The exact -mechanism is platform-specific: for example, the Bash activation script defines -a "deactivate" function, whereas on Windows there are separate scripts called -``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is -created. .. _venv-def: @@ -119,9 +39,14 @@ created. A venv is a directory tree which contains Python executable files and other files which indicate that it is a venv. - Common installation tools such as ``distribute`` and ``pip`` work as + Common installation tools such as ``Distribute`` and ``pip`` work as expected with venvs - i.e. when a venv is active, they install Python packages into the venv without needing to be told to do so explicitly. + Of course, you need to install them into the venv first: this could be + done by running ``distribute_setup.py`` with the venv activated, + followed by running ``easy_install pip``. Alternatively, you could download + the source tarballs and run ``python setup.py install`` after unpacking, + with the venv activated. When a venv is active (i.e. the venv's Python interpreter is running), the attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the base |