Skip to content
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.

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

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

Merged
merged 12 commits into from
Oct 15, 2022

Conversation

JulienPalard
Copy link
Member

@JulienPalard JulienPalard commented Sep 5, 2022

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.

@bedevere-bot bedevere-bot added awaiting core review docs Documentation in the Doc dir skip news labels Sep 5, 2022
Doc/library/functions.rst Outdated Show resolved Hide resolved
Doc/library/functions.rst Outdated Show resolved Hide resolved
@JulienPalard
Copy link
Member Author

I don't like:

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

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

Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

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

Biggest comment is on map().

A

Doc/library/functions.rst Outdated Show resolved Hide resolved
Doc/library/functions.rst Outdated Show resolved Hide resolved
Doc/library/functions.rst Outdated Show resolved Hide resolved
Doc/library/functions.rst Show resolved Hide resolved
Doc/library/functions.rst Outdated Show resolved Hide resolved
Comment on lines 1021 to 1026
.. function:: map(function, *iterables)

Return an iterator that applies *function* to every item of *iterable*,
yielding the results. If additional *iterable* arguments are passed,
Return an iterator that applies *function* to every item of *iterables*,
yielding the results. If additional *iterables* arguments are passed,
Copy link
Member

Choose a reason for hiding this comment

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

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

>>> from operator import add
>>> for x in map(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).

Copy link
Member Author

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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

@JulienPalard
Copy link
Member Author

@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

Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

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

Thanks! I think this is good to merge personally.

A

@AA-Turner AA-Turner added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Oct 13, 2022
@JulienPalard JulienPalard merged commit 3c4cbd1 into python:main Oct 15, 2022
@miss-islington
Copy link
Contributor

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

@JulienPalard JulienPalard deleted the mdk-stick-to-python-syntax branch October 15, 2022 10:19
@miss-islington
Copy link
Contributor

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
Copy link

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

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Oct 15, 2022
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 15, 2022
…unctions. (pythonGH-96579)

(cherry picked from commit 3c4cbd1)

Co-authored-by: Julien Palard <[email protected]>
miss-islington added a commit that referenced this pull request Oct 15, 2022
…ns. (GH-96579)

(cherry picked from commit 3c4cbd1)

Co-authored-by: Julien Palard <[email protected]>
JulienPalard added a commit that referenced this pull request Oct 17, 2022
pablogsal pushed a commit that referenced this pull request Oct 22, 2022
@hauntsaninja hauntsaninja removed the needs backport to 3.10 only security fixes label Dec 27, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants