Possible inaccuracies in expression_stmt syntax documentation (3.14.4)

Documentation
1

I think I’ve found some issues with how expression syntax is described in the official Python documentation for version 3.14.4.

According to the docs:

expression_stmt: starred_expression

And starred_expression is defined as:

starred_expression:       "*" or_expr | expression

However, I’m seeing several mismatches with the actual language syntax.

  1. An expression like *[1,2] fits the starred_expression grammar (since [1,2] is an or_expr), but it is not a syntactically valid statement in Python.

  2. An expression like 1,2 is a perfectly valid statement in Python, but I can’t see how it matches starred_expression as described in the docs.

  3. As I understand, parenthesized expressions like (2+3) are covered by parenth_form, which is defined as:

    parenth_form: "(" [starred_expression] ")"

    But similar to point 2, I don’t see how a perfectly valid expression like (1,2) fits this grammar.

  4. Moreover, an expression like (x:=1) also doesn’t seem to be covered, since assignment_expression is not a subset of expression according to the grammar rules presented.

I believe parenth_form should reference flexible_expression_list instead of starred_expression.

Similarly, expression_stmt and related rules should reference something analogous to yield_list:

yield_list: expression_list | starred_expression "," [starred_expression_list]

Am I missing something here? I’d appreciate any clarification.

1 Like
2

You should probably look at the full grammar spec for the definitive grammar. There do appear to be some discrepancies. In the case of (x:=1), this comes from simple_stmt → star_expressions → expression → disjunction → … → primary → atom → group → '(' named_expression ')', where “group” appears to be what handles the things (genexps and assignment expressions) that have to be parenthesised at the top level. The section on atoms doesn’t mention this group item.

For (2), you have statement → simple_stmts → simple_stmt->star_expressions. As you say, expression_stmt: starred_expression` seems inaccurate here.

(3) comes from atom → group via named_expression → expression !‘:=’` (the last item is a negative lookahead).

As for (1), I think the syntax error there comes from a processing step after the initial parse based on the grammar. You can see this with ast.parse:

>>> ast.parse("*[1,2]")
Module(body=[Expr(value=Starred(value=List(...), ctx=Load(...)))], type_ignores=[])

A documentation PR cleaning up some of the discrepancies between the narrative discussion of the grammar and the formal spec might be welcome. But I suspect there’s a bit of a balancing act there, between being formally correct and being readable. I’ll leave judging what’s appropriate there to the documentation specialists…

2 Likes
3

Thanks for the clarification.

Regarding point 1, you’re right — the error occurs not at the syntax level but during the semantic analysis phase. That was somewhat unexpected for me, but it’s probably a topic for a separate discussion.

As for the remaining cases, I’ll try to prepare a PR in the near future to address the discrepancies I mentioned.

1 Like
4

Pull request