classification
Title: venv API Docs for EnvBuilder.ensure_directories incorrectly describe behavior
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9, Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, itsayellow, miss-islington, vinay.sajip
Priority: normal Keywords: patch

Created on 2021-06-11 05:00 by itsayellow, last changed 2021-07-28 10:49 by vinay.sajip. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26663 merged itsayellow, 2021-06-11 05:08
Messages (3)
msg395603 - (view) Author: Matthew Clapp (itsayellow) * Date: 2021-06-11 05:00
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
msg395678 - (view) Author: Matthew Clapp (itsayellow) * Date: 2021-06-12 06:24
To clarify my intent: I'd really love a way to get the paths info from context from an existing native venv without affecting the directories of the venv.  It seems like this is what ensure_directories *actually* does if clear==False.  I'm hoping that this is also something that could be pledged in the API and noted in the documentation so this behavior can be relied on.
msg396878 - (view) Author: miss-islington (miss-islington) Date: 2021-07-02 20:48
New changeset 4bcef2bb48b3fd82011a89c1c716421b789f1442 by Matthew Clapp in branch 'main':
bpo-44388: Update venv EnvBuilder.ensure_directories() docs. (GH-26663)
https://github.com/python/cpython/commit/4bcef2bb48b3fd82011a89c1c716421b789f1442
History
Date User Action Args
2021-07-28 10:49:34vinay.sajipsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-07-02 20:48:51miss-islingtonsetnosy: + miss-islington
messages: + msg396878
2021-06-13 21:08:57ned.deilysetnosy: + vinay.sajip
2021-06-12 06:24:43itsayellowsetmessages: + msg395678
2021-06-11 05:08:18itsayellowsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25250
2021-06-11 05:00:48itsayellowcreate