Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the deprecation of pyvenv in favor of python3 -m venv #71472

Closed
stevepiercy mannequin opened this issue Jun 10, 2016 · 23 comments
Closed

Document the deprecation of pyvenv in favor of python3 -m venv #71472

stevepiercy mannequin opened this issue Jun 10, 2016 · 23 comments
Assignees
@brettcannon
Labels
docs Documentation in the Doc dir easy type-feature A feature request or enhancement

Comments

@stevepiercy
Copy link
Mannequin

stevepiercy mannequin commented Jun 10, 2016

BPO 27285
Nosy @brettcannon, @ned-deily, @bitdancer, @berkerpeksag, @vadmium, @stevepiercy
Files
  • pyvenv-to-venv.patch: pyvenv-to-venv.patch
  • pyvenv-to-venv.update-susp-ignored.csv.patch: Update tools/susp-ignored.csv to properly ignore updated docstring
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = 'https://github.com/brettcannon'
closed_at = <Date 2016-07-11.18:28:31.993>
created_at = <Date 2016-06-10.07:49:04.109>
labels = ['easy', 'type-feature', 'docs']
title = 'Document the deprecation of pyvenv in favor of `python3 -m venv`'
updated_at = <Date 2016-07-16.07:29:19.253>
user = 'https://github.com/stevepiercy'

    bugs.python.org fields:

    activity = <Date 2016-07-16.07:29:19.253>
actor = 'python-dev'
assignee = 'brett.cannon'
closed = True
closed_date = <Date 2016-07-11.18:28:31.993>
closer = 'ned.deily'
components = ['Documentation']
creation = <Date 2016-06-10.07:49:04.109>
creator = 'stevepiercy'
dependencies = []
files = ['43598', '43681']
hgrepos = ['346']
issue_num = 27285
keywords = ['patch', 'easy']
message_count = 23.0
messages = ['268104', '268105', '268106', '268124', '268133', '268134', '268135', '268136', '268981', '269005', '269466', '269495', '269649', '269678', '269997', '269998', '270004', '270144', '270156', '270195', '270196', '270257', '270545']
nosy_count = 8.0
nosy_names = ['brett.cannon', 'ned.deily', 'r.david.murray', 'docs@python', 'python-dev', 'berker.peksag', 'martin.panter', 'stevepiercy']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue27285'
versions = ['Python 3.6']
    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 10, 2016

    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.

    @stevepiercy stevepiercy mannequin assigned docspython Jun 10, 2016
    @stevepiercy stevepiercy mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Jun 10, 2016
    @berkerpeksag
    Copy link
    Member

    It's actually deprecated in Python 3.6: https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 10, 2016

    I saw the patch in 3.6, yet the discussion in issue bpo-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.

    @brettcannon
    Copy link
    Member

    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.

    @brettcannon brettcannon changed the title Deprecate pyvenv in favor of python3 -m venv Document the deprecation of pyvenv in favor of python3 -m venv Jun 10, 2016
    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 10, 2016

    I forgot to include the specific URL to update:
    https://docs.python.org/3/installing/

    There may be other places.

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 10, 2016

    One more.
    https://docs.python.org/3/library/venv.html

    Should that be updated for 3.5.1 as well as 3.6?

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 10, 2016

    See also:
    pypa/packaging.python.org#242

    @brettcannon
    Copy link
    Member

    Documenting the deprecation in 3.5 is fine.

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 21, 2016

    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.

    @brettcannon
    Copy link
    Member

    No one is working on it, Steve, so feel free to write a patch.

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jun 29, 2016

    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.

    @bitdancer
    Copy link
    Member

    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.

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jul 1, 2016

    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.

    @brettcannon
    Copy link
    Member

    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.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jul 8, 2016

    New changeset 414f67e000a7 by Brett Cannon in branch 'default':
    Issue bpo-27285: Document the deprecation of the pyvenv script.
    https://hg.python.org/cpython/rev/414f67e000a7

    @brettcannon
    Copy link
    Member

    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.

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jul 8, 2016

    Thank you!

    @vadmium
    Copy link
    Member

    vadmium commented Jul 11, 2016

    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.

    @vadmium vadmium reopened this Jul 11, 2016
    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jul 11, 2016

    I've attached a patch for the buildbot error at [library/venv:353].

    However, as noted in my second bullet point:

    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.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jul 11, 2016

    New changeset 2a34cef7681b by Ned Deily in branch 'default':
    Issue bpo-27285: Cleanup "suspicious" warnings.
    https://hg.python.org/cpython/rev/2a34cef7681b

    @ned-deily
    Copy link
    Member

    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.)

    @stevepiercy
    Copy link
    Mannequin Author

    stevepiercy mannequin commented Jul 12, 2016

    Thanks, Ned. This was my first hg patch. I'm learning.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jul 16, 2016

    New changeset 0d8f139a6e19 by Martin Panter in branch 'default':
    Issue bpo-27285: Cleanup leftover susp-ignored entry after text was changed
    https://hg.python.org/cpython/rev/0d8f139a6e19

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @brettcannon brettcannon

    Labels
    docs Documentation in the Doc dir easy type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @berkerpeksag @brettcannon @bitdancer @vadmium @ned-deily