A few typos, grammar mistakes, and code snippet errors in the docs

Documentation

(UPDATE: Added multiple suspected errors in code snippets in the documentation and another typo to this initial report in #156233 (comment) as I was OK'd to open a PR but encouraged to expand the scope before sending a fix.)

Hello Python team,

this is just a typo so I know an issue is not required, but I hope you won't mind if I open one in case someone else wants to include it in a larger typo cleanup PR they are already doing (if no one picks it up after some time and I don't find other typos, I can send a PR).

In the latest version of https://docs.python.org/3/howto/mro.html#python-2-3-mro (archived as is at https://web.archive.org/web/20260822145356/https://docs.python.org/3/howto/mro.html#python-2-3-mro )

In the sentence

Then repeat the operation until all the class are removed or it is impossible to find good heads.

it seems "all the class" should be "all the classes".

Thanks so much!

Linked PRs

@willy-b

@willy-b would you like to open a PR?

Here is another typo and what appear to be a few minor mistakes in some of the code snippet examples in the 3.16 version of the Python documentation (I confirmed the latest code does not have these fixed yet).

On https://docs.python.org/3.16/howto/logging-cookbook.html (archived as is at https://web.archive.org/web/20260827054643/https://docs.python.org/3.16/howto/logging-cookbook.html )

In the sentence

cpython/Doc/howto/logging-cookbook.rst

Line 3923 in fe3a26f

to the log). Nevertheless, the above should be adaptable to your speciric needs. With

Nevertheless, the above should be adaptable to your speciric needs.

"speciric" should be "specific".

On https://docs.python.org/3.16/library/logging.config.html (archived as is at https://web.archive.org/web/20260827041728/https://docs.python.org/3.16/library/logging.config.html )

In the example

You can also specify a special key '.' whose value is a mapping of attribute names to values. If found, the specified attributes will be set on the user-defined object before it is returned. Thus, with the following configuration:

{
'()' : 'my.package.customFormatterFactory',
'bar' : 'baz',
'spam' : 99.9,
'answer' : 42,
'.' {
  'foo': 'bar',
  'baz': 'bozz'
}
}

It seems the key "." is missing a ":" before its value to avoid ':' expected after dictionary key (<string>, line 6)' for the above.

cpython/Doc/library/logging.config.rst

Line 558 in fe3a26f

'.' {

On https://docs.python.org/3.16/library/pdb.html#pdbcommand-exceptions (archived as is at https://web.archive.org/web/20260827042203/https://docs.python.org/3.16/library/pdb.html#pdbcommand-exceptions )

nit: In the example

def out():
   try:
       middle()
   except Exception as e:
       raise ValueError("reraise middle() error") from e

def middle():
   try:
       return inner(0)
   except Exception as e:
       raise ValueError("Middle fail")

def inner(x):
   1 / x

out()

There is an extra space on the beginning of the last line out(), which prevents the snippet from running exactly as is if copy-pasted.

cpython/Doc/library/pdb.rst

Line 837 in fe3a26f

out()

On https://docs.python.org/3.16/reference/compound_stmts.html (archived as is at https://web.archive.org/web/20260827044953/https://docs.python.org/3.16/reference/compound_stmts.html )

In the example
```
def overly_generic[
  SimpleTypeVar,
  TypeVarWithDefault = int,
  TypeVarWithBound: int,
  TypeVarWithConstraints: (str, bytes),
  *SimpleTypeVarTuple = (int, float),
  **SimpleParamSpec = (str, bytearray),
](
  a: SimpleTypeVar,
  b: TypeVarWithDefault,
  c: TypeVarWithBound,
  d: Callable[SimpleParamSpec, TypeVarWithConstraints],
  *e: SimpleTypeVarTuple,
): ...
```
(noting one must add pass to the end of the above instead of ... before attempting to execute it, but I quoted it as it is)

it seems the arguments are possibly in a disallowed order, as I observe the error
non-default type parameter 'TypeVarWithBound' follows default type parameter,

cpython/Doc/reference/compound_stmts.rst

Line 1852 in fe3a26f

TypeVarWithDefault = int,

Thanks so much!

You can open a PR with all of them.

Note earlier this AM I sent #156475 (which has been partially approved, thanks(!), but is not merged yet) to fix most of the items I reported here.

Note that I did NOT make any updates in that PR to try to fix the non-default type parameter 'TypeVarWithBound' follows default type parameter for the overly_generic example on https://docs.python.org/3.16/reference/compound_stmts.html yet ( caused by

cpython/Doc/reference/compound_stmts.rst

Line 1852 in fe3a26f

TypeVarWithDefault = int,

) which I discovered and reported as part of my last comment in this issue (not from me, already present, but not fixing it yet either) because while a simple reordering of the type parameters fixes that to be runnable again in Python there may be other updates required for that example to work properly with type checkers like mypy.

