gh-156233: Fixing a couple of typos and a few code snippet errors in Python docs

[willy-b]

Hello Python team!

Just sending a PR to fix a couple of typos and a few code snippet errors in Python docs. No changes outside of a few .rst files used to generate content on docs.python.org are made to the Python project. These changes are not claimed to fix other unreported possible issues in the documentation, but rather just the items currently mentioned in #156233 .

---

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()

---

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".

---

I am not trying in this PR 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 in the same ticket because while a simple reordering 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 , so I will handle that separately if that is ok.

---

Let me know if there are any additional backport PRs or other language repos for the docs I need to open manually to propagate these changes (if the automated backports don't end up running for this PR).

Thanks so much!

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

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34261231 | 📁 Comparing cb57023 against main (eb08902)

  🔍 Preview build  

3 files changed

± howto/logging-cookbook.html
± howto/mro.html
± library/logging.config.html

[StanFromIreland]

I just noticed #156233 (comment), can you please fix it here as well. Indeed it's currently a SyntaxError. To fix it, move TypeVarWithDefault after the non-defaulted type parameters (that is, after TypeVarWithConstraints, and also realign the function parameters to match), since a non-default type parameter cannot follow one with a default.

    def overly_generic[
       SimpleTypeVar,
-      TypeVarWithDefault = int,
       TypeVarWithBound: int,
       TypeVarWithConstraints: (str, bytes),
+      TypeVarWithDefault = int,
       *SimpleTypeVarTuple = (int, float),
       **SimpleParamSpec = (str, bytearray),
    ](
       a: SimpleTypeVar,
-      b: TypeVarWithDefault,
-      c: TypeVarWithBound,
-      d: Callable[SimpleParamSpec, TypeVarWithConstraints],
+      b: TypeVarWithBound,
+      c: TypeVarWithConstraints,
+      d: Callable[SimpleParamSpec, TypeVarWithDefault],
       *e: SimpleTypeVarTuple,
    ): ...

[willy-b]

re: #156475 (comment)

@StanFromIreland have you tried your proposed fix with mypy ( https://github.com/python/mypy ) or any type checker that would use the type annotations?
I think there may be other issues with the existing example beyond the surface SyntaxError and for that one it may be best to send it back to the original author to have them double check and fix it to what they intended given that it may still not work with mypy (a type checker that may use the annotations) after fixing the ordering so that it runs in Python.

Note that I did NOT make any updates in this PR to that page or 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 in the upstream issue (not from me, already present, but not fixing it yet either).

Furthermore, when taking a look at how mypy is processing the kinds of type annotations in the overly_generic example, I was able to produce some outright crashes in mypy (not just it complaining that the type annotations were invalid), e.g. python/mypy#21907 for a mypy crash (complete with instructions to report it) triggered by type annotations that python itself was fine with.

All this makes me wary to bundle that one example in with a simple typo and syntax error fixup PR as there may be more updates needed to that section.

[StanFromIreland]

I think it's fine to fix the SyntaxError in this PR, as I suggested. If we need further changes they can be done in a follow up, and in any case, it's outright broken currently anyway.

[willy-b]

@StanFromIreland

OK, let's try to fix the prior author's overly_generic example SyntaxError 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 ) here,
but also see if we can make these type annotations compatible with the python type checker MyPy at the same time (since my understanding is that is the intended consumer).

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])`
   ](
      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

Thanks. If the above definition update I propose is OK, I will update the PR accordingly.

[encukou]

Apparently the suggested follow-up is too complex. I'd be fine with leaving it to a follow-up PR, so we can merge this one.

[StanFromIreland]

Sure, let's merge.

[miss-islington-app]

Thanks @willy-b for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @willy-b for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @willy-b for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-157221 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-157222 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-157223 is a backport of this pull request to the 3.15 branch.

[willy-b]

Thanks team!

A note:
Failing checks after merge are in the upstream in unrelated code, obviously, as this is a text-only change for docs.python.org content, not CPython itself, see all the failing checks for commits preceding this one: