match statement is undocumented in built-in python help

[britecrawlers]

Documentation

Python 3.11.7 (tags/v3.11.7:fa7a6f2, Dec 4 2023, 19:24:49) [MSC v.1937 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

help()
Welcome to Python 3.11's help utility! If this is your first time using
Python, you should definitely check out the tutorial at
https://docs.python.org/3.11/tutorial/.

Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules. To get a list of available
modules, keywords, symbols, or topics, enter "modules", "keywords",
"symbols", or "topics".

Each module also comes with a one-line summary of what it does; to list
the modules whose name or summary contain a given string such as "spam",
enter "modules spam".

To quit this help utility and return to the interpreter,
enter "q" or "quit".

help> match
No Python documentation found for 'match'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

help> quit
You are now leaving help and returning to the Python interpreter.
If you want to ask for help on a particular object directly from the
interpreter, you can type "help(object)". Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.

[kiran-4444]

Can I take this up?

[Eclips4]

Duplicate of #105895

[britecrawlers]

Hello Chandra Kiran G , I'm sorry, but I don't know what you mean by "take this up". Obviously, my knowledge of English language idioms is sadly lacking. I guess I'm one of those silly people who knows 'textbook' English, but not the language as it is actually used by most people today. I'm guessing you mean you want me to explain my issue in more detail and justify my request for what must be technically difficult and/or extremely tedious documentation improvement. I hope somebody with the power to do it will fix this issue for 3.11.8 (and future versions). If you want help on 'if' or 'while', it works, but for the match statement, which isn't really very new, there's nothing in the built-in help. I realize a dedicated person (Python zealot?) can hunt down the PEPs, but really, those are not easy reading for people when English is not their first language. If Python includes built-in help as a feature, then my opinion (which I admit is probably not important to the greater Python world) is that it should at least include all of the statements of the language. I'm a teacher, and when I try to encourage my students to use match and it isn't even in the built-in help, well, they stick to if/elif/... chains. The few books on Python available here are all ancient (pre-COVID) and don't mention match either. My students let me know that they feel that if a statement isn't documented, it probably will be removed and no new code should be written that uses it. My students believe match must be deprecated, which is why it isn't documented in the built-in help system. I tried to explain that match came later than the rest of the help, and the problem is that built-in help is not considered important by some of the Python developers, so when they add/change stuff they forget to add/change the help to go with it. The response from my students, predictably, was that if match was important, it would be documented. Since it isn't documented, even the Python people who created and implemented match must feel that match is not important. It must be just an expiriment, and not a "real" statement for programming like 'if' and 'while' (which are documented). This documentation issue is a lot like the strong typing people are now pushing for Python. Everybody says we ought to use it, but have you ever seriously tried to find complete, systematic, step-by-step documentation for that which allows a newbie or an older Python coder who has always used dynamic typing to learn how to use it? Like built-in match help, I don't think such a thing exists. If it does, it's well hidden. Python gods can get by with a PEP or two, but mere mortals need a lot more. I'm not going to try and fight the battle about the type annotation documentation, but I had hoped an issue filed about the missing match statement would spur whoever implemented match to finish the job by adding appropriate built-in help to go with it. I would think adding the built-in help would be trivial, but I wonder if the built-in help is in some wierd proprietary format that nobody still on the Python core team knows how to edit? Maybe it needs some rare tool that only runs on some ancient platform and nobody's got any working hardware? Where I live (S.E. Asia) networking isn't really always reliable, so docs on some web page are often intermittently inaccessible. That's why I love Python's built-in help. However, the reality is that the built-in help just doesn't appear to get updated much, even for new statements (which should be very rare). I'm not daring to ask for wonderful examples or anything, just built-in help as good as the other control-flow statements like 'if' and 'while' have. I hope the problem gets fixed so that match statements can be considered at least as official and supported as if and while statements are. Surely I cannot be the only person whose noticed this? Then again I insist my students use only Python and a text editor without auto-complete so that they actually learn the language instead of just using some IDE with AI auto-complete. Maybe it's rare for people to actually use the built-in help nowadays? Just so this doesn't seem like an isolated issue, let's look at another example where built-in help lets my students down. Want to know what Python thinks about the 'file' concept? Well, that's another thing you cannot get from the built-in help (type file, see "No Python documentation found for 'file'."). But that's not a statement, it's something for TOPICS I guess. The built-in help just doesn't seem to get much attention any more.... And the 'open' help says "open() returns a file object...." which is why people type file, only to find that must be an error, since there is no built-in help for 'file' objects. JGH

…

________________________________________ From: Chandra Kiran G ***@***.***> Sent: Friday, January 5, 2024 2:32 AM To: python/cpython Cc: John Ham; Author Subject: Re: [python/cpython] match statement is undocumented in built-in python help (Issue #113700) Can I take this up? — Reply to this email directly, view it on GitHub<#113700 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BFDP3NBUYZY4K4GB3FH6243YM37VDAVCNFSM6AAAAABBM7OIY6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNZXGY2TCOBQGA>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[hugovk]

"Can I take this up?" means "Can I work on this?"

In this case, the answer is no because there's a duplicate issue (#105895) which already has a PR open (#105897).

What would help is trying out and reviewing that PR.

Thanks both for opening the issue and volunteering to help!

[britecrawlers]

I'm willing to try it, but how? I got to the page with this URL: 1d74ddd But then how do I download the new version to try this out on my machine? I know how to apply a patch and how to pull a specific git version of Python, but the page referenced above view diff button gives me a page that says "This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository." so I don't really know how to test this. I'm eager to try it and I hope you'll be patient and tell me the steps I need to follow, realizing I really am so ignorant I don't know how to do this on my own.

…

__________________________________ From: Hugo van Kemenade ***@***.***> Sent: Friday, January 5, 2024 5:13 PM To: python/cpython Cc: John Ham; Author Subject: Re: [python/cpython] match statement is undocumented in built-in python help (Issue #113700) "Can I take this up?" means "Can I work on this?" In this case, the answer is no because there's a duplicate issue (#105895<#105895>) which already has a PR open (#105897<#105897>). What would help is trying out and reviewing that PR. Thanks both for opening the issue and volunteering to help! — Reply to this email directly, view it on GitHub<#113700 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BFDP3NAN4PSPZG2CS4BWOMDYM7G3DAVCNFSM6AAAAABBM7OIY6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNZYGQZDQNRSGU>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[hugovk]

It's a bit tricky to test because you need to rebuild CPython (instructions here if interested). So I've tried it out and it looks good.