gh-91485: Doc: Using Python syntax to document builtin Python functions. (GH-96579)

1 files changed, 84 insertions, 65 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 93c9f4a..8108c98 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -54,14 +54,14 @@ are always available.  They are listed here in alphabetical order.
 .. |func-bytearray| replace:: ``bytearray()``
 .. |func-bytes| replace:: ``bytes()``
 
-.. function:: abs(x)
+.. function:: abs(x, /)
 
    Return the absolute value of a number.  The argument may be an
    integer, a floating point number, or an object implementing :meth:`__abs__`.
    If the argument is a complex number, its magnitude is returned.
 
 
-.. function:: aiter(async_iterable)
+.. function:: aiter(async_iterable, /)
 
    Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
    Equivalent to calling ``x.__aiter__()``.
@@ -70,7 +70,7 @@ are always available.  They are listed here in alphabetical order.
 
    .. versionadded:: 3.10
 
-.. function:: all(iterable)
+.. function:: all(iterable, /)
 
    Return ``True`` if all elements of the *iterable* are true (or if the iterable
    is empty).  Equivalent to::
@@ -82,7 +82,8 @@ are always available.  They are listed here in alphabetical order.
           return True
 
 
-.. awaitablefunction:: anext(async_iterator[, default])
+.. awaitablefunction:: anext(async_iterator, /)
+                       anext(async_iterator, default, /)
 
    When awaited, return the next item from the given :term:`asynchronous
    iterator`, or *default* if given and the iterator is exhausted.
@@ -97,7 +98,7 @@ are always available.  They are listed here in alphabetical order.
 
    .. versionadded:: 3.10
 
-.. function:: any(iterable)
+.. function:: any(iterable, /)
 
    Return ``True`` if any element of the *iterable* is true.  If the iterable
    is empty, return ``False``.  Equivalent to::
@@ -109,7 +110,7 @@ are always available.  They are listed here in alphabetical order.
           return False
 
 
-.. function:: ascii(object)
+.. function:: ascii(object, /)
 
    As :func:`repr`, return a string containing a printable representation of an
    object, but escape the non-ASCII characters in the string returned by
@@ -117,7 +118,7 @@ are always available.  They are listed here in alphabetical order.
    similar to that returned by :func:`repr` in Python 2.
 
 
-.. function:: bin(x)
+.. function:: bin(x, /)
 
    Convert an integer number to a binary string prefixed with "0b". The result
    is a valid Python expression. If *x* is not a Python :class:`int` object, it
@@ -139,7 +140,7 @@ are always available.  They are listed here in alphabetical order.
    See also :func:`format` for more information.
 
 
-.. class:: bool([x])
+.. class:: bool(x=False, /)
 
    Return a Boolean value, i.e. one of ``True`` or ``False``.  *x* is converted
    using the standard :ref:`truth testing procedure <truth>`.  If *x* is false
@@ -172,7 +173,9 @@ are always available.  They are listed here in alphabetical order.
    .. versionadded:: 3.7
 
 .. _func-bytearray:
-.. class:: bytearray([source[, encoding[, errors]]])
+.. class:: bytearray(source=b'')
+           bytearray(source, encoding)
+           bytearray(source, encoding, errors)
    :noindex:
 
    Return a new array of bytes.  The :class:`bytearray` class is a mutable
@@ -202,7 +205,9 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-bytes:
-.. class:: bytes([source[, encoding[, errors]]])
+.. class:: bytes(source=b'')
+           bytes(source, encoding)
+           bytes(source, encoding, errors)
    :noindex:
 
    Return a new "bytes" object which is an immutable sequence of integers in
