Skip to content

gh-90250: Fix/update missing parameters in function signatures for Built-in Functions documentation #30128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vivekvashist wants to merge 8 commits into from
Closed

gh-90250: Fix/update missing parameters in function signatures for Built-in Functions documentation #30128

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
27566f1
Fix/update missing parameters in function signatures for Built-in Fun…
vivekvashist Dec 15, 2021
0402980
Update Doc/library/functions.rst
vivekvashist Dec 16, 2021
68a14d2
Update Doc/library/functions.rst
vivekvashist Dec 16, 2021
3eb483f
Update Doc/library/functions.rst
vivekvashist Dec 16, 2021
d16a06c
Update Doc/library/functions.rst
vivekvashist Dec 16, 2021
9642d8b
Merge branch 'main' into Fix-missing-parameters-in-Built-in-Functions…
erlend-aasland Feb 9, 2024
6d94bcf
Fix merge
erlend-aasland Feb 9, 2024
154e31d
Revert "Fix merge"
erlend-aasland Feb 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 29 additions & 29 deletions Doc/library/functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,15 @@ 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:`~object.__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__()``.
Expand All @@ -71,7 +71,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::
Expand Down Expand Up @@ -99,7 +99,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::
Expand All @@ -111,15 +111,15 @@ are always available. They are listed here in alphabetical order.
return False


.. function:: ascii(object)
.. function:: ascii(obj, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: ascii(obj, /)
.. function:: ascii(object, /)

@merwok merwok Feb 9, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, what docstring?

@erlend-aasland erlend-aasland Feb 10, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cpython/Python/bltinmodule.c

Lines 400 to 403 in 5643856

ascii as builtin_ascii
obj: object
/

Perhaps "signature" is more accurate. Anyway, I'm not sure it is worth it (neither this PR nor updating the signature).

@merwok merwok Feb 10, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah ok. I am not sure that it is necessary to edit many docstrings here: they are not wrong, as the params do not really have names.

See my comment on the ticket for a broader point about his issue.

@CAM-Gerlach CAM-Gerlach Feb 10, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, we should pick the clearer name and use that consistently. In this case, while using the full name rather than abbreviating is potentially a bit clearer on the word intended, the latter avoids confusion on the meaning: object is already a builtin name, the base type object itself, while obj seems to be de-facto convention for function parameter that is an arbitrary object instance to act on.


As :func:`repr`, return a string containing a printable representation of an
object, but escape the non-ASCII characters in the string returned by
:func:`repr` using ``\x``, ``\u``, or ``\U`` escapes. This generates a string
similar to that returned by :func:`repr` in Python 2.


.. function:: bin(x)
.. function:: bin(number, /)

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
Expand Down Expand Up @@ -230,7 +230,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(obj, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: callable(obj, /)
.. 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
Expand All @@ -243,7 +243,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
Expand Down Expand Up @@ -405,7 +405,7 @@ are always available. They are listed here in alphabetical order.
:meth:`~object.__float__` are not defined.


.. function:: delattr(object, name)
.. function:: delattr(obj, name, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: delattr(obj, 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
Expand Down Expand Up @@ -488,16 +488,16 @@ are always available. They are listed here in alphabetical order.
class.


.. function:: divmod(a, b)
.. function:: divmod(x, y, /)

Take two (non-complex) numbers as arguments and return a pair of numbers
consisting of their quotient and remainder when using integer division. With
mixed operand types, the rules for binary arithmetic operators apply. For
integers, the result is the same as ``(a // b, a % b)``. For floating point
numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a /
b)`` but may be 1 less than that. In any case ``q * b + a % b`` is very
close to *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0
<= abs(a % b) < abs(b)``.
integers, the result is the same as ``(x // y, x % y)``. For floating point
numbers the result is ``(q, x % y)``, where *q* is usually ``math.floor(x /
y)`` but may be 1 less than that. In any case ``q * x + y % y`` is very
close to *x*, if ``x % y`` is non-zero it has the same sign as *y*, and ``0
<= abs(x % y) < abs(y)``.


.. function:: enumerate(iterable, start=0)
Expand Down Expand Up @@ -778,15 +778,15 @@ are always available. They are listed here in alphabetical order.
regardless of where the function is called.


.. function:: hasattr(object, name)
.. function:: hasattr(obj, name, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: hasattr(obj, 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
is implemented by calling ``getattr(object, name)`` and seeing whether it
raises an :exc:`AttributeError` or not.)


.. function:: hash(object)
.. function:: hash(obj, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: hash(obj, /)
.. 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
Expand Down Expand Up @@ -821,10 +821,10 @@ are always available. They are listed here in alphabetical order.
signatures for callables are now more comprehensive and consistent.


.. function:: hex(x)
.. function:: hex(number,/)

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
"0x". If *number* is not a Python :class:`int` object, it has to define an
:meth:`~object.__index__` method that returns an integer. Some examples:

>>> hex(255)
Expand Down Expand Up @@ -853,7 +853,7 @@ are always available. They are listed here in alphabetical order.
:meth:`float.hex` method.


.. function:: id(object)
.. function:: id(obj, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: id(obj, /)
.. 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.
Expand Down Expand Up @@ -948,7 +948,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(obj, class_or_tuple, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: isinstance(obj, class_or_tuple, /)
.. 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
Expand All @@ -965,7 +965,7 @@ are always available. They are listed here in alphabetical order.
*classinfo* can be a :ref:`types-union`.


.. function:: issubclass(class, classinfo)
.. function:: issubclass(cls, class_or_tuple , /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: issubclass(cls, class_or_tuple , /)
.. function:: issubclass(class, classinfo , /)

@CAM-Gerlach CAM-Gerlach Feb 10, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also a typo (stray space):

Suggested change
.. function:: issubclass(cls, class_or_tuple , /)
.. function:: issubclass(cls, class_or_tuple, /)

or

Suggested change
.. function:: issubclass(cls, class_or_tuple , /)
.. function:: issubclass(cls, classinfo, /)


Return ``True`` if *class* is a subclass (direct, indirect, or :term:`virtual
<abstract base class>`) of *classinfo*. A
Expand Down Expand Up @@ -1008,7 +1008,7 @@ are always available. They are listed here in alphabetical order.
process_block(block)


.. function:: len(s)
.. function:: len(obj, /)

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
Expand Down Expand Up @@ -1138,10 +1138,10 @@ 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(number, /)

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
is a valid Python expression. If *number* is not a Python :class:`int` object, it
has to define an :meth:`~object.__index__` method that returns an integer. For
example:

Expand Down Expand Up @@ -1390,7 +1390,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,
Expand Down Expand Up @@ -1556,7 +1556,7 @@ are always available. They are listed here in alphabetical order.
sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`.


.. function:: repr(object)
.. function:: repr(obj, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: repr(obj, /)
.. 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
Expand All @@ -1570,7 +1570,7 @@ are always available. They are listed here in alphabetical order.
:exc:`RuntimeError`.


.. function:: reversed(seq)
.. function:: reversed(sequence, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: reversed(sequence, /)
.. function:: reversed(seq, /)

@CAM-Gerlach CAM-Gerlach Feb 10, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case at least ISTM sequence reads clearer than seq; beginners and particularly non-native speakers may not immediately assume seq is short for sequence.


Return a reverse :term:`iterator`. *seq* must be an object which has
a :meth:`~object.__reversed__` method or supports the sequence protocol (the
Expand Down Expand Up @@ -1619,7 +1619,7 @@ are always available. They are listed here in alphabetical order.
module.


.. function:: setattr(object, name, value)
.. function:: setattr(obj, name, value, /)

@erlend-aasland erlend-aasland Feb 9, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave the param name untouched and instead consider updating the docstring.

Suggested change
.. function:: setattr(obj, 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
Expand Down