Why is there no official (python.org) documentation specifying ALL Python keywords, with each being given its own page with links to other areas of documentation that describe them?

Have searched and gone through official Python documentation, I noticed two things.

First, while there is a dedicated page in the documentation included with the Python 3.11 release that lists all valid Python keywords, NOT ALL the links on the keyword page lead to a page for that specific keyword. For example, while the link for the “if” keyword does go to a description of “if” and its uses in Python syntax, the link for “from” goes to the “import” keyword page. There is no “from” keyword page. Is “import” the only use of the “from” keyword? Unknown, based on official Python documentation. Which brings me to the second thing I noticed.

Second, on the documentation page listing the keyword “as”, the link goes to the “with” keyword page, implying that “as” must be used exclusively with the “with” keyword. Yet, the whole reason I dived into the documentation this time was to see how the “as” keyword worked with the “except” keyword. Upon clicking the link to the “except” keyword, there was the keyword “as” used in the context for which I was searching. However, I wasn’t wondering what “except” did, I was wondering what “as” did, but there was no documentation of the “as” keyword or how it may (or may not) be used.

I know that there are LOTS of websites out there just begging to teach Python, but where do they get THEIR information from? Also, what guarantee is there that their information is 1) correct 2) up-to-date and 3) whole and complete? The only guarantee of that is to go straight to the source: Python.org itself and packages downloaded directly from them. As such, there should be official documentation for the official standard uses of all official Python keywords on the official Python.org site or included in the official Python documentation downloads.

In the end, I am still not certain of all the uses and contexts for the “as” keyword in Python. This is not helped by the fact that in addition to being a Python keyword, and a keyword in other programming languages, “as” is also such a common (and SHORT) word in the English language that it appears in nearly every English language page of any significant length.

1 Like

Search for 'as' on 10. Full Grammar specification — Python 3.11.0 documentation (with the single quotes) and you’ll get the places where “as” can be used (import, with, match, except)

1 Like

Also, there’s a list of keywords in the Lexical Analysis chapter of the reference.

(Ah, sorry, I saw you already found section. The full grammar spec, as linked by Shantanu, is all you should need. Sorry for the noise.)

The logical place to look would be the definition of the except statement, then.

Subkeywords like as are hard to define on their own; they get their meaning from the statement they are in. There is generally some consistency (except SomeType as e: and with SomeManager() as m: both use as to capture the object of interest), but for example, in has different meanings depending on its context, and from ... import is quite different from yield from, despite both using the word from. What sort of information would be useful on the word from? Much more helpful to look up either import or yield.

To find out exactly where a keyword COULD be used, browse the full grammar. That’s not a normal use-case though.

As others have noted, there are ways to get this information. But I’d like to ask, why do you want to know this? Documentation is always a matter of meeting people’s needs and trying to present the information in the best possible way for the majority. It seems to me that “what are all the places the as keyword can be used” is a pretty minority requirement, so it’s not surprising that it’s a bit more effort to locate that information (as opposed to, say, “what keywords are used in the except statement”).

1 Like

I think it’s a nice idea to add a page / section for each keyword.

New users that notice a new keyword for the first time might not know about grammars. If they are confused about as they might not know it is related to except. It would probably be reassuring for them to have a page that just explains there are different statements where as can appear, what they have in common or what special differences there are, and links to those statements.

For comparison:

The PHP page on keywords has a link for each keyword.
as links to foreach.
else has its own page.
static links to a page on “variable scope” with sections on static variables.

The C# page on keywords has a link for each keyword.
as has its own section.
else links to if.
static has its own page, about static variables and classes etc., and links to other constructs like using static etc.

(Luckily Python doesn’t have the static keyword. :slight_smile: )

Use the index page.
https://docs.python.org/3/genindex.html

5 Likes

As has been mentioned, this is the grammar.

https://docs.python.org/3/reference/grammar.html

Search for 'as' (with the apostrophes around it) to find every place where this keyword can be used. Extremely niche in requirement, but covered by the one place that is truly authoritative - the grammar itself.

