gh-156233: Fix the prior author's 'overly_generic' example's Python SyntaxError, and type annotation errors

[willy-b]

Thanks so much Python team for everything you do. In discussion with @StanFromIreland at #156475 (comment) and @encukou at #156233 (comment) , I have opened this PR to fix the Compound Statement documentation page's 'overly_generic' example's Python SyntaxError, and type annotation errors (ParamSpec default given as a tuple (instead of List), TypeVarTuple default specified as a plain packed tuple instead of unpacked) by prior author.

Re: the 'Compound Statement's overly_generic example on https://docs.python.org/3.16/reference/compound_stmts.html (archived as is at https://web.archive.org/web/20260913010111/https://docs.python.org/3.16/reference/compound_stmts.html ) (and docs for earlier Python versions, e.g. 3.13, 3.14, 3.15), this commit makes minimal changes specific to this example only to:

• Fix Python SyntaxError: non-default type parameter 'TypeVarWithBound' follows default type parameter for the overly_generic by moving the TypeVarwithDefault down in the list after the non-default type parameters (from

  cpython/Doc/reference/compound_stmts.rst

  Line 1852 in fe3a26f

  TypeVarWithDefault = int,

  )
• Fix MyPy error: The default argument to ParamSpec must be a list expression, ellipsis, or a ParamSpec [misc] by substituting **SimpleParamSpec=[str, bytearray] instead of the invalid **SimpleParamSpec=(str, bytearray) (fixing

  cpython/Doc/reference/compound_stmts.rst

  Line 1856 in fe3a26f

  **SimpleParamSpec = (str, bytearray),

  ) to follow guidance at e.g. https://typing.python.org/en/latest/spec/generics.html#paramspec-defaults (archived as is at https://web.archive.org/web/20260913004550/https://typing.python.org/en/latest/spec/generics.html#paramspec-defaults )
• Fix MyPy error: The default argument to TypeVarTuple must be an Unpacked tuple [misc] by replacing *SimpleTypeVarTuple = (int, float), with *SimpleTypeVarTuple = *tuple[int, float], (fixing

  cpython/Doc/reference/compound_stmts.rst

  Line 1855 in fe3a26f

  *SimpleTypeVarTuple = (int, float),

  ) to follow guidance at e.g. https://typing.python.org/en/latest/spec/generics.html#typevartuple-defaults (archived as is at https://web.archive.org/web/20260913004550/https://typing.python.org/en/latest/spec/generics.html#typevartuple-defaults )
• Fix MyPy error: TypeVarTuple 'SimpleTypeVarTuple' is only valid with an unpack [valid-type] by replacing *e: SimpleTypeVarTuple, with *e: *SimpleTypeVarTuple, to follow guidance at e.g. https://typing.python.org/en/latest/spec/generics.html#args-as-a-type-variable-tuple (archived as is at https://web.archive.org/web/20260913004550/https://typing.python.org/en/latest/spec/generics.html#args-as-a-type-variable-tuple )

See motivating discussion at #156233 (comment) and #156233 (comment) .

Should be backported from 3.16 through 3.13. Checked this example also on the lower version of Python 3.13.2 with MyPy 2.3.1 , PyreFly 1.3.0 , Pyright 1.1.414 .

(Re further backports: Note the version of the page on 3.12 did not have default type parameters but probably still needs a SEPARATE fix for

cpython/Doc/reference/compound_stmts.rst

Line 1718 in c016c25

*d: SimpleTypeVarTuple,

in that branch to unpack the tuple (in that branch SimpleTypeVarTuple doesn't have a default but is still used without unpack where an unpacked tuple is needed, so only one line needs to change)).

(Note that no AI or LLM was used in the discovery of this issue or the development of this change.)

• Issue: A few typos, grammar mistakes, and code snippet errors in the docs #156233

[willy-b]

Note that MyPy has its own bug that it cannot handle typed varargs after some other typed arguments like Callables preceding it, e.g. as I reported earlier in python/mypy#21907 , which one trying related examples may encounter (that exists prior to updating this example to use correct type annotations per the instructions at https://typing.python.org/en/latest/spec/generics.html , though I may subsequently try to fix that bug now that this example indirectly brought my attention to it ).

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34530604 | 📁 Comparing a313ee2 against main (2cd6d4b)

  🔍 Preview build  

1 file changed

± reference/compound_stmts.html

[StanFromIreland]

@willy-b, can you please try to keep comments more succinct, the description is quite noisy, making it difficult to read. You don't need to add details like the archived web page. Also, 3.12 is security-only so it won't be getting any changes.

[willy-b]

Thanks @StanFromIreland I am just trying to keep the detail that allows these items to be discovered.

---

For example, the use of a tuple to specify a ParamSpec default (not valid per typing spec, can be list with square brackets instead) being fixed here in the Compound Statements overly_generic example (currently **SimpleParamSpec = (str, bytearray), [1]) at

cpython/Doc/reference/compound_stmts.rst

Line 1856 in fe3a26f

**SimpleParamSpec = (str, bytearray),

,

came in from ca269e5#diff-8a0f115fde6769c122b771b6d0eca184c4580f7b5fabe2f0b0579c679424364f and the same mistake was made in multiple places in that same commit (lots of great work, big changes, just few mistakes as well it seems).
E.g. also at
ca269e5#diff-2001e0882d63f99ea9256cccc068969c03afa6dca739cf2ee1f5068d4534ab08R1789
(see default for ParamSpec **P in the code at that version at

cpython/Doc/library/ast.rst

Line 1789 in ca269e5

>>> print(ast.dump(ast.parse("type Alias[**P = (int, str)] = Callable[P, int]"), indent=4))

), that one other occurrence having been caught and fixed earlier by others in #127955 .

There's one other example in a unit test from that same author/group of authors commit at ca269e5#diff-04d29c98076c2d6bb75921ea9becb26a862544d39b71db87b6e354c759b9305dR580-R607 still present at

cpython/Lib/test/test_typing.py

Line 659 in f154574

P = ParamSpec('P', default=(str, int))

which also appears to introduce a class on which no test case assertions are made

cpython/Lib/test/test_typing.py

Line 664 in f154574

class A(Generic[P]): ...

, just FYI.

(They have a separate test case with type checker compatible default ParamSpec type annotation syntax as well at

cpython/Lib/test/test_typing.py

Line 742 in f154574

P = ParamSpec('P', default=[str, int])

, so the earlier ParamSpec test case using a tuple default (in violation of type annotations specification) may be obsolete/redundant in that file and worth removing.)

Also potentially useful re: type annotations throwing errors in the MyPy checker (I fix them here) in addition to the typing specification I linked in my opening comment are the MyPy test cases at https://github.com/python/mypy/blob/75b6d3c3c316d4d6c7b844da59bb0b443290a2eb/test-data/unit/check-typevar-defaults.test#L68

Thanks very much @StanFromIreland for your support in encouraging this change in the upstream issue/prior PR and helping me get the other fixes landed!

---

[1]P.S. the original version of my opening comment correctly linked the upstream's SimpleParamSpec default as it is today from prior author with a tuple instead of list type (

cpython/Doc/reference/compound_stmts.rst

Line 1856 in fe3a26f

**SimpleParamSpec = (str, bytearray),

) but I also misquoted it in that text as if I had already fixed it to a list type; I corrected my opening comment for this draft PR to be clear this change (or similar) is necessary to fix what is there.

(Note that no AI or LLM was used in the discovery of this issue or the development of this change; an LLM would admittedly likely be more succinct.)