Investigating the overly_generic example above has led me to file at least one ticket (the mypy tool itself crashed on a related example and instructed me to file a ticket), python/mypy#21907 with mypy which there is a PR out for (thanks to the mypy team and community!).

@StanFromIreland

@StanFromIreland @willy-b is this issue still active

@MAYANKSHARMA01010

@MAYANKSHARMA01010 yes waiting for go, no go on proposed fix to a tutorial in comment #156475 (comment) from @StanFromIreland

Merge branch 'main' into tachyon-native-callable

@encukou

@encukou thanks, but it seems inconsistent with other parts of the Python documentation as well
(e.g. ParamSpec is mentioned as able to be substituted with a square bracket list (not parenthesis tuple) in Python side documentation at

cpython/Doc/library/typing.rst

Line 674 in 092c896

    
           to this is that a list of types can be used to substitute a :class:`ParamSpec`::

, whereas in the overly_generic example reported here, inconsistent with everywhere else in CPython I see and violating MyPy type checker rules for type annotations (error: The default argument to ParamSpec must be a list expression, ellipsis, or a ParamSpec )
the ParamSpec is shown substituted by a tuple, by the prior author

cpython/Doc/reference/compound_stmts.rst

Line 1856 in fe3a26f

**SimpleParamSpec = (str, bytearray),

)

so especially now that the other PR #156475 for the easier parts of this ticket landed, why not fix the overly_generic example for MyPy as well?

Here is my proposal (I had posted in it in the previous PR where we decided to separate it out, but it should also be in this issue):

For the overly_generic example (which is not supposed to intentionally fail the type checker), after fixing the Python SyntaxError due to bad type parameter ordering, we can address each MyPy-side complaint as follows:

To fix:

error: The default argument to ParamSpec must be a list expression, ellipsis, or a ParamSpec  [misc]

how about we use **SimpleParamSpec=[str, bytearray] with square brackets instead of parentheses used by the prior author

cpython/Doc/reference/compound_stmts.rst

Line 1856 in fe3a26f

**SimpleParamSpec = (str, bytearray),

(which are ok in Python but do not seem to be ok with MyPy the type checker the type annotations are for)? (tuples are not allowed, but lists are)

And to avoid

error: The default argument to TypeVarTuple must be an Unpacked tuple  [misc]
error: TypeVarTuple "SimpleTypeVarTuple" is only valid with an unpack  [valid-type]

we can unpack the TypeVarTuple as *tuple[int, float] (using * or Unpack[...]) instead of

cpython/Doc/reference/compound_stmts.rst

Line 1855 in fe3a26f

*SimpleTypeVarTuple = (int, float),

and
unpack it also at

cpython/Doc/reference/compound_stmts.rst

Line 1862 in fe3a26f

*e: SimpleTypeVarTuple,

.

With both those changes as well as moving TypeVarWithDefault after the type arguments without defaults (the SyntaxError by the article author), see below:

from typing import *

