search

python / cpython

The Python programming language
https://www.python.org/
Other
61.15k stars 29.51k forks source link

Tutorial: command for `python -c` should be consistent with main command #112146

Open encukou opened 8 months ago

encukou commented 8 months ago

In https://docs.python.org/3/tutorial/interpreter.html, the main command is python3.12 but later an alternative is given: python -c command [arg] ... Both should be the same (python3.12).

terryjreedy commented 8 months ago

I disagree. Explain that since the actual command word needed or allowed varies by OS and installation, we use the generic 'python' except in literal code examples where something more specific is needed, and that users should interpret 'python' as needed. It might be good to explain that a now generic 'python3' may also work to get the 'latest' python3.x.

terryjreedy commented 8 months ago

The initial statement "The Python interpreter is usually installed as /usr/local/bin/python3.12 on those machines where it is available" is unix specific and is both wrong and meaningless for the majority of beginners, the presumed target of the tutorial. Version specific statement should explicitly say so. Start with "The Python 3.12 interpreter ..." whatever the continuation.

The box with "python3.12" is wrong for Windows users who install from python.org (and maybe other places other than Microsoft store) and install the recommended way, which is to use the py launcher and not add the python3.12 directory to PATH. I believe that a majority of beginners are using Windows releases and therefore think the tutorial should not treat them as an afterthought.

terryjreedy commented 8 months ago

A deeper problem is that 'Invoking the interpreter' only discusses starting Python from a command line, which may the the least common way beginners start Python. It ignores icons, menus, and file dialogs.

hugovk commented 8 months ago

I believe that a majority of beginners are using Windows releases and therefore think the tutorial should not treat them as an afterthought.

We have numbers that suggest this. From the Plausible trial in July, 58.6% of visitors to the docs used Windows.

We don't know if they were beginners or tutorial visitors, but tutorial pages are amongst the most visited, so I expect many are also Windows users:

drts01 commented 1 month ago

Is the issue now about updating the tutorial to help Windows users? I believe that issue is different than what the title says. I believe the original issue stated original title no longer an issue as I can not find the inconsistency. Should the title be changed to add a tutorial information for Windows users, or create a new issue?

terryjreedy commented 1 month ago

The inconsistency reported by a user, between python3.12 and python, is still there. The fixup needed in more complicated then replacing either by the other. I have changed the title. I am thinking about a draft PR.