classification
Title: Document the deprecation of pyvenv in favor of `python3 -m venv`
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: brett.cannon Nosy List: berker.peksag, brett.cannon, docs@python, martin.panter, ned.deily, python-dev, r.david.murray, stevepiercy
Priority: normal Keywords: easy, patch

Created on 2016-06-10 07:49 by stevepiercy, last changed 2016-07-16 07:29 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
pyvenv-to-venv.patch stevepiercy, 2016-07-01 08:29 pyvenv-to-venv.patch review
pyvenv-to-venv.update-susp-ignored.csv.patch stevepiercy, 2016-07-11 04:07 Update tools/susp-ignored.csv to properly ignore updated docstring review
Repositories containing patches
https://hg.python.org/cpython
Messages (23)
msg268104 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-10 07:49
Per https://bugs.python.org/issue25154 `pyvenv` is deprecated in favor of `python3 -m venv`. The docs for Python 3.5+ need to be updated accordingly.
msg268105 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-10 07:52
It's actually deprecated in Python 3.6: https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features
msg268106 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-10 08:12
I saw the patch in 3.6, yet the discussion in issue #25154 called for deprecation in 3.5.1.  Was deprecation of `pyvenv` supposed to be implemented in 3.5.1?

I couldn't find any other relevant discussion, so apologies for jumping in uninformed.
msg268124 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-06-10 16:21
Basically I changed my mind about adding the code deprecation in 3.5.1 since it wasn't fair to people to run into that in a bugfix release. Documenting the deprecation, though, can happen in Python 3.5.1 as well as updating the documentation of the venv module to only use `python3 -m venv` which I missed the first time through.
msg268133 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-10 17:57
I forgot to include the specific URL to update:
https://docs.python.org/3/installing/

There may be other places.
msg268134 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-10 18:02
One more.
https://docs.python.org/3/library/venv.html

Should that be updated for 3.5.1 as well as 3.6?
msg268135 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-10 18:05
See also:
https://github.com/pypa/python-packaging-user-guide/issues/242
msg268136 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-06-10 18:14
Documenting the deprecation in 3.5 is fine.
msg268981 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-21 10:14
I'd like to take on this issue and submit a patch for consideration by 2016-06-26.  Please let me know if anyone is working on it.
msg269005 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-06-21 15:41
No one is working on it, Steve, so feel free to write a patch.
msg269466 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-06-29 06:37
After looking into this issue, I need guidance to better define scope and intent, and how to go about submitting the changes. I found 81 occurrences of the term `pyvenv` in the documentation, either in reST files or docstrings, across about a dozen files.

1. Should I obliterate any mention of `pyvenv` (excluding HISTORY and whatsnew) or preserve a mention or two of it? For example, "`pyvenv` was the recommended tool for creating virtual environments for Python 3.3 and 3.4, and is deprecated in Python 3.6. Beginning in Python 3.5, the use of `venv` is recommended."

2. Is it preferred to submit one patch for all edited files, or one patch per edited file?

TIA for any guidance.
msg269495 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-29 14:04
In this case I think one patch is good.  The deprecation should mention pyvenv in the main venv docs (and maybe installing), but probably nowhere else.  See the deprecated-removed sphinx tag.
msg269649 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-07-01 08:29
Patch attached for review.

Notes:
- I built the docs using Sphinx 1.4.1, whereas I think 1.3.3 is in use in production. If you upgrade, you will need to specify the language for syntax highlighting, else you will get hundreds of these error messages:

  /Users/stevepiercy/projects/cpython/Doc/distutils/examples.rst:250: WARNING: Could not lex literal_block as "python3". Highlighting skipped.

  I made my changes accordingly, as they are backward compatible to Sphinx 1.3.3 and will be one fewer thing to update in future releases.
- I removed the file Doc/using/scripts.rst because it became obsolete. This caused warnings in Doc/whatsnew/3.3.rst and Doc/whatsnew/3.4.rst which reference the obsolete file.
- I updated a lot of links to https://packaging.python.org/ and others to save a redirect and to get link checking to pass.
- I replaced confusing colloquialisms of "env", "venv", and "virtualenv" with "virtual environment" as appropriate. This clarifies that a virtual environment is the thing created, whereas `venv`, `pyvenv`, and `virtualenv` are modules/scripts/commands that create a virtual environment, or that "env" is the name of a directory.
- Minor grammar, punctuation, and reST fixes.
msg269678 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-01 16:20
Thanks for the patch, Steve! Since this is a bug fix I may take until after 3.6b1 goes out to get reviewed and committed since I need to get any semantic changes in before then (b1 is due out in Sep). So if this patch lingers for a couple months, that will be why.
msg269997 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-08 17:46
New changeset 414f67e000a7 by Brett Cannon in branch 'default':
Issue #27285: Document the deprecation of the pyvenv script.
https://hg.python.org/cpython/rev/414f67e000a7
msg269998 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-07-08 17:47
Thanks for the patch, Steve! I went ahead and got this done now when I realized your patch touched so many files, thus waiting could lead to skew and the need to update the patch needlessly.
msg270004 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-07-08 18:15
Thank you!
msg270144 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-07-11 00:33
Buildbot has errors and warnings:

http://buildbot.python.org/all/builders/Docs%203.x/builds/1729/steps/suspicious/logs/stdio

make -C Doc/ suspicious
. . .
writing output... [ 83%] library/venv