@@ -217,7 +222,7 @@ are always available.  They are listed here in alphabetical order.
    See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`.
 
 
-.. function:: callable(object)
+.. function:: callable(object, /)
 
    Return :const:`True` if the *object* argument appears callable,
    :const:`False` if not.  If this returns ``True``, it is still possible that a
@@ -230,7 +235,7 @@ are always available.  They are listed here in alphabetical order.
       in Python 3.2.
 
 
-.. function:: chr(i)
+.. function:: chr(i, /)
 
    Return the string representing a character whose Unicode code point is the
    integer *i*.  For example, ``chr(97)`` returns the string ``'a'``, while
@@ -358,7 +363,8 @@ are always available.  They are listed here in alphabetical order.
       support for top-level ``await``, ``async for``, and ``async with``.
 
 
-.. class:: complex([real[, imag]])
+.. class:: complex(real=0, imag=0)
+           complex(string, /)
 
    Return a complex number with the value *real* + *imag*\*1j or convert a string
    or number to a complex number.  If the first parameter is a string, it will
@@ -391,7 +397,7 @@ are always available.  They are listed here in alphabetical order.
       :meth:`__float__` are not defined.
 
 
-.. function:: delattr(object, name)
+.. function:: delattr(object, name, /)
 
    This is a relative of :func:`setattr`.  The arguments are an object and a
    string.  The string must be the name of one of the object's attributes.  The
@@ -402,8 +408,8 @@ are always available.  They are listed here in alphabetical order.
 
 .. _func-dict:
 .. class:: dict(**kwarg)
-           dict(mapping, **kwarg)
-           dict(iterable, **kwarg)
+           dict(mapping, /, **kwarg)
+           dict(iterable, /, **kwarg)
    :noindex:
 
    Create a new dictionary.  The :class:`dict` object is the dictionary class.
@@ -413,7 +419,8 @@ are always available.  They are listed here in alphabetical order.
    :class:`tuple` classes, as well as the :mod:`collections` module.
 
 
-.. function:: dir([object])
+.. function:: dir()
+              dir(object, /)
 
    Without arguments, return the list of names in the current local scope.  With an
    argument, attempt to return a list of valid attributes for that object.
@@ -469,7 +476,7 @@ are always available.  They are listed here in alphabetical order.
       class.
 
 
-.. function:: divmod(a, b)
+.. function:: divmod(a, b, /)
 
    Take two (non-complex) numbers as arguments and return a pair of numbers
    consisting of their quotient and remainder when using integer division.  With
@@ -505,7 +512,7 @@ are always available.  They are listed here in alphabetical order.
 
 .. _func-eval:
 
-.. function:: eval(expression[, globals[, locals]])
+.. function:: eval(expression, /, globals=None, locals=None)
 
    The arguments are a string and optional globals and locals.  If provided,
    *globals* must be a dictionary.  If provided, *locals* can be any mapping
@@ -556,7 +563,7 @@ are always available.  They are listed here in alphabetical order.
 
 .. index:: builtin: exec
 
-.. function:: exec(object[, globals[, locals]], *, closure=None)
+.. function:: exec(object, globals=None, locals=None, /, *, closure=None)
 
    This function supports dynamic execution of Python code. *object* must be
    either a string or a code object.  If it is a string, the string is parsed as
@@ -612,7 +619,7 @@ are always available.  They are listed here in alphabetical order.
       Added the *closure* parameter.
 
 
-.. function:: filter(function, iterable)
+.. function:: filter(function, iterable, /)
 
    Construct an iterator from those elements of *iterable* for which *function*
    returns true.  *iterable* may be either a sequence, a container which
@@ -629,7 +636,7 @@ are always available.  They are listed here in alphabetical order.
    elements of *iterable* for which *function* returns false.
 
 
-.. class:: float([x])
+.. class:: float(x=0.0, /)
 
    .. index::
       single: NaN
@@ -697,7 +704,7 @@ are always available.  They are listed here in alphabetical order.
    single: __format__
    single: string; format() (built-in function)
 
-.. function:: format(value[, format_spec])
+.. function:: format(value, format_spec="", /)
 
    Convert a *value* to a "formatted" representation, as controlled by
    *format_spec*.  The interpretation of *format_spec* will depend on the type
@@ -720,7 +727,7 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-frozenset:
-.. class:: frozenset([iterable])
+.. class:: frozenset(iterable=set(), /)
    :noindex:
 
    Return a new :class:`frozenset` object, optionally with elements taken from
@@ -732,7 +739,8 @@ are always available.  They are listed here in alphabetical order.
    module.
 
 
-.. function:: getattr(object, name[, default])
+.. function:: getattr(object, name, /)
+              getattr(object, name, default, /)
 
    Return the value of the named attribute of *object*.  *name* must be a string.
    If the string is the name of one of the object's attributes, the result is the
@@ -756,7 +764,7 @@ are always available.  They are listed here in alphabetical order.
    regardless of where the function is called.
 
 
-.. function:: hasattr(object, name)
+.. function:: hasattr(object, name, /)
 
    The arguments are an object and a string.  The result is ``True`` if the
    string is the name of one of the object's attributes, ``False`` if not. (This
@@ -764,7 +772,7 @@ are always available.  They are listed here in alphabetical order.
    raises an :exc:`AttributeError` or not.)
 
 
-.. function:: hash(object)
+.. function:: hash(object, /)
 
    Return the hash value of the object (if it has one).  Hash values are
    integers.  They are used to quickly compare dictionary keys during a
@@ -777,7 +785,8 @@ are always available.  They are listed here in alphabetical order.
       truncates the return value based on the bit width of the host machine.
       See :meth:`__hash__` for details.
 
-.. function:: help([object])
+.. function:: help()
+              help(request)
 
    Invoke the built-in help system.  (This function is intended for interactive
    use.)  If no argument is given, the interactive help system starts on the
@@ -798,7 +807,7 @@ are always available.  They are listed here in alphabetical order.
       signatures for callables are now more comprehensive and consistent.
 
 
-.. function:: hex(x)
+.. function:: hex(x, /)
 
    Convert an integer number to a lowercase hexadecimal string prefixed with
    "0x". If *x* is not a Python :class:`int` object, it has to define an
@@ -830,7 +839,7 @@ are always available.  They are listed here in alphabetical order.
       :meth:`float.hex` method.
 
 
-.. function:: id(object)
+.. function:: id(object, /)
 
    Return the "identity" of an object.  This is an integer which
    is guaranteed to be unique and constant for this object during its lifetime.
@@ -842,7 +851,8 @@ are always available.  They are listed here in alphabetical order.
    .. audit-event:: builtins.id id id
 
 
-.. function:: input([prompt])
+.. function:: input()
+              input(prompt, /)
 
    If the *prompt* argument is present, it is written to standard output without
    a trailing newline.  The function then reads a line from input, converts it
@@ -868,8 +878,8 @@ are always available.  They are listed here in alphabetical order.
       with the result after successfully reading input.
 
 
-.. class:: int([x])
-           int(x, base=10)
+.. class:: int(x=0, /)
+           int(x, /, base=10)
 
    Return an integer object constructed from a number or string *x*, or return
    ``0`` if no arguments are given.  If *x* defines :meth:`__int__`,
@@ -920,7 +930,7 @@ are always available.  They are listed here in alphabetical order.
       See the :ref:`integer string conversion length limitation
       <int_max_str_digits>` documentation.
 
-.. function:: isinstance(object, classinfo)
+.. function:: isinstance(object, classinfo, /)
 
    Return ``True`` if the *object* argument is an instance of the *classinfo*
    argument, or of a (direct, indirect, or :term:`virtual <abstract base
