-
-
Notifications
You must be signed in to change notification settings - Fork 31.4k
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
gh-91485: Doc: Using Python syntax to document builtin Python functions. #96579
Conversation
I don't like:
for an acute reader it scream "the default empty list is reused!", I have to change this. |
Co-authored-by: Antoine Rozo <antoine.rozo@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
There was a problem hiding this 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
.. 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, |
There was a problem hiding this comment.
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)
.
There was a problem hiding this comment.
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..
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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)
0bf0db5
to
92a3bb0
Compare
@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 |
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
There was a problem hiding this 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
Thanks @JulienPalard for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. |
Sorry, @JulienPalard, I could not cleanly backport this to |
GH-98276 is a backport of this pull request to the 3.11 branch. |
…unctions. (pythonGH-96579) (cherry picked from commit 3c4cbd1) Co-authored-by: Julien Palard <julien@palard.fr>
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:
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 CNULL
), but there's no practical difference for the reader.Sometimes the change is more neutral, like in:
or:
(where I'm happy to remove
, *[,
because it hurt my eyes.)Sometimes it's good as it add information:
Or make more explicit where it's OK to pass
None
and where it's not, like in: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:
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:
don't.