WARNING: [library/venv:353] ":param" found in "        :param context: The information for the virtual environment"
. . .
/buildbot/buildarea/3.x.ware-docs/build/Doc/whatsnew/3.3.rst:110: WARNING: undefined label: scripts-pyvenv (if the link has no caption the label must precede a section header)
/buildbot/buildarea/3.x.ware-docs/build/Doc/whatsnew/3.4.rst:200: WARNING: undefined label: scripts-pyvenv (if the link has no caption the label must precede a section header)
/buildbot/buildarea/3.x.ware-docs/build/Doc/whatsnew/3.4.rst:1992: WARNING: undefined label: scripts-pyvenv (if the link has no caption the label must precede a section header)
/buildbot/buildarea/3.x.ware-docs/build/Doc/whatsnew/3.4.rst:1996: WARNING: undefined label: scripts-pyvenv (if the link has no caption the label must precede a section header)
/buildbot/buildarea/3.x.ware-docs/build/Doc/whatsnew/3.4.rst:2462: WARNING: undefined label: scripts-pyvenv (if the link has no caption the label must precede a section header)
WARNING: Found 2/299 unused rules:
library/venv,,:param,:param context: The information for the environment creation request
tutorial/venv,,:c7b9645a6f35,Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25)
. . .
Suspicious check complete; look for any errors in the above output or in build/suspicious/suspicious.csv.  If all issues are false positives, append that file to tools/susp-ignored.csv.

Looks like Doc/tools/susp-ignored.csv and the whatsnew files need adjusting.
msg270156 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-07-11 04:07
I've attached a patch for the buildbot error at [library/venv:353].

However, as noted in my [second bullet point](http://bugs.python.org/issue27285#msg269649):

- I removed the file Doc/using/scripts.rst because it became obsolete. This caused warnings in Doc/whatsnew/3.3.rst and Doc/whatsnew/3.4.rst which reference the obsolete file.

I couldn't find a policy that addresses what to do in this situation, so I left it to the council of elders to provide me with their sage guidance. I'll submit a patch as soon as I know which path to follow.
msg270195 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-11 18:23
New changeset 2a34cef7681b by Ned Deily in branch 'default':
Issue #27285: Cleanup "suspicious" warnings.
https://hg.python.org/cpython/rev/2a34cef7681b
msg270196 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2016-07-11 18:28
Thanks for the fix up, Steve.  For 3.6.0a3, I chose to just change the 3.3 and 3.4 whatsnew references to just in-line code without any links.  If anyone wants something fancier, please feel free to expand on it (after the release).

(BTW, Steve, when you submit an updated patch, please do so against the current tip of the branch; most of your update patch had already been committed by Brett.)
msg270257 - (view) Author: Steve Piercy (stevepiercy) * Date: 2016-07-12 17:38
Thanks, Ned. This was my first hg patch. I'm learning.
msg270545 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-07-16 07:29
New changeset 0d8f139a6e19 by Martin Panter in branch 'default':
Issue #27285: Cleanup leftover susp-ignored entry after text was changed
https://hg.python.org/cpython/rev/0d8f139a6e19
History
Date User Action Args
2016-07-16 07:29:19python-devsetmessages: + msg270545
2016-07-12 17:38:39stevepiercysetmessages: + msg270257
2016-07-11 18:28:31ned.deilysetstatus: open -> closed
nosy: + ned.deily
messages: + msg270196

2016-07-11 18:23:44python-devsetmessages: + msg270195
2016-07-11 04:07:19stevepiercysetfiles: + pyvenv-to-venv.update-susp-ignored.csv.patch

messages: + msg270156
2016-07-11 00:33:49martin.pantersetstatus: closed -> open
nosy: + martin.panter
messages: + msg270144

2016-07-08 18:15:05stevepiercysetmessages: + msg270004
2016-07-08 17:47:30brett.cannonsetstatus: open -> closed
resolution: fixed
messages: + msg269998

stage: needs patch -> resolved
2016-07-08 17:46:33python-devsetnosy: + python-dev
messages: + msg269997
2016-07-01 16:20:06brett.cannonsetmessages: + msg269678
2016-07-01 08:29:55stevepiercysetfiles: + pyvenv-to-venv.patch
hgrepos: + hgrepo346
messages: + msg269649

keywords: + patch
2016-06-29 14:04:26r.david.murraysetnosy: + r.david.murray
messages: + msg269495
2016-06-29 06:37:57stevepiercysetmessages: + msg269466
2016-06-21 15:41:29brett.cannonsetmessages: + msg269005
2016-06-21 10:14:40stevepiercysetmessages: + msg268981
2016-06-10 18:14:02brett.cannonsetmessages: + msg268136
2016-06-10 18:05:11stevepiercysetmessages: + msg268135
2016-06-10 18:02:48stevepiercysetmessages: + msg268134
2016-06-10 17:57:57stevepiercysetmessages: + msg268133
2016-06-10 16:21:21brett.cannonsetassignee: docs@python -> brett.cannon
messages: + msg268124
title: Deprecate pyvenv in favor of python3 -m venv -> Document the deprecation of pyvenv in favor of `python3 -m venv`
2016-06-10 08:32:35berker.peksagsetnosy: + brett.cannon
2016-06-10 08:12:51stevepiercysetmessages: + msg268106
2016-06-10 07:52:46berker.peksagsetversions: - Python 3.5
nosy: + berker.peksag

messages: + msg268105

keywords: + easy
stage: needs patch
2016-06-10 07:49:04stevepiercycreate