On Tue, Nov 14, 2017, 04:06 Stephan Houben, <stephanh42@gmail.com> wrote:
Hi Brett,

The current documentation *cannot* be fixed, since
fixing it would entail adding an initial two-page essay
on "how to start Python on various platforms/systems"
(it is really NOT as simple as Windows=python, Linux=python3)
and such a PR will certainly by rejected.

It doesn't have to be in the venv' docs. Such a page could be a HOWTO or in the tutorial (if it isn't already there).


In my opinion, the only alternatives are

1. either harmonize the invocation of python across platforms
  (and *then* adapt the docs to follow).
  Which was pretty much the whole topic of this thread so far.

The idea has been discussed of developing a 'py' command fo all OSs like on Windows, but has never gone beyond just a discussion.


2. or just use "python" consistently across all docs
  (since that is the *only* command which is at least consistent among
   python.org installers), and add weasel-wording to "consult documentation
  of third-party installers"

While 'python' is 'python2' on operating systems that won't really work out well. Best you could do is 'python3'.


3. or leave the docs broken for at least some people some of the time.

I'm eyeing the removal of pyvenv come February when we fork for 3.8 development so I'm personally not planning to try and clarify anything (obviously others can make an attempt).

-brett



Stephan


2017-11-14 2:31 GMT+01:00 Brett Cannon <brett@python.org>:


On Mon, Nov 13, 2017, 00:01 Stephan Houben, <stephanh42@gmail.com> wrote:
Hi all,


============

 Note
  The pyvenv script has been deprecated as of Python 3.6 in favor of
  using python3 -m venv to help prevent any potential confusion as to
  which Python interpreter a virtual environment will be based on.
============

It's clearer than the text below to which I originally referred.

However,  this text has also problems in that it is too unix-specific.
In particular:
* Most seriously, it refers to "python3" which doesn't work with the python.org Windows installer.

It can, but it's opt-in. It's just one of those things that's easy to forget.

* Less seriously, it refers to "pyenv" as a "script" which is unix jargon and moreover technically
   incorrect on Windows. (Also, needlessly specific, it should just be "the pyenv command",
  how it is implemented is irrelevant for this section).

I disagree with this as Python refers to .Py files that you execute directly as "scripts", so I don't think this requires clarification.


Anyway, a pull request with suggested wording to address your concerns would be the best way to try and rectify the issue.

-brett



Stephan

2017-11-13 0:32 GMT+01:00 Chris Angelico <rosuav@gmail.com>:
On Mon, Nov 13, 2017 at 10:29 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
> On 13 November 2017 at 07:11, Chris Angelico <rosuav@gmail.com> wrote:
>> On Mon, Nov 13, 2017 at 6:24 AM, Stephan Houben <stephanh42@gmail.com> wrote:
>>> Hi Antoine,
>>>
>>> The venv module is included,
>>> however the pyvenv script is in a separate package
>>> python3.5-venv .
>>>
>>> By the way, I was totally confused by the following text form the doc.
>>>
>>> https://docs.python.org/3/library/venv.html
>>>
>>> ========
>>> Deprecated since version 3.6: pyvenv was the recommended tool for creating
>>> virtual environments for Python 3.3 and 3.4, and is deprecated in Python
>>> 3.6.
>>>
>>> Changed in version 3.5: The use of venv is now recommended for creating
>>> virtual environments.
>>>
>>> ========
>>
>> Not sure where you're reading that. I'm seeing:
>>
>> """
>> Note
>> The pyvenv script has been deprecated as of Python 3.6 in favor of
>> using python3 -m venv to help prevent any potential confusion as to
>> which Python interpreter a virtual environment will be based on.
>> """
>>
>> I think that's pretty clear. "python3 -m venv env" is the standard and
>> recommended way to spin up a virtual environment.
>
> It's further down in the page, under
> https://docs.python.org/3/library/venv.html#creating-virtual-environments
>
> I think the deprecation notice for pyvenv should just be deleted,
> since it renders like the *module* is deprecated.

Ah, I see it now, thanks.

Agreed; or maybe downgrade it to a parenthetical comment. Focus on
"this is how to do the obvious thing", and only as an afterthought
mention "it used to be done differently" in case someone greps for
pyvenv.

ChrisA
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/