https://github.com/python/cpython/commit/1eae1dfaf6463baa9eae1858965ec8d91b718e59
commit: 1eae1dfaf6463baa9eae1858965ec8d91b718e59
branch: 3.15
author: Inada Naoki <[email protected]>
committer: methane <[email protected]>
date: 2026-11-09T04:40:56Z
summary:
Doc: Correct built-in function and type descriptions (GH-161552)
(cherry picked from commit 3dee86d70560329437c2e774a1a89a3c57b14119)
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 2d36fc94549af10..a7a8fa35042f759 100644
--- a/Doc/builtins/functions.rst
+++ b/Doc/builtins/functions.rst
@@ -700,7 +700,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`
@@ -2405,9 +2405,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 6c4d03b36d9548a..a7dc1f624aafa08 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:
@@ -5905,8 +5904,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::
@@ -6059,8 +6059,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
@@ -6509,8 +6508,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 8d3669ca3d4a0db..3f6a9f8f90d7d47 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -1,4 +1,4 @@
-# Autogenerated by Sphinx on Sun Oct 25 18:57:09 2026
+# Autogenerated by Sphinx on Sat Nov 7 11:32:29 2026
# as part of the release process.
topics = {
@@ -3508,9 +3508,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),
](
@@ -3608,7 +3608,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:
@@ -4318,8 +4318,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()
@@ -4547,7 +4547,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.
@@ -4895,7 +4896,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.
@@ -10932,7 +10933,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
@@ -11093,18 +11101,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.
@@ -11833,7 +11841,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, /)
@@ -11862,7 +11870,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).
@@ -14314,7 +14322,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)"
@@ -14530,9 +14538,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()
@@ -14571,8 +14579,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:
@@ -14730,8 +14738,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]
