GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-156233: Fixing a couple of typos and a few code snippet errors in Python docs by willy-b · Pull Request #156475 · python/cpython

Conversation

@willy-b

@willy-b willy-b commented Aug 27, 2026 •
edited by bedevere-app Bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@willy-b
Fix a couple of typos and a few code snippet errors in the Python doc…
cb57023
…umentation
@willy-b
willy-b requested review from gaogaotiantian and vsajip as code owners August 27, 2026 15:27
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels Aug 27, 2026
@github-project-automation github-project-automation Bot added this to Docs PRs Aug 27, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Aug 27, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Aug 27, 2026
A few typos, grammar mistakes, and code snippet errors in the docs #156233
Open
@bedevere-app bedevere-app Bot added the awaiting review label Aug 27, 2026
@read-the-docs-community

read-the-docs-community Bot commented Aug 27, 2026

Copy link
Copy Markdown

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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

StanFromIreland
StanFromIreland approved these changes Aug 27, 2026
View reviewed changes
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting review labels Aug 27, 2026
@willy-b willy-b mentioned this pull request Aug 27, 2026
gh-156233: Fix grammar in MRO documentation #156320
Closed
2 of 4 tasks
vsajip
vsajip approved these changes Aug 27, 2026
View reviewed changes
@StanFromIreland

StanFromIreland commented Aug 28, 2026

Copy link
Copy Markdown
Member

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,
    ): ...
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@willy-b

willy-b commented Aug 31, 2026

Copy link
Copy Markdown
Contributor Author

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.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@StanFromIreland

StanFromIreland commented Sep 1, 2026

Copy link
Copy Markdown
Member

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.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@willy-b

willy-b commented Sep 2, 2026

Copy link
Copy Markdown
Contributor Author

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@StanFromIreland StanFromIreland mentioned this pull request Sep 8, 2026
gh-156233: Fix grammar in MRO documentation #157177
Closed
encukou
encukou approved these changes Sep 9, 2026
View reviewed changes

@encukou encukou left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

willy-b reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@StanFromIreland

StanFromIreland commented Sep 9, 2026

Copy link
Copy Markdown
Member

Sure, let's merge.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@StanFromIreland
StanFromIreland merged commit 9f90a86 into python:main Sep 9, 2026
40 checks passed

Uh oh!

There was an error while loading. Please reload this page.

@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Sep 9, 2026
@bedevere-app bedevere-app Bot removed the awaiting merge label Sep 9, 2026
@StanFromIreland StanFromIreland added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Sep 9, 2026
@miss-islington-app

miss-islington-app Bot commented Sep 9, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@miss-islington-app

miss-islington-app Bot commented Sep 9, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@miss-islington-app

miss-islington-app Bot commented Sep 9, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app

bedevere-app Bot commented Sep 9, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Sep 9, 2026
@bedevere-app

bedevere-app Bot commented Sep 9, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Sep 9, 2026
@bedevere-app

bedevere-app Bot commented Sep 9, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Sep 9, 2026
StanFromIreland pushed a commit that referenced this pull request Sep 9, 2026
@miss-islington @willy-b
[3.14] gh-156233: Fix typos and code snippet errors in the docs (GH-1…
11bf622
…56475) (#157221)

(cherry picked from commit 9f90a86)

Co-authored-by: Willy Bruns <[email protected]>
StanFromIreland pushed a commit that referenced this pull request Sep 9, 2026
@miss-islington @willy-b
[3.13] gh-156233: Fix typos and code snippet errors in the docs (GH-1…
865c2d4
…56475) (#157222)

(cherry picked from commit 9f90a86)

Co-authored-by: Willy Bruns <[email protected]>
hugovk pushed a commit that referenced this pull request Sep 9, 2026
@miss-islington @willy-b
[3.15] gh-156233: Fix typos and code snippet errors in the docs (GH-1…
311df8c
…56475) (#157223)

gh-156233: Fix typos and code snippet errors in the docs (GH-156475)
(cherry picked from commit 9f90a86)

Co-authored-by: Willy Bruns <[email protected]>
@willy-b

willy-b commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

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:
Screenshot_20260909_185146

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

maurycy added a commit to maurycy/cpython that referenced this pull request Sep 10, 2026
@maurycy
Merge branch 'main' into tachyon-native-callable
e028ff5
* main: (158 commits)
  pythongh-156924: Try reifying lazy imports in `ForwarRef.evaluate()` (python#156940)
  pythongh-156233: Fix typos and code snippet errors in the docs (python#156475)
  pythongh-156837: Refer to yield expressions in generator function definitions (pythonGH-156863)
  pythongh-155292: Skip updating unicodedata with mismatched interpreter (pythonGH-157066)
  pythongh-157170: Document the scope of global curses settings (pythonGH-157207)
  pythongh-155966: Correct handling of `math.tanpi` poles (python#155980)
  pythongh-157170: Restore use_env() after test_use_prescr_screen in test_curses (pythonGH-157171)
  pythongh-156910: fix deadlock in type_set_abstractmethods under free-threading (python#156948)
  pythongh-155648: Write the empty and placeholder IDLE tests (python#156260)
  pythongh-153569: centralize formatted-string state and source spans (python#156484)
  pythongh-157137: Mark the PEP 820 soft deprecations as 3.15, not `next` (python#157138)
  pythongh-152433: Use regular LoadLibrary in UWP for Windows system libs (pythonGH-156972)
  pythongh-121617: Fix Py_CLEAR() memcpy in C++: replace NULL with _Py_NULL (python#157188)
  pythongh-157135: Fix documentation errors in the `math.atan{2}pi` functions (python#157136)
  pythongh-121617: Fix Py_CLEAR() in C++: replace NULL with _Py_NULL (python#157067)
  pythongh-156774: Speed up pdb startup with asyncio guard (python#156775)
  pythongh-156109: Allow static, non-framework iOS builds (python#156110)
  pythongh-156780: Emscripten: add missing EM_JS_DEPS (python#156798)
  pythongh-152936: Make privileged functions available on Android (python#152977)
  pythongh-123018: Keep the libedit history file header when truncating (pythonGH-157165)
  ...
clin1234 pushed a commit to clin1234/cpython that referenced this pull request Sep 12, 2026
@willy-b @clin1234
pythongh-156233: Fix typos and code snippet errors in the docs (pytho…
bbffd5b
…n#156475)
@willy-b willy-b mentioned this pull request Sep 13, 2026
gh-156233: Fix the prior author's 'overly_generic' example's Python SyntaxError, and type annotation errors #157386
Open
johnslavik pushed a commit to johnslavik/cpython that referenced this pull request Sep 14, 2026
@willy-b @johnslavik
pythongh-156233: Fix typos and code snippet errors in the docs (pytho…
cdd1758
…n#156475)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vsajip vsajip vsajip approved these changes
@encukou encukou encukou approved these changes
@StanFromIreland StanFromIreland StanFromIreland approved these changes
@gaogaotiantian gaogaotiantian Awaiting requested review from gaogaotiantian gaogaotiantian is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@willy-b @StanFromIreland @vsajip @encukou
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.