Where is that page?

:point_down:

“Refer to the grammar” is a horrible answer. That’s not even “RTFM”, that’s “go read the sources”. Please stop telling anyone that that’s the answer.

Similarly, the list in Lexical Analysis doesn’t tell anyone anything at all about keywords.

“Refer to the index” as Serhiy mentioned is the correct answer. Here’s what appears under as:
image


To the OP, @Sunday_scour, are you able to link to the specific page that you were reading? I can’t find the page with the links you mentioned. Also, if you remember the path you followed to get there, that will help us understand how to arrange things to help people who follow the same path end up at the right place.

4 Likes

@steve.dower Serhiy’s answer is excellent, but “I want an official, guaranteed whole and complete source that tells me exactly all language constructs that use a keyword” is one of the few places where referring someone to the grammar isn’t a horrible answer.

For example, the index actually doesn’t clearly list the match statement as using as (there’s a link under one of the keyword cites, but that’s not obvious for Sunday_scour’s purposes and isn’t visible in the screenshot you post).

(Also — I listed the four places out in my answer and mentioned exactly how I found that; I’d hardly call my response RTFM)

That’s rather clearly not what they’re talking about. That’s not a dedicated page for keywords, and none of the keywords there are links (which they’re talking about).

Then that’s a documentation bug. Easily fixed - not everyone remembers to add index terms when they do their docs.

1 Like

Please see PR Docs: Add 'as, match statement' to the index by hugovk · Pull Request #99001 · python/cpython · GitHub to add “match statement” to the index under “as”:

image

3 Likes

The PR has been merged and is now live on:

4 Likes

Sorry for the delay, classes have picked up the pace and increased the work load here in the middle of the semester.

Anyway, the solution I was looking for was found in the Index page of the Python Documents site. I had not noticed it was there, and had no idea it was so robust.

The reason I was wanting to lookup Keywords (“as” in particular this time, but other Keywords later), is that I am in a class, “Introduction to Problem Solving and Programming” that uses Python as an introductory language to computer programming. In the late 1990’s and early 2000’s I was learning C and C++ after learning MS-BASIC and Pascal. So, I like to learn the keywords of a language and their LIMITS, so I can find my own solutions to problems, and find alternative, perhaps shorter, ways to do the problems in class. In this case, I saw the “as” used with the “except” keyword after having seen it used with the “with” keyword and wanted to know what other uses there were and how the uses were related.

Again, the surprisingly robust Index page was EXACTLY what I was looking for.

1 Like

BINGO! You’re the winner! Yup, I had not realized the link was there, and had NO idea it was so detailed and robust. This was EXACTLY what I was looking for. No more posts about keywords and basic language concepts! :grinning:

The only Python.org site that Google lists (on the first page of results) for my search for Python “as” keyword is: keyword — Testing for Python keywords — Python 3.11.0 documentation talking about Keyword testing.

From that page I clicked into the search box and typed as keyword and got the list:

