bpo-35854: Fix EnvBuilder and --symlinks in venv on Windows (GH-11700)
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index efa51e2..412808a 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -109,8 +109,7 @@
any existing target directory, before creating the environment.
* ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
- Python binary (and any necessary DLLs or other binaries,
- e.g. ``pythonw.exe``), rather than copying.
+ Python binary rather than copying.
* ``upgrade`` -- a Boolean value which, if true, will upgrade an existing
environment with the running Python - for use when that Python has been
@@ -176,15 +175,15 @@
.. method:: setup_python(context)
- Creates a copy of the Python executable in the environment on POSIX
- systems. If a specific executable ``python3.x`` was used, symlinks to
- ``python`` and ``python3`` will be created pointing to that executable,
- unless files with those names already exist.
+ Creates a copy or symlink to the Python executable in the environment.
+ On POSIX systems, if a specific executable ``python3.x`` was used,
+ symlinks to ``python`` and ``python3`` will be created pointing to that
+ executable, unless files with those names already exist.
.. method:: setup_scripts(context)
Installs activation scripts appropriate to the platform into the virtual
- environment. On Windows, also installs the ``python[w].exe`` scripts.
+ environment.
.. method:: post_setup(context)
@@ -194,8 +193,13 @@
.. versionchanged:: 3.7.2
Windows now uses redirector scripts for ``python[w].exe`` instead of
- copying the actual binaries, and so :meth:`setup_python` does nothing
- unless running from a build in the source tree.
+ copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
+ nothing unless running from a build in the source tree.
+
+ .. versionchanged:: 3.7.3
+ Windows copies the redirector scripts as part of :meth:`setup_python`
+ instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
+ When using symlinks, the original executables will be linked.
In addition, :class:`EnvBuilder` provides this utility method that can be
called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc
index ba5096a..1ba538b 100644
--- a/Doc/using/venv-create.inc
+++ b/Doc/using/venv-create.inc
@@ -70,6 +70,11 @@
In earlier versions, if the target directory already existed, an error was
raised, unless the ``--clear`` or ``--upgrade`` option was provided.
+.. note::
+ While symlinks are supported on Windows, they are not recommended. Of
+ particular note is that double-clicking ``python.exe`` in File Explorer
+ will resolve the symlink eagerly and ignore the virtual environment.
+
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.