bpo-44388: Update venv EnvBuilder.ensure_directories() docs. (GH-26663)

Ref:

This changes the documentation for `EnvBuilder.ensure_directories(env_dir)` to match the actual behavior of that API call.

In particular, `ensure_directories()` is not affected by the state of the `upgrade` attribute, and will not cause an error to have existing directories whether or not the `clear` attribute is set.

This documentation change I believe should be valid to all python versions back to 3.6.

Automerge-Triggered-By: GH:vsajip

diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 2a4eede91a7c17867ff3c5a490819d21478c11cf..5eb5094801501b46fb5acbf27e8fd678373d1ef3 100644 (file)
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -170,11 +170,12 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
     .. method:: ensure_directories(env_dir)
 
-        Creates the environment directory and all necessary directories, and
-        returns a context object.  This is just a holder for attributes (such as
-        paths), for use by the other methods. The directories are allowed to
-        exist already, as long as either ``clear`` or ``upgrade`` were
-        specified to allow operating on an existing environment directory.
+        Creates the environment directory and all necessary subdirectories that
+        don't already exist, and returns a context object.  This context object
+        is just a holder for attributes (such as paths) for use by the other
+        methods.  If the :class:`EnvBuilder` is created with the arg
+        ``clear=True``, contents of the environment directory will be cleared
+        and then all necessary subdirectories will be recreated.
 
     .. method:: create_configuration(context)