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

vivekvashist · 2021-12-15T23:28:11Z

https://bugs.python.org/issue46092

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

…ctions documentation.

AlexWaygood

Even if it is decided that it would be best not to add the forward slashes to the documentation here (as is being discussed in the BPO issue), you've picked up on a number of typos that would be worth correcting. I also think it's good to have consistent parameter names between the output of help() and the documentation here. So, thank you!

Doc/library/functions.rst

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

vivekvashist · 2021-12-16T20:19:27Z

Thanks Alex. I just committed your suggestions - is that ok ?

AlexWaygood · 2021-12-16T20:30:36Z

Thanks Alex. I just committed your suggestions - is that ok ?

I would revert the changes to max and min as well — as I said in my comments, I think they are better as they are currently 🙂

github-actions · 2022-01-16T00:07:33Z

This PR is stale because it has been open for 30 days with no activity.

…-documentation

erlend-aasland · 2024-02-09T13:37:57Z

I'm not sure these changes are worth it, as this PR stands. It is nice to align the docs with the docstrings, but in some cases we should rather align the docstrings with the docs (these are mostly functions that take positional-only parameters; we can change the param names if we want). Adding / is ok, IMO, though.

erlend-aasland · 2024-02-09T13:38:33Z

Doc/library/functions.rst

@@ -111,15 +111,15 @@ are always available.  They are listed here in alphabetical order.
          return False


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


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

Suggested change

.. function:: ascii(obj, /)

.. function:: ascii(object, /)

Sorry, what docstring?

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).

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.

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.

erlend-aasland · 2024-02-09T13:39:41Z

Doc/library/functions.rst

@@ -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, /)


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

Suggested change

.. function:: callable(obj, /)

.. function:: callable(object, /)

erlend-aasland · 2024-02-09T13:39:54Z

Doc/library/functions.rst

@@ -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, /)


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

Suggested change

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

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

erlend-aasland · 2024-02-09T13:40:38Z

Doc/library/functions.rst

@@ -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, /)


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

Suggested change

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

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

erlend-aasland · 2024-02-09T13:40:47Z

Doc/library/functions.rst


   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, /)


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

Suggested change

.. function:: hash(obj, /)

.. function:: hash(object, /)

erlend-aasland · 2024-02-09T13:41:17Z

Doc/library/functions.rst

@@ -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, /)


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, /)

erlend-aasland · 2024-02-09T13:41:50Z

Doc/library/functions.rst

@@ -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 , /)


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 , /)

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, /)

erlend-aasland · 2024-02-09T13:42:17Z

Doc/library/functions.rst

@@ -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, /)


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

Suggested change

.. function:: repr(obj, /)

.. function:: repr(object, /)

erlend-aasland · 2024-02-09T13:42:29Z

Doc/library/functions.rst

@@ -1570,7 +1570,7 @@ are always available.  They are listed here in alphabetical order.
   :exc:`RuntimeError`.


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


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

Suggested change

.. function:: reversed(sequence, /)

.. function:: reversed(seq, /)

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.

erlend-aasland · 2024-02-09T13:42:41Z

Doc/library/functions.rst

@@ -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, /)


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 reverts commit 6d94bcf.

erlend-aasland · 2024-02-13T09:23:11Z

Let's close this until we know how to solve these issues on a larger scale; thanks for the PR!

Fix/update missing parameters in function signatures for Built-in Fun…

27566f1

…ctions documentation.

bedevere-bot added the docs Documentation in the Doc dir label Dec 15, 2021

the-knights-who-say-ni added the CLA signed label Dec 15, 2021

bedevere-bot added the awaiting review label Dec 15, 2021

AlexWaygood self-requested a review December 16, 2021 00:10

rhettinger added the DO-NOT-MERGE label Dec 16, 2021

AlexWaygood requested changes Dec 16, 2021

View reviewed changes

bedevere-bot added awaiting core review and removed awaiting review labels Dec 16, 2021

AlexWaygood added the skip news label Dec 16, 2021

vivekvashist and others added 4 commits December 17, 2021 06:41

Update Doc/library/functions.rst

0402980

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Update Doc/library/functions.rst

68a14d2

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Update Doc/library/functions.rst

3eb483f

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Update Doc/library/functions.rst

d16a06c

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

github-actions bot added the stale Stale PR or inactive for long period of time. label Jan 16, 2022

ezio-melotti removed the CLA signed label Jul 13, 2022

erlend-aasland added 2 commits February 9, 2024 14:26

Merge branch 'main' into Fix-missing-parameters-in-Built-in-Functions…

9642d8b

…-documentation

Fix merge

6d94bcf

erlend-aasland changed the title ~~bpo-46092: Fix/update missing parameters in function signatures for Built-in Functions documentation~~ gh-90250: Fix/update missing parameters in function signatures for Built-in Functions documentation Feb 9, 2024

vivekvashist mannequin mentioned this pull request Feb 9, 2024

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

Open

erlend-aasland reviewed Feb 9, 2024

View reviewed changes

Revert "Fix merge"

154e31d

This reverts commit 6d94bcf.

erlend-aasland marked this pull request as draft February 13, 2024 09:22

bedevere-app bot removed the awaiting core review label Feb 13, 2024

erlend-aasland closed this Feb 13, 2024

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

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

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

	.. function:: isinstance(obj, class_or_tuple, /)
	.. function:: isinstance(object, classinfo, /)

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

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

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

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

Uh oh!

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

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

Uh oh!

Conversation

vivekvashist commented Dec 15, 2021 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AlexWaygood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vivekvashist commented Dec 16, 2021

Uh oh!

AlexWaygood commented Dec 16, 2021

Uh oh!

github-actions bot commented Jan 16, 2022

Uh oh!

erlend-aasland commented Feb 9, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erlend-aasland commented Feb 13, 2024

Uh oh!

Uh oh!

vivekvashist commented Dec 15, 2021 •

edited by bedevere-app bot

Loading