document positional-only arguments for collections.deque

[asottile]

No description provided.

[asottile]

ran into this accidentally while using pypy and then was surprised when I used cpython and it didn't work

[rhettinger]

I believe there was a decision to NOT broadly apply this across the documentation. The notion was the / notation was broadly confusing to beginners and the doc edits were not actually helping anyone (i.e. no real user problem is being solved). For example, the sequence method documentation for list methods was not changed. We are applying the notation is complex cases whether the notation is a net win. For example, the sorted() builtin has a complex signature that mixes both keyword-only and positional-only arguments. I believe a similar decision was made to not add type annotations to the docs.

[rhettinger]

Thanks for the suggestion, but let's wait until there is a collective decision to go forward with doing this to all the docs, not just deque.

[asottile]

Thanks for the suggestion, but let's wait until there is a collective decision to go forward with doing this to all the docs, not just deque.

then should these be removed?

$ git grep -E '^\.\. (method|function):: .*/[,)]' -- Doc/ | head -5
Doc/library/_thread.rst:.. function:: interrupt_main(signum=signal.SIGINT, /)
Doc/library/binascii.rst:.. function:: a2b_base64(string, /, *, strict_mode=False)
Doc/library/curses.rst:.. function:: wrapper(func, /, *args, **kwargs)
Doc/library/dataclasses.rst:.. function:: replace(obj, /, **changes)
Doc/library/functions.rst:.. function:: eval(expression, /, globals=None, locals=None)
$ git grep -E '^\.\. (method|function):: .*/[,)]' -- Doc/ | wc -l
107

[rhettinger]

No, I wouldn't remove them. Occasionally, some are added at the discretion of the maintainer when they think it might be useful. Previously, I mentioned sorted() as a example. The replace function in dataclasses makes sense to me because we specifically want to indicate that obj is allowed as a keyword argument: replace(dci, obj=10, self=5, cls=15).

And while I didn't make any of the edits that you found, I'm not worried about them. The users of eval, curses, and binascii are more sophisticated than the users of len and append. It's the latter users who are more likely to defeated by an arcane notation that doesn't appear in any other language.

Side note. I recommend not going down the path of "give me an exact, clearly defined rule, then I will sweep through the docs and apply it everywhere without consideration to each individual case". It is a tempting path, but our world is more nuanced than that and not all the developers agree on all the little decisions. To start contributing, I recommend starting with filed bug reports so that changes are directed at solving known user issues. In the past, Guido has advocated "holistic refactoring" focusing on the zeitgeist and needs of a particular module and its user base rather than non-holistic mark-and-sweep PRs (put another way, don't start by running grep). Others might advise you differently so take this all with a grain of salt.

[asottile]

yeah I'm not exactly new here but appreciate the message nonetheless

[rhettinger]

yeah I'm not exactly new here but appreciate the message nonetheless

Yes, of course, I know who you are. Just wanted to give a more thoughtful answer to your question than just "no" ;-)