[Python-checkins] gh-91485: Doc: Using Python syntax to document builtin Python functions. (GH-96579)
miss-islington
webhook-mailer at python.org
Sat Oct 15 10:32:43 EDT 2022
https://github.com/python/cpython/commit/42d536c1c7b9fcb2f85663a54f11f4a073211fef
commit: 42d536c1c7b9fcb2f85663a54f11f4a073211fef
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-10-15T07:32:37-07:00
summary:
gh-91485: Doc: Using Python syntax to document builtin Python functions. (GH-96579)
(cherry picked from commit 3c4cbd177f36777a04e78eb07ce20367560a66d3)
Co-authored-by: Julien Palard <julien at palard.fr>
files:
M Doc/library/functions.rst
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 93c9f4ad2bc2..8108c98332e9 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.
More information about the Python-checkins
mailing list