gh-91485: Doc: Using Python syntax to document builtin Python functions.

[JulienPalard]

I tried my idea at documenting Python functions using only Python syntax (avoiding manpages-like brackets to denote optional arguments), please tell me what you think.

It sometimes went "badly", like:

-.. class:: set([iterable])+.. class:: set(iterable=())

where I "had" to use an empty tuple because it would have looked very recursive to use a set here, like set(iterable=set()). It's also a lie: it's not an empty tuple by default (it's a C NULL), but there's no practical difference for the reader.

Sometimes the change is more neutral, like in:

-.. awaitablefunction:: anext(async_iterator[, default])+.. awaitablefunction:: anext(async_iterator)+ anext(async_iterator, default)

or:

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

(where I'm happy to remove , *[, because it hurt my eyes.)

Sometimes it's good as it add information:

-.. class:: complex([real[, imag]])+.. class:: complex(real=0, imag=0)

Or make more explicit where it's OK to pass None and where it's not, like in:

-.. class:: super([type[, object-or-type]])+.. class:: super()+ super(type, object_or_type=None)

I bet you think « People should know this syntax, or learn it anyway », but I don't think so, I mean yes they will learn it anyway, but why forcing them to learn it at the same time as they learn basic Python functions? Learning one thing at a time is complicated enough.

Many are alone facing those pages and showing them:

complex(real=0, imag=0)

teach them how to implement default arguments in their own functions, and explicitly show them what happen when they don't give the values, while:

complex([real[, imag]])

don't.

• Issue: documentation for function arguments #91485

[JulienPalard]

I don't like:

.. class:: list(iterable=[])

for an acute reader it scream "the default empty list is reused!", I have to change this.

[AA-Turner]

Biggest comment is on map().

A

[AA-Turner]

I don't think the new wording is true, e.g.:

>>> from operator import add
>>> for x inmap(add, [1, 2, 3, 4, 5], [10, 20, 30, 40, 50]):
>>> print(x)
>>> 11
22
33
44
55

So it doesn't apply function to every item of iterables, but to every item of zip(*iterables).

[JulienPalard]

you're right, we have to rephrase it..

[JulienPalard]

What about 7aca0e5 ? map(int) is not valid anyway.

[JulienPalard]

(I move the / in the following commit as iterable can't be given by name)

[JulienPalard]

@AA-Turner wow we were doing it in the same time, I just pushed my part, we'll be able to diff them to see if we agree :D

[AA-Turner]

Thanks! I think this is good to merge personally.

A

[miss-islington]

Thanks @JulienPalard for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[miss-islington]

Sorry, @JulienPalard, I could not cleanly backport this to 3.10 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 3c4cbd177f36777a04e78eb07ce20367560a66d3 3.10

[bedevere-bot]

GH-98276 is a backport of this pull request to the 3.11 branch.