def overly_generic[
      SimpleTypeVar,
      TypeVarWithBound: int,
      TypeVarWithConstraints: (str, bytes), # originally used for return value type of callable param, I am proposing to leave that as is
      TypeVarWithDefault = int,
      *SimpleTypeVarTuple = *tuple[int, float], # match https://peps.python.org/pep-0646/
      # this is a valid format for declaring a ParamSpec as a generic type parameter
      **SimpleParamSpec = [str, bytearray], # same as `ParamSpec('SimpleParamSpec', default=[str, bytearray])`, NOT `(str, bytearray)`  as prior author had.
   ](
      a: SimpleTypeVar,
      b: TypeVarWithBound,
      c: Callable[SimpleParamSpec, TypeVarWithConstraints], # not the same ordering as StanFromIreland's suggestion, but rather matches the type argument use in the original example; the Callable parameter return type IS the example for TypeVarWithConstraints, though I am fine to change the parameter (not type parameter) ordering however you want
      d: TypeVarWithDefault, # this can be TypeVarWithDefault in the reordered example to match the movement of TypeVarWithDefault to the 4th position for readability
      *e: *SimpleTypeVarTuple, # needs a star/unpack here on the right-hand-side for mypy, I think
      # note that mypy appears to have a bug that it cannot yet handle typed varargs after some other typed arguments like Callables preceding it, e.g. https://github.com/python/mypy/issues/21907 , which one trying related examples may encounter
   ): pass

Some related checks we can do in MyPy are:

def some_fun_returns_str(a: str, b: bytearray) -> str:
    return 'abc'

def some_bad_param_fun_returns_str(a: int, b: bytearray) -> str:
    return 'abc'

def some_fun_returns_bytes(a: str, b: bytearray) -> bytes:
    return b'abc'

def some_fun_returns_int(a: str, b: bytearray) -> int:
    return 1

overly_generic('a', 1, some_fun_returns_str, 2)
overly_generic('a', 1, some_fun_returns_bytes, 2)

# error: Value of type variable "TypeVarWithConstraints" of "overly_generic" cannot be "int"  [type-var]
# overly_generic[('a', 1, some_fun_returns_int, 2)

# error: Value of type variable "TypeVarWithBound" of "overly_generic" cannot be "str"  [type-var]
# overly_generic('a', '1', some_fun_returns_str, 2)

# If we force the ParamSpec of the Callable argument
# to be the default of SimpleParamSpec
# e.g. `c: Callable[[str, bytearray], TypeVarWithConstraints]`
# then we can see that properly types the arguments to the callable, and we can't pass a function that takes an int and a bytearray, only a str and bytearray:
#
# error: Argument 3 to "overly_generic" has incompatible type "Callable[[int, bytearray], str]"; expected "Callable[[str, bytearray], str]"  [arg-type]
# overly_generic('a', 1, some_bad_param_fun_returns_str, 2) # will fail mypy if SimpleParamSpec replaced with [str, bytearray]

# we can also show that an unpacked tuple (using `*` or `Unpack[...]`) is the expected type for `*e` varargs (like `*args`):
def example_fun_with_typed_varargs(
      *e: *tuple[int, float],
   ): pass

example_fun_with_typed_varargs(1, 1.1) # OK

# error: Argument 1 to "example_fun_with_typed_varargs" has incompatible type "float"; expected "int"  [arg-type]
# example_fun_with_typed_varargs(1.2, 1.1) # mypy rejects

# note that mypy has a bug that it cannot handle typed varargs after some other typed arguments like Callables preceding it, e.g. https://github.com/python/mypy/issues/21907 , which one trying related examples may encounter
# that is not caused by anything particular to the example we are proposing to put here

What do you think? Thanks!

