[Python-checkins] bpo-37403: Touch up venv docs (GH-14458)

Brett Cannon webhook-mailer at python.org
Fri Jun 28 15:14:35 EDT 2019

commit: f9f8e3ce709ceb15c8db8c8dde940daf1febf13d
branch: master
author: Brett Cannon <54418+brettcannon at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-06-28T12:14:31-07:00

bpo-37403: Touch up venv docs (GH-14458)

Add a versionadded for PS Core and note that `.venv` is a common virtual environment name.

M Doc/tutorial/venv.rst
M Doc/using/venv-create.inc

diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst
index d8bb2f5155d7..f422146aae8a 100644
--- a/Doc/tutorial/venv.rst
+++ b/Doc/tutorial/venv.rst
@@ -50,6 +50,12 @@ This will create the ``tutorial-env`` directory if it doesn't exist,
 and also create directories inside it containing a copy of the Python
 interpreter, the standard library, and various supporting files.
+A common directory location for a virtual environment is ``.venv``.
+This name keeps the directory typically hidden in your shell and thus
+out of the way while giving it a name that explains why the directory
+exists. It also prevents clashing with ``.env`` environment variable
+definition files that some tooling supports.
 Once you've created a virtual environment, you may activate it.
 On Windows, run::
diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc
index 8fd107b33202..46bf0b49657d 100644
--- a/Doc/using/venv-create.inc
+++ b/Doc/using/venv-create.inc
@@ -6,12 +6,13 @@ command ``venv``::
 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 from which the command
-was run.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
-containing a copy/symlink of the Python binary/binaries (as appropriate for the
-platform or arguments used at environment creation time). It also creates an
-(initially empty) ``lib/pythonX.Y/site-packages`` subdirectory
-(on Windows, this is ``Lib\site-packages``). If an existing
-directory is specified, it will be re-used.
+was run (a common name for the target directory is ``.venv``).  It also creates
+a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink
+of the Python binary/binaries (as appropriate for the platform or arguments
+used at environment creation time). It also creates an (initially empty)
+``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is
+``Lib\site-packages``). If an existing directory is specified, it will be
 .. deprecated:: 3.6
    ``pyvenv`` was the recommended tool for creating virtual environments for
@@ -101,12 +102,14 @@ directory containing the virtual environment):
 | Platform    | Shell           | Command to activate virtual environment |
-| Posix       | bash/zsh        | $ source <venv>/bin/activate            |
+| POSIX       | bash/zsh        | $ source <venv>/bin/activate            |
 |             | fish            | $ . <venv>/bin/activate.fish            |
 |             | csh/tcsh        | $ source <venv>/bin/activate.csh        |
+|             | PowerShell Core | $ <venv>/bin/Activate.ps1               |
 | Windows     | cmd.exe         | C:\\> <venv>\\Scripts\\activate.bat     |
 |             | PowerShell      | PS C:\\> <venv>\\Scripts\\Activate.ps1  |
@@ -127,3 +130,7 @@ when the virtual environment is created.
 .. versionadded:: 3.4
    ``fish`` and ``csh`` activation scripts.
+.. versionadded:: 3.8
+   PowerShell activation scripts installed under POSIX for PowerShell Core
+   support.

More information about the Python-checkins mailing list