@@ -937,7 +947,7 @@ are always available.  They are listed here in alphabetical order.
       *classinfo* can be a :ref:`types-union`.
 
 
-.. function:: issubclass(class, classinfo)
+.. function:: issubclass(class, classinfo, /)
 
    Return ``True`` if *class* is a subclass (direct, indirect, or :term:`virtual
    <abstract base class>`) of *classinfo*.  A
@@ -951,7 +961,8 @@ are always available.  They are listed here in alphabetical order.
       *classinfo* can be a :ref:`types-union`.
 
 
-.. function:: iter(object[, sentinel])
+.. function:: iter(object, /)
+              iter(object, sentinel, /)
 
    Return an :term:`iterator` object.  The first argument is interpreted very
    differently depending on the presence of the second argument. Without a
@@ -978,7 +989,7 @@ are always available.  They are listed here in alphabetical order.
               process_block(block)
 
 
-.. function:: len(s)
+.. function:: len(s, /)
 
    Return the length (the number of items) of an object.  The argument may be a
    sequence (such as a string, bytes, tuple, list, or range) or a collection
@@ -991,7 +1002,8 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-list:
-.. class:: list([iterable])
+.. class:: list()
+           list(iterable, /)
    :noindex:
 
    Rather than being a function, :class:`list` is actually a mutable
