From 2a01d82b09ac58b109c5c1f578acfa2d30877caf Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Thu, 24 May 2012 14:18:29 -0600 Subject: [PATCH 1/2] Edit include files section of PEP 405. --- pep-0405.txt | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/pep-0405.txt b/pep-0405.txt index fe097cf71..4437998a9 100644 --- a/pep-0405.txt +++ b/pep-0405.txt @@ -299,19 +299,18 @@ standard abstraction for a site-specific include directory. This PEP proposes a slightly different approach, though one with essentially the same effect and the same set of advantages and -disadvantages. Rather than symlinking or copying include files into -the venv, we simply modify the sysconfig schemes so that header files -are always looked for relative to ``base_prefix`` rather than -``prefix``. (We also create an ``include/`` directory within the venv +disadvantages. Rather than symlinking or copying include files into the +venv, we simply modify the sysconfig schemes so that header files are +always looked for relative to ``base_prefix`` rather than +``prefix``. (We also create an ``include/`` directory within the venv, +so installers have somewhere to put include files installed within the +env). Better handling of include files in distutils/packaging and, by extension, pyvenv, is an area that may deserve its own future PEP. For now, we propose that the behavior of virtualenv has thus far proved itself to be at least "good enough" in practice. -[Open question: should pyvenv instead simply copy the behavior of -virtualenv entirely, to avoid introducing unexpected new issues here?] - API --- From 4162cd4583e41efff7e40788798efc00b4623b42 Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Thu, 24 May 2012 15:46:52 -0600 Subject: [PATCH 2/2] Edits from ncoghlan review. --- pep-0405.txt | 78 +++++++++++++++++++++++++++------------------------- 1 file changed, 40 insertions(+), 38 deletions(-) diff --git a/pep-0405.txt b/pep-0405.txt index 4437998a9..3939740bf 100644 --- a/pep-0405.txt +++ b/pep-0405.txt @@ -78,12 +78,13 @@ that signifies the presence of the standard library, and if none is found, falling back to the build-time prefix hardcoded in the binary. This PEP proposes to add a new first step to this search. If a -``pyvenv.cfg`` file is found either adjacent to the Python executable, -or one directory above it, this file is scanned for lines of the form -``key = value``. If a ``home`` key is found, this signifies that the -Python binary belongs to a virtual environment, and the value of the -``home`` key is the directory containing the Python executable used to -create this virtual environment. +``pyvenv.cfg`` file is found either adjacent to the Python executable or +one directory above it (if the executable is a symlink, it is not +dereferenced), this file is scanned for lines of the form ``key = +value``. If a ``home`` key is found, this signifies that the Python +binary belongs to a virtual environment, and the value of the ``home`` +key is the directory containing the Python executable used to create +this virtual environment. In this case, prefix-finding continues as normal using the value of the ``home`` key as the effective Python binary location, which finds @@ -95,14 +96,16 @@ this value, while ``sys.prefix`` is set to the directory containing prefix-finding continues normally, and ``sys.prefix`` will be equal to ``sys.base_prefix``.) +Also, ``sys.base_exec_prefix`` is added, and handled similarly with +regard to ``sys.exec_prefix``. (``sys.exec_prefix`` is the equivalent of +``sys.prefix``, but for platform-specific files; by default it has the +same value as ``sys.prefix``.) + The ``site`` and ``sysconfig`` standard-library modules are modified such that the standard library and header files are are found relative -to ``sys.base_prefix``, while site-package directories ("purelib" and -"platlib", in ``sysconfig`` terms) are still found relative to -``sys.prefix``. - -(Also, ``sys.base_exec_prefix`` is added, and handled similarly with -regard to ``sys.exec_prefix``.) +to ``sys.base_prefix`` / ``sys.base_exec_prefix``, while site-package +directories ("purelib" and "platlib", in ``sysconfig`` terms) are still +found relative to ``sys.prefix`` / ``sys.exec_prefix``. Thus, a Python virtual environment in its simplest form would consist of nothing more than a copy or symlink of the Python binary @@ -147,12 +150,12 @@ 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 (or symlink) of the -``python3`` executable, and the ``pysetup3`` script from the -``packaging`` standard library module (to facilitate easy installation -of packages from PyPI into the new virtualenv). And it creates an -(initially empty) ``lib/pythonX.Y/site-packages`` (or -``Lib\site-packages`` on Windows) subdirectory. +Windows) subdirectory containing a copy (or symlink) of the ``python3`` +executable, and the ``pysetup3`` script from the ``packaging`` standard +library module (to facilitate easy installation of packages from PyPI +into the new venv). And it creates an (initially empty) +``lib/pythonX.Y/site-packages`` (or ``Lib\site-packages`` on Windows) +subdirectory. If the target directory already exists an error will be raised, unless the ``--clear`` option was provided, in which case the target @@ -160,27 +163,29 @@ directory will be deleted and virtual environment creation will proceed as usual. The created ``pyvenv.cfg`` file also includes the -``include-system-site-packages`` key, set to ``true`` if ``venv`` is +``include-system-site-packages`` key, set to ``true`` if ``pyvenv`` is run with the ``--system-site-packages`` option, ``false`` by default. Multiple paths can be given to ``pyvenv``, in which case an identical -virtualenv will be created, according to the given options, at each +venv will be created, according to the given options, at each provided path. -The ``venv`` module also provides "shell activation scripts" for POSIX -and Windows systems which simply add the virtual environment's ``bin`` -(or ``Scripts``) directory to the front of the user's shell PATH. -This is not strictly necessary for use of a virtual environment (as an -explicit path to the venv's python binary or scripts can just as well -be used), but it is convenient. +The ``venv`` module also places "shell activation scripts" for POSIX and +Windows systems in the ``bin`` or ``Scripts`` directory of the +venv. These scripts simply add the virtual environment's ``bin`` (or +``Scripts``) directory to the front of the user's shell PATH. This is +not strictly necessary for use of a virtual environment (as an explicit +path to the venv's python binary or scripts can just as well be used), +but it is convenient. In order to allow ``pysetup`` and other Python package managers to install packages into the virtual environment the same way they would install into a normal Python installation, and avoid special-casing -virtual environments in ``sysconfig`` beyond using ``sys.site_prefix`` -in place of ``sys.prefix``, the internal virtual environment layout -mimics the layout of the Python installation itself on each platform. -So a typical virtual environment layout on a POSIX system would be:: +virtual environments in ``sysconfig`` beyond using ``sys.base_prefix`` +in place of ``sys.prefix`` where appropriate, the internal virtual +environment layout mimics the layout of the Python installation itself +on each platform. So a typical virtual environment layout on a POSIX +system would be:: pyvenv.cfg bin/python3 @@ -301,10 +306,9 @@ This PEP proposes a slightly different approach, though one with essentially the same effect and the same set of advantages and disadvantages. Rather than symlinking or copying include files into the venv, we simply modify the sysconfig schemes so that header files are -always looked for relative to ``base_prefix`` rather than -``prefix``. (We also create an ``include/`` directory within the venv, -so installers have somewhere to put include files installed within the -env). +always sought relative to ``base_prefix`` rather than ``prefix``. (We +also create an ``include/`` directory within the venv, so installers +have somewhere to put include files installed within the env). Better handling of include files in distutils/packaging and, by extension, pyvenv, is an area that may deserve its own future PEP. For @@ -507,10 +511,8 @@ Reference Implementation ======================== The reference implementation is found in `a clone of the CPython -Mercurial repository`_. To test it, build and install it (the virtual -environment tool currently does not run from a source tree). From the -installed Python, run ``bin/pyvenv /path/to/new/virtualenv`` to create -a virtual environment. +Mercurial repository`_. To test it, build and run ``bin/pyvenv +/path/to/new/venv`` to create a virtual environment. .. _a clone of the CPython Mercurial repository: http://hg.python.org/sandbox/vsajip#venv