This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author itsayellow
Recipients docs@python, itsayellow
Date 2021-06-11.05:00:47
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1623387648.1.0.29600166507.issue44388@roundup.psfhosted.org>
In-reply-to
Content
The docs for the venv module, EnvBuilder class, ensure_directories method, describe behavior that doesn't match what its actual behavior is, (and what the code is).  I propose to update the documentation of the API to match the actual behavior.

https://docs.python.org/3.9/library/venv.html#venv.EnvBuilder.ensure_directories

The last sentence for ensure_directories(env_dir) reads:
The directories are allowed to exist already, as long as either clear or upgrade were specified to allow operating on an existing environment directory.

After testing and looking at the code (including past commits back over 6 years), this is not true.  ensure_directories completely disregards the `upgrade` attribute.  Also it allows directories to exist already unconditionally (always operating without error), whether the `clear` attribute is set or not.  In addition, if `clear` is not set, it doesn't make any changes to the directories, but helpfully still returns the context of venv paths.

Ref: https://github.com/python/cpython/blob/3ce35bfbbe29664942f9a8c50c177a4575a31934/Lib/venv/__init__.py#L95
History
Date User Action Args
2021-06-11 05:00:48itsayellowsetrecipients: + itsayellow, docs@python
2021-06-11 05:00:48itsayellowsetmessageid: <1623387648.1.0.29600166507.issue44388@roundup.psfhosted.org>
2021-06-11 05:00:48itsayellowlinkissue44388 messages
2021-06-11 05:00:47itsayellowcreate