@@ -1009,18 +1021,19 @@ are always available.  They are listed here in alphabetical order.
       The contents of this dictionary should not be modified; changes may not
       affect the values of local and free variables used by the interpreter.
 
-.. function:: map(function, iterable, ...)
+.. function:: map(function, iterable, /, *iterables)
 
    Return an iterator that applies *function* to every item of *iterable*,
-   yielding the results.  If additional *iterable* arguments are passed,
+   yielding the results.  If additional *iterables* arguments are passed,
    *function* must take that many arguments and is applied to the items from all
    iterables in parallel.  With multiple iterables, the iterator stops when the
    shortest iterable is exhausted.  For cases where the function inputs are
    already arranged into argument tuples, see :func:`itertools.starmap`\.
 
 
-.. function:: max(iterable, *[, key, default])
-              max(arg1, arg2, *args[, key])
+.. function:: max(iterable, /, *, key=None)
+              max(iterable, /, *, default, key=None)
+              max(arg1, arg2, /, *args, key=None)
 
    Return the largest item in an iterable or the largest of two or more
    arguments.
@@ -1056,8 +1069,9 @@ are always available.  They are listed here in alphabetical order.
    :ref:`typememoryview` for more information.
 
 
-.. function:: min(iterable, *[, key, default])
-              min(arg1, arg2, *args[, key])
+.. function:: min(iterable, /, *, key=None)
+              min(iterable, /, *, default, key=None)
+              min(arg1, arg2, /, *args, key=None)
 
    Return the smallest item in an iterable or the smallest of two or more
    arguments.
@@ -1085,7 +1099,8 @@ are always available.  They are listed here in alphabetical order.
       The *key* can be ``None``.
 
 
-.. function:: next(iterator[, default])
+.. function:: next(iterator, /)
+              next(iterator, default, /)
 
    Retrieve the next item from the :term:`iterator` by calling its
    :meth:`~iterator.__next__` method.  If *default* is given, it is returned
@@ -1104,7 +1119,7 @@ are always available.  They are listed here in alphabetical order.
       assign arbitrary attributes to an instance of the :class:`object` class.
 
 
-.. function:: oct(x)
+.. function:: oct(x, /)
 
   Convert an integer number to an octal string prefixed with "0o".  The result
   is a valid Python expression. If *x* is not a Python :class:`int` object, it
@@ -1356,7 +1371,7 @@ are always available.  They are listed here in alphabetical order.
    .. versionchanged:: 3.11
       The ``'U'`` mode has been removed.
 
-.. function:: ord(c)
+.. function:: ord(c, /)
 
    Given a string representing one Unicode character, return an integer
    representing the Unicode code point of that character.  For example,
@@ -1364,7 +1379,7 @@ are always available.  They are listed here in alphabetical order.
    returns ``8364``.  This is the inverse of :func:`chr`.
 
 
