https://github.com/python/cpython/commit/3dee86d70560329437c2e774a1a89a3c57b14119
commit: 3dee86d70560329437c2e774a1a89a3c57b14119
branch: main
author: Inada Naoki <[email protected]>
committer: methane <[email protected]>
date: 2026-11-09T12:56:53+09:00
summary:
Doc: Correct built-in function and type descriptions (#161552)
files:
M Doc/builtins/functions.rst
M Doc/builtins/stdtypes.rst
M Lib/pydoc_data/topics.py
diff --git a/Doc/builtins/functions.rst b/Doc/builtins/functions.rst
index a1db1544c7bf4ed..717efe50c130744 100644
--- a/Doc/builtins/functions.rst
+++ b/Doc/builtins/functions.rst
@@ -740,7 +740,7 @@ are always available. They are listed here in alphabetical
order.
This function supports dynamic execution of Python code. *source* must be
either a string or a code object. If it is a string, the string is parsed
as
a suite of Python statements which is then executed (unless a syntax error
- occurs). [#]_ If it is a code object, it is simply executed. In all cases,
+ occurs). If it is a code object, it is simply executed. In all cases,
the code that's executed is expected to be valid as file input (see the
section :ref:`file-input` in the Reference Manual). Be aware that the
:keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return`
@@ -2470,9 +2470,3 @@ are always available. They are listed here in
alphabetical order.
.. versionchanged:: 3.9
When the command line options :option:`-E` or :option:`-I` are being
used,
the environment variable :envvar:`PYTHONCASEOK` is now ignored.
-
-.. rubric:: Footnotes
-
-.. [#] Note that the parser only accepts the Unix-style end of line convention.
- If you are reading the code from a file, make sure to use newline conversion
- mode to convert Windows or Mac-style newlines.
diff --git a/Doc/builtins/stdtypes.rst b/Doc/builtins/stdtypes.rst
index b998331cb60c5b2..7072f01e09aa250 100644
--- a/Doc/builtins/stdtypes.rst
+++ b/Doc/builtins/stdtypes.rst
@@ -1225,8 +1225,8 @@ the underlying generator function:
If the asynchronous generator function then exits gracefully, is already
closed, or raises :exc:`GeneratorExit` (by not catching the exception),
then the returned awaitable will raise a :exc:`StopIteration` exception.
- Any further awaitables returned by subsequent calls to the asynchronous
- generator will raise a :exc:`StopAsyncIteration` exception.
+ Awaitables returned by subsequent calls to :meth:`~agen.__anext__`
+ or :meth:`~agen.asend` will raise a :exc:`StopAsyncIteration` exception.
If the asynchronous generator yields a value, a :exc:`RuntimeError` is
raised by the awaitable.
@@ -2313,19 +2313,19 @@ expression support in the :mod:`re` module).
Perform a string formatting operation. The string on which this method is
called can contain literal text or replacement fields delimited by braces
- ``{}``. Each replacement field contains either the numeric index of a
- positional argument, or the name of a keyword argument. Returns a copy of
+ ``{}``. Each replacement field refers to a positional argument (numbered
+ explicitly or automatically) or a keyword argument. Returns a copy of
the string where each replacement field is replaced with the string value of
the corresponding argument. For example:
.. doctest::
- >>> "The sum of 1 + 2 is {0}".format(1+2)
- 'The sum of 1 + 2 is 3'
- >>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
+ >>> "The sum of {} + {} is {}".format(1, 2, 1+2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'
+ >>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
+ 'The sum of 1 + 2 is 3'
See :ref:`formatstrings` for a description of the various formatting options
that can be specified in format strings.
@@ -3180,7 +3180,7 @@ expression support in the :mod:`re` module).
Return a copy of the string with all the cased characters [4]_ converted to
uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s``
- contains uncased characters or if the Unicode category of the resulting
+ contains no cased characters or if the Unicode category of the resulting
character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter,
titlecase).
@@ -3537,9 +3537,8 @@ The conversion types are:
| | character in the result. | |
+------------+-----------------------------------------------------+-------+
-For floating-point formats, the result should be correctly rounded to a given
-precision ``p`` of digits after the decimal point. The rounding mode matches
-that of the :func:`round` builtin.
+For floating-point formats, the result should be correctly rounded to the
+specified precision. The rounding mode matches that of the :func:`round`
builtin.
Notes:
@@ -5928,8 +5927,9 @@ can be used interchangeably to index the same dictionary
entry.
.. seealso::
- :class:`frozendict` and :class:`types.MappingProxyType` can be used to
- create a read-only view of a :class:`dict`.
+ :class:`types.MappingProxyType` can be used to create a read-only view
+ of a :class:`dict`. :class:`frozendict` is an immutable version of
+ :class:`dict`.
.. seealso::
@@ -6082,8 +6082,7 @@ Frozen dictionaries
Similar to :meth:`dict.fromkeys`, but call again the type constructor
with an initialized :class:`frozendict` if the type is a
- :class:`frozendict` subclass or if the constructor returned a
- :class:`frozendict`.
+ :class:`frozendict` subclass.
.. versionadded:: 3.15
@@ -6532,8 +6531,8 @@ The user-exposed type for the union object can be
accessed from
.. note::
The :meth:`!__or__` method for type objects was added to support the syntax
- ``X | Y``. If a metaclass implements :meth:`!__or__`, the Union may
- override it:
+ ``X | Y``. If a metaclass implements :meth:`!__or__`, it may override
+ the default behavior of creating a union:
.. doctest::
diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index 7278c2dba6d219a..8a237ef4d5e927d 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -1,4 +1,4 @@
-# Autogenerated by Sphinx on Wed Oct 14 15:38:08 2026
+# Autogenerated by Sphinx on Sat Nov 7 11:32:29 2026
# as part of the release process.
topics = {
@@ -4112,9 +4112,9 @@ def add(self, arg: T) -> None:
def overly_generic[
SimpleTypeVar,
- TypeVarWithDefault = int,
TypeVarWithBound: int,
TypeVarWithConstraints: (str, bytes),
+ TypeVarWithDefault = int,
*SimpleTypeVarTuple = (int, float),
**SimpleParamSpec = (str, bytearray),
](
@@ -4212,7 +4212,7 @@ class Bag(typing.Generic[T]):
outside that scope. This is illustrated by this example:
@decorator
- class Bag(Base[T], arg=T): ...
+ class Bag[T](Base[T], arg=T): ...
This is equivalent to:
@@ -4959,8 +4959,8 @@ def double(x):
awaitable pdb.set_trace_async(*, header=None, commands=None)
- async version of "set_trace()". This function should be used inside
- an async function with "await".
+ Asynchronous version of "set_trace()". This function should be used
+ inside a *coroutine function* with "await". For instance:
async def f():
await pdb.set_trace_async()
@@ -5188,7 +5188,8 @@ class pdb.Pdb(completekey='tab', stdin=None, stdout=None,
skip=None, nosigint=Fa
With a *function* argument, set a break at the first executable
statement within that function. *function* can be any expression
- that evaluates to a function in the current namespace.
+ that evaluates to a function in the current namespace, or in the
+ form "package.module.function" if "package.module" is importable.
If a second argument is present, it is an expression which must
evaluate to true before the breakpoint is honored.
@@ -5536,7 +5537,7 @@ class pdb.Pdb(completekey='tab', stdin=None, stdout=None,
skip=None, nosigint=Fa
List or jump between chained exceptions.
- When using "pdb.pm()" or "Pdb.post_mortem(...)" with a chained
+ When using "pdb.pm()" or "pdb.post_mortem(...)" with a chained
exception instead of a traceback, it allows the user to move
between the chained exceptions using "exceptions" command to list
exceptions, and "exceptions <number>" to switch to that exception.
@@ -11742,7 +11743,14 @@ class is used in a class pattern with positional
arguments, each
str.capitalize()
Return a copy of the string with its first character capitalized
- and the rest lowercased.
+ and the rest lowercased. For example:
+
+ >>> 'PYTHON IS AMAZING'.capitalize()
+ 'Python is amazing'
+ >>> 'Njemačka starts With a non-ASCII digraph'.capitalize()
+ 'Njemačka starts with a non-ascii digraph'
+
+ See also "title()".
Changed in version 3.8: The first character is now put into
titlecase rather than uppercase. This means that characters like
@@ -11903,18 +11911,18 @@ class is used in a class pattern with positional
arguments, each
Perform a string formatting operation. The string on which this
method is called can contain literal text or replacement fields
- delimited by braces "{}". Each replacement field contains either
- the numeric index of a positional argument, or the name of a
+ delimited by braces "{}". Each replacement field refers to a
+ positional argument (numbered explicitly or automatically) or a
keyword argument. Returns a copy of the string where each
replacement field is replaced with the string value of the
corresponding argument. For example:
- >>> "The sum of 1 + 2 is {0}".format(1+2)
- 'The sum of 1 + 2 is 3'
- >>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
+ >>> "The sum of {} + {} is {}".format(1, 2, 1+2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'
+ >>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
+ 'The sum of 1 + 2 is 3'
See Format string syntax for a description of the various
formatting options that can be specified in format strings.
@@ -12644,7 +12652,7 @@ class is used in a class pattern with positional
arguments, each
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."
- See also "istitle()".
+ See also "istitle()" and "capitalize()".
str.translate(table, /)
@@ -12673,7 +12681,7 @@ class is used in a class pattern with positional
arguments, each
Return a copy of the string with all the cased characters [4]
converted to uppercase. Note that "s.upper().isupper()" might be
- "False" if "s" contains uncased characters or if the Unicode
+ "False" if "s" contains no cased characters or if the Unicode
category of the resulting character(s) is not “Lu” (Letter,
uppercase), but e.g. “Lt” (Letter, titlecase).
@@ -14221,7 +14229,8 @@ def foo():
* "__name__" is the function’s name. See "function.__name__".
-* "__self__" is set to "None" (but see the next item).
+* "__self__" is the module object the function was defined in or
+ "None" if unavailable.
* "__module__" is the name of the module the function was defined in
or "None" if unavailable. See "function.__module__".
@@ -15124,7 +15133,7 @@ class dict(iterable, /, **kwargs)
"{'jack': 4098, 'sjoerd': 4127}" or "{4098: 'jack', 4127:
'sjoerd'}"
- * Use a dict comprehension: "{}", "{x: x ** 2 for x in range(10)}"
+ * Use a dict comprehension: "{x: x ** 2 for x in range(10)}"
* Use the type constructor: "dict()", "dict([('foo', 100), ('bar',
200)])", "dict(foo=100, bar=200)"
@@ -15340,9 +15349,9 @@ class dict(iterable, /, **kwargs)
Return a new view of the dictionary’s values. See the
documentation of view objects.
- An equality comparison between one "dict.values()" view and
- another will always return "False". This also applies when
- comparing "dict.values()" to itself:
+ An equality comparison between two distinct "dict.values()"
+ views will always return "False", even for views of the same
+ dictionary:
>>> d = {'a': 1}
>>> d.values() == d.values()
@@ -15381,8 +15390,8 @@ class dict(iterable, /, **kwargs)
See also:
- "frozendict" and "types.MappingProxyType" can be used to create a
- read-only view of a "dict".
+ "types.MappingProxyType" can be used to create a read-only view
+ of a "dict". "frozendict" is an immutable version of "dict".
See also:
@@ -15540,8 +15549,7 @@ class frozendict(iterable, /, **kwargs)
Similar to "dict.fromkeys()", but call again the type
constructor with an initialized "frozendict" if the type is a
- "frozendict" subclass or if the constructor returned a
- "frozendict".
+ "frozendict" subclass.
Added in version 3.15.
''',
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