> * [keyword](https://docs.python.org/3/library/keyword.html?highlight=keyword#module-keyword) (Python module, in `keyword` — Testing for Python keywords)
> * [ast.keyword](https://docs.python.org/3/library/ast.html?highlight=keyword#ast.keyword) (Python class, in `ast` — Abstract Syntax Trees)
> * [`dataclasses` — Data Classes](https://docs.python.org/3/library/dataclasses.html?highlight=keyword)...generated. New in version 3.10. kw_only: If true (the default value is False), then all fields will be marked as keyword-only. If a field is marked as keyword-only, then the only effect is that the __init__() parameter generated fro...
> * [`keyword` — Testing for Python keywords](https://docs.python.org/3/library/keyword.html?highlight=keyword)keyword — Testing for Python keywords Source code: Lib/keyword.py This module allows a Python program to determine if a string is a keyword or soft keyword. keyword.iskeyword(s) Return True if s is a Python keyword....
> * [1. Extending Python with C or C++](https://docs.python.org/3/extending/extending.html?highlight=keyword)...the calling convention to be used for the C function. It should normally always be METH_VARARGS or METH_VARARGS | METH_KEYWORDS; a value of 0 means that an obsolete variant of PyArg_ParseTuple() is used. When using only METH_VARARGS, the f...
> * [2. Lexical analysis](https://docs.python.org/3/reference/lexical_analysis.html?highlight=keyword)...okens). 2.2. Other tokens Besides NEWLINE, INDENT and DEDENT, the following categories of tokens exist: identifiers, keywords, literals, operators, and delimiters. Whitespace characters (other than line terminators, discussed earlier) ar...
> * [4. More Control Flow Tools](https://docs.python.org/3/tutorial/controlflow.html?highlight=keyword)...') ... else: ... print('More') ... More There can be zero or more elif parts, and the else part is optional. The keyword ‘elif’ is short for ‘else if’, and is useful to avoid excessive indentation. An if … elif … elif … sequence is...
> * [Programming FAQ](https://docs.python.org/3/faq/programming.html?highlight=keyword)...best practices” for using import in a module? Why are default values shared between objects? How can I pass optional or keyword parameters from one function to another? What is the difference between arguments and parameters? Why did changi...
> * [What’s New In Python 3.10](https://docs.python.org/3/whatsnew/3.10.html?highlight=keyword)...rd **rest is also supported. (But **_ would be redundant, so is not allowed.) Subpatterns may be captured using the as keyword: case (Point(x1, y1), Point(x2, y2) as p2): ... This binds x1, y1, x2, y2 like you would expect without the as...
> * [What’s New In Python 3.5](https://docs.python.org/3/whatsnew/3.5.html?highlight=keyword)...difflib The charset of HTML documents generated by HtmlDiff.make_file() can now be customized by using a new charset keyword-only argument. The default charset of HTML document changed from "ISO-8859-1" to "utf-8". (Contributed by Berker...
> * [What’s New In Python 3.6](https://docs.python.org/3/whatsnew/3.6.html?highlight=keyword)...ss attribute definition order is now preserved. The order of elements in **kwargs now corresponds to the order in which keyword arguments were passed to the function. DTrace and SystemTap probing support has been added. The new PYTHONMALLOC...
> * [_PyCFunctionFastWithKeywords](https://docs.python.org/3/c-api/structures.html?highlight=keyword#c._PyCFunctionFastWithKeywords) (C type, in Common Object Structures)
> * [_PyCFunctionFastWithKeywords](https://docs.python.org/3/c-api/structures.html?highlight=keyword#c._PyCFunctionFastWithKeywords) (C type, in Common Object Structures)
> * [contextlib.AbstractAsyncContextManager](https://docs.python.org/3/library/contextlib.html?highlight=keyword#contextlib.AbstractAsyncContextManager) (Python class, in `contextlib` — Utilities for `with`-statement contexts)
> * [contextlib.AsyncContextDecorator](https://docs.python.org/3/library/contextlib.html?highlight=keyword#contextlib.AsyncContextDecorator) (Python class, in `contextlib` — Utilities for `with`-statement contexts)
> * [contextlib.asynccontextmanager](https://docs.python.org/3/library/contextlib.html?highlight=keyword#contextlib.asynccontextmanager) (Python function, in `contextlib` — Utilities for `with`-statement contexts)

But no link to the index page, which I guess would be roughly equivalent to an index listing the references in an index in the word references for each entry.

Anyway, the index was what I was looking for. It should be a featured page on the Documents site as a primary entry point to the documentation pages.

The “Grammar specification” page is a fine answer, and exactly what I was ASKING for, but it turns out it was not what I needed, even when pared with the “Lexical Analysis” page. What I NEEDED for the solution to my problem was the Index page.

Although I have had Middle School classes (MS-BASIC) and High School classes (Pascal), this introductory class is my first foray into actual Computer Science. So, although I self taught C and C++, I do not have the knowledge / training to fully digest the Grammar and Lexical Analysis yet.