GeezerVison is showing github.com — A few typos, grammar mistakes, and code snippet errors in the docs · Issue #156233 · python/cpython
A few typos, grammar mistakes, and code snippet errors in the docs #156233ActivityStanFromIreland commented on Aug 22, 2026 Reacted by Willy Bruns and An Long changed the title [-]A tiny grammar issue in the Python MRO documentation: "all the class" should be "all the classes"[/-] [+]Reporting few typos, grammar mistakes, code snippet errors in the Python documentation (e.g. "speciric" should be "specific" in logging-cookbook; in MRO doc "all the class" should be "all the classes", etc)[/+] on Aug 27, 2026willy-b commented on Aug 27, 2026 ContributorAuthor More actions 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 )
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.
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 )
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,
|
TypeVarWithDefault = int, |
Thanks so much! changed the title [-]Reporting few typos, grammar mistakes, code snippet errors in the Python documentation (e.g. "speciric" should be "specific" in logging-cookbook; in MRO doc "all the class" should be "all the classes", etc)[/-] [+]Reporting a few typos, grammar mistakes, code snippet errors in the Python documentation (e.g. "speciric" should be "specific" in logging-cookbook; in MRO doc "all the class" should be "all the classes", etc)[/+] on Aug 27, 2026StanFromIreland commented on Aug 27, 2026 You can open a PR with all of them. changed the title [-]Reporting a few typos, grammar mistakes, code snippet errors in the Python documentation (e.g. "speciric" should be "specific" in logging-cookbook; in MRO doc "all the class" should be "all the classes", etc)[/-] [+]A few typos, grammar mistakes, and code snippet errors in the docs[/+] on Aug 27, 2026willy-b commented on Aug 27, 2026 ContributorAuthor More actions 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
|
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. willy-b commented on Aug 29, 2026 ContributorAuthor More actions 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!). MAYANKSHARMA01010 commented on Sep 9, 2026 willy-b commented on Sep 9, 2026 ContributorAuthor More actions willy-b commented on Sep 10, 2026 ContributorAuthor More actions @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
|
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
|
**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
|
**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
|
*SimpleTypeVarTuple = (int, float), |
and
unpack it also at
.
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! encukou commented on Sep 11, 2026 (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] willy-b commented on Sep 13, 2026 ContributorAuthor More actions 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. willy-b commented on Oct 10, 2026 ContributorAuthor More actions 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! Rafiaminhaj commented on Oct 13, 2026 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!?? willy-b commented on Oct 13, 2026 ContributorAuthor More actions @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. Rafiaminhaj commented on Oct 13, 2026 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! Shalini-07-M commented on Oct 19, 2026 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! Reacted by Willy Bruns Reacted by Willy Bruns willy-b commented on Oct 22, 2026 ContributorAuthor More actions @Shalini-07-M I am no gatekeeper, per the Python documentation anyone can send PRs to fix documentation typos, see
|
We are always interested to hear ideas about improvements to the documentation. |
|
- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_ |
and
|
> 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!
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|