I verify that this PR fixes the IDLE tooltip regression of #100990.

Please do not force-push; instead do git merge --no-ff main if you want to pull in recent changes.

The devguide also mentions this.

The original commits should be reverted entirely. There is no known user problem that warrants a wholesale rewrite of the docstrings. In addition, the existing docstrings were modeled after their counterparts in list and tuple. I don't want to lose that relationship:

for method in set(dir(list)) & set(dir(deque)):
    if not method.startswith('__'):
        print(method.upper())
        print('list:  ', getattr(list, method).__doc__)
        print('deque: ', getattr(list, method).__doc__)
        print()

        
EXTEND
list:   Extend list by appending elements from the iterable.
deque:  Extend list by appending elements from the iterable.

CLEAR
list:   Remove all items from list.
deque:  Remove all items from list.

COPY
list:   Return a shallow copy of the list.
deque:  Return a shallow copy of the list.

APPEND
list:   Append object to the end of the list.
deque:  Append object to the end of the list.

REMOVE
list:   Remove first occurrence of value.

Raises ValueError if the value is not present.
deque:  Remove first occurrence of value.

Raises ValueError if the value is not present.

INDEX
list:   Return first index of value.

Raises ValueError if the value is not present.
deque:  Return first index of value.

Raises ValueError if the value is not present.

REVERSE
list:   Reverse *IN PLACE*.
deque:  Reverse *IN PLACE*.

COUNT
list:   Return number of occurrences of value.
deque:  Return number of occurrences of value.

POP
list:   Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.
deque:  Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

INSERT
list:   Insert object before index.
deque:  Insert object before index.

I've taught Python to new people weekly for 11 years. I've seen no evidence at all that these docstrings cause any issues for beginners.

@rhettinger Alright, I appreciate the insight!

The motivation for this was not that I think the current docstrings are unclear in any way, but simply that I think my changes provide a compromise that improves compatibility with existing conventions and tools while not degrading understandability for humans at the same time.
If the second part is not true, I agree that readability for humans is more important.

I mean of course I could also adapt the docstrings of their counterparts if this is the main concern, but as I understand your comments, this is more of a matter of principle, and probably other problems will arise if we go down that road.

In the absence of a known user problem with readability, we should leave the docstrings in sync with listobject.c. Also, docstrings edits that aren't bug fixes are not supposed to be backported. In the initial review, I asked that only one change be made, going from "integer" to "int" and noted that all the other edits were gratuitous. Please stick with just that. Side ntoe, it is the duty of third-party tools to match CPython conventions, not vice-versa. These docstrings have been present for well over a decade. All third party tools should have been tested against them.

@erlend-aasland Are you on-board with closing this PR and reverting the others? The original PR did not follow my review comments. It violated our docstring pep resulting which affected tooling and degraded the user experience. It broke the intentional symmetry with listobject.c. It did not address any known user readability issue. The "fix accuracy" checkin message bordered on being intentionally misleading. And since it wasn't a bug fix, it should not have been backported, especially without the consent of the module maintainer.

If there are new docstring conventions that we want to require, they should be proposed as an amendment to the docstring PEP rather than being pushed through under the guise of "fixing accuracy".

In the initial review, I asked that only one change be made, going from "integer" to "int" and noted that all the other edits were gratuitous.

Ok, I reverted all changes but this one. When this PR is squash merged, it will revert the old PR and include only the change from integer to int.

If there are new docstring conventions that we want to require, they should be proposed as an amendment to the docstring PEP rather than being pushed through under the guise of "fixing accuracy".

The existing docs mention PEP-7 which says:

The first line of each function docstring should be a “signature line” that gives a brief synopsis of the arguments and return value. For example:

PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n\
Determine whether name and value make a valid pair.");

Always include a blank line between the signature line and the text of the description.

If the return value for the function is always None (because there is no meaningful return value), do not include the indication of the return type.

So a first step would be to update the docs and state that PEP-7 is no longer the preferred format.

Also, PEP-257, which was mentioned in the discussion, says:

The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection). Don’t do:

def function(a, b):
    """function(a, b) -> list"""

This type of docstring is only appropriate for C functions (such as built-ins), where introspection is not possible.

And especially the last paragraph sounds to me as this format would in fact be appropriate for C functions.

@rhettinger: sure, I'm fine with reverting #100990, and AFAICS, this PR has now been updated to do just that (except for the integer => int thing).

Thanks. In the interest of making sure it is done correctly and not overlooking any spurious changes, I'm going to do clean 100% revert of the previous PRs. A new clean PR can be made for just the "integer" to "int" change and applied only to 3.12 and 3.11.

SGTM