-.. function:: pow(base, exp[, mod])
+.. function:: pow(base, exp, mod=None)
 
    Return *base* to the power *exp*; if *mod* is present, return *base* to the
    power *exp*, modulo *mod* (computed more efficiently than
@@ -1507,15 +1522,15 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-range:
-.. class:: range(stop)
-              range(start, stop[, step])
+.. class:: range(stop, /)
+           range(start, stop, step=1, /)
    :noindex:
 
    Rather than being a function, :class:`range` is actually an immutable
    sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.
 
 
-.. function:: repr(object)
+.. function:: repr(object, /)
 
    Return a string containing a printable representation of an object.  For many
    types, this function makes an attempt to return a string that would yield an
@@ -1528,7 +1543,7 @@ are always available.  They are listed here in alphabetical order.
    :exc:`RuntimeError`.
 
 
-.. function:: reversed(seq)
+.. function:: reversed(seq, /)
 
    Return a reverse :term:`iterator`.  *seq* must be an object which has
    a :meth:`__reversed__` method or supports the sequence protocol (the
@@ -1536,7 +1551,7 @@ are always available.  They are listed here in alphabetical order.
    arguments starting at ``0``).
 
 
-.. function:: round(number[, ndigits])
+.. function:: round(number, ndigits=None)
 
    Return *number* rounded to *ndigits* precision after the decimal
    point.  If *ndigits* is omitted or is ``None``, it returns the
@@ -1564,7 +1579,8 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-set:
-.. class:: set([iterable])
+.. class:: set()
+           set(iterable, /)
    :noindex:
 
    Return a new :class:`set` object, optionally with elements taken from
@@ -1576,7 +1592,7 @@ are always available.  They are listed here in alphabetical order.
    module.
 
 
-.. function:: setattr(object, name, value)
+.. function:: setattr(object, name, value, /)
 
    This is the counterpart of :func:`getattr`.  The arguments are an object, a
    string, and an arbitrary value.  The string may name an existing attribute or a
@@ -1598,8 +1614,8 @@ are always available.  They are listed here in alphabetical order.
       :func:`setattr`.
 
 
-.. class:: slice(stop)
-           slice(start, stop[, step])
+.. class:: slice(stop, /)
+           slice(start, stop, step=1, /)
 
    Return a :term:`slice` object representing the set of indices specified by
    ``range(start, stop, step)``.  The *start* and *step* arguments default to
@@ -1716,21 +1732,22 @@ are always available.  They are listed here in alphabetical order.
    .. versionchanged:: 3.8
       The *start* parameter can be specified as a keyword argument.
 
-.. class:: super([type[, object-or-type]])
+.. class:: super()
+           super(type, object_or_type=None, /)
 
    Return a proxy object that delegates method calls to a parent or sibling
    class of *type*.  This is useful for accessing inherited methods that have
    been overridden in a class.
 
-   The *object-or-type* determines the :term:`method resolution order`
+   The *object_or_type* determines the :term:`method resolution order`
    to be searched.  The search starts from the class right after the
    *type*.
 
-   For example, if :attr:`~class.__mro__` of *object-or-type* is
+   For example, if :attr:`~class.__mro__` of *object_or_type* is
    ``D -> B -> C -> A -> object`` and the value of *type* is ``B``,
    then :func:`super` searches ``C -> A -> object``.
 
-   The :attr:`~class.__mro__` attribute of the *object-or-type* lists the method
+   The :attr:`~class.__mro__` attribute of the *object_or_type* lists the method
    resolution search order used by both :func:`getattr` and :func:`super`.  The
    attribute is dynamic and can change whenever the inheritance hierarchy is
    updated.
@@ -1786,15 +1803,16 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-tuple:
-.. class:: tuple([iterable])
+.. class:: tuple()
+           tuple(iterable, /)
    :noindex:
 
    Rather than being a function, :class:`tuple` is actually an immutable
    sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`.
 
 
-.. class:: type(object)
-           type(name, bases, dict, **kwds)
+.. class:: type(object, /)
+           type(name, bases, dict, /, **kwds)
 
    .. index:: object: type
 
@@ -1834,7 +1852,8 @@ are always available.  They are listed here in alphabetical order.
       Subclasses of :class:`type` which don't override ``type.__new__`` may no
       longer use the one-argument form to get the type of an object.
 
-.. function:: vars([object])
+.. function:: vars()
+              vars(object, /)
 
    Return the :attr:`~object.__dict__` attribute for a module, class, instance,
    or any other object with a :attr:`~object.__dict__` attribute.