(Docs for the typing module are specifically for static typing; there I'd expect type checkers to pass.)

Anyway, your suggestion looks good, do you want to turn it into a PR?
Consider also matching the arguments to the type examples one-to-one:

c: TypeVarWithConstraints
...
f: Callable[SimpleParamSpec, None]

pythongh-156233: Fix typos and code snippet errors in the docs (pytho…

@encukou

Thanks @encukou I sent #157386 , let me know what you think! To make a minimal change fixing the Python SyntaxError and the MyPy type annotation errors I did not change the Callable's return type but left the use of the constrained generic type as is in the PR as that part of the original author's vision can be preserved.

pythongh-156233: Fix typos and code snippet errors in the docs (pytho…

@encukou

FYI @encukou the crash I had found in MyPy (official type checker) related to cases similar to those in the overly_generic documentation example was resolved in python/mypy#21907 by that team (I had essentially the same approach in my fork and discussion in issue but happy the team did the PR there as did not want to create side effects and I don't claim team-level knowledge of that code).

However, the PR to update the documentation as we discussed remains at #157386 (pending review; now safer as the MyPy bug one might encounter exploring it has been resolved). Let me know if you have any feedback (no pressure, no rush!). Thanks!

Hi! I'm Rafia Minhaj, a final-year B.Tech CSE student with experience in Python, FastAPI, and open source contributions (GSSoC 2026 Top 1%, Hacktoberfest 2026). I would love to work on this issue and help fix the typos, grammar mistakes, and code snippet errors in the docs. Could you please let me know if this issue is still available? I'll get started right away. Thank you!??

@Rafiaminhaj

@Rafiaminhaj you can help review the PR already available for this #157386
and/or you can give me your email and I can share these items I spend time to find with you (as in this ticket or e.g. a different batch I sent up a fix for in #157879 , also pending review ) in advance of posting them to see if you want them. In that case I could either post them with you mentioned as working on it or you could work on it in advance and just send your fixes.

@willy-b

Hi @willy-b

Thank you for the opportunity! I'd be happy to help review PR #157386 and contribute to the CPython documentation improvements.

I'll go through the changes carefully and share my feedback. I'd also be glad to work on the additional documentation issues you mentioned.

Thanks again for your guidance!

Hi! I'm a beginner interested in making my first contribution to CPython. I'd be happy to help fix a small documentation typo or error. Could you suggest one of the additional documentation issues that hasn't been claimed yet? Thank you!

@Shalini-07-M

@Shalini-07-M I am no gatekeeper, per the Python documentation anyone can send PRs to fix documentation typos, see

cpython/Doc/improve-page.rst

Line 43 in c1c4c18

We are always interested to hear ideas about improvements to the documentation.

cpython/Doc/improve-page.rst

Line 64 in c1c4c18

    
           - You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_

and

cpython/.github/ISSUE_TEMPLATE/documentation.yml

Line 9 in c1c4c18

    
                   > Trivial changes (for example typos) don’t require an issue before opening a PR.

for example.

However, if you give me your contact info then when I find some more I can send some to you that you can send a patch for, if that helps you get started. It can take a lot of reading or searching to find typos or potential items to fix (spending lots of time reading documentation is of course advised in any case), and I would be happy to give you a boost if I can.

Thanks!

Navigation Menu

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

Documentation

Linked PRs

5 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Documentation

Linked PRs

Activity

StanFromIreland commented on Aug 22, 2026

willy-b commented on Aug 27, 2026

StanFromIreland commented on Aug 27, 2026

willy-b commented on Aug 27, 2026

willy-b commented on Aug 29, 2026

MAYANKSHARMA01010 commented on Sep 9, 2026

willy-b commented on Sep 9, 2026

5 remaining items

willy-b commented on Sep 10, 2026

encukou commented on Sep 11, 2026

willy-b commented on Sep 13, 2026

willy-b commented on Oct 10, 2026

Rafiaminhaj commented on Oct 13, 2026

willy-b commented on Oct 13, 2026

Rafiaminhaj commented on Oct 13, 2026

Shalini-07-M commented on Oct 19, 2026

willy-b commented on Oct 22, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions