On 2019-08-01 12:31, Andrew Barnert via Python-ideas wrote:
On Aug 1, 2019, at 10:48, Eli Berkowitz<eliberkow...@gmail.com> wrote:
>
>In terms of an argument for why it should be included, for most Python users
the itertools recipes remain unseen.
Sure. But do you also know all of the functions in the module? Would you notice
or a new one got added? In practical terms, how much more discoverable is
groupby than grouper?
It is massively more discoverable, for one simple reason: autocomplete.
In teaching people to program, I often use Jupyter notebook, which has
great autocomplete functionality that can also bring up the
documentation on any function. You can type itertools.[TAB] and get a
list, and then you can scroll down the list looking for a likely
function, and when you get to it you can hit Shift-Tab and see the
documentation. Certainly other IDEs have similar functionality.
This is a colossal win over having to go the documentation and look
through the text for a recipe that is not "addressable" in any way. You
can't even link to it, for heaven's sake! The function docs in all the
modules have permalinks but the recipes are just unstructured text.
I don't fully understand the resistance to adding these functions to
itertools itself. As what I mentioned above indicates, they already ARE
in itertools from a documentation perspective. They're just there as
irritatingly unstructured text instead of integrated into the clean,
useful format that the documentation generally follows. They already
have to be maintained because they're part of the official docs; if some
change were made to itertools that required one of the recipes to
change, the recipe would have to be changed, because it's already there
in the official docs.
From some other posts in the thread I get the impression some people
think there is (or should be) some sort of multi-tiered system along the
lines of:
1) in the stdlib
2) in a "recipe" in the stdlib but you have to copy and paste it
3) in an "officially sanctioned" third-party lib which is a "category
killer" (like requests)
4) in a "somewhat less officially sanctioned" third-party lib which
isn't a "category killer" (like toolz?)
5) in an ordinary third-party lib of which the documentation makes no
mention
Some of those may be good ideas, but I don't see the use of the
distinction between tiers 1 and 2. If there's going to be a full
implementation of a simple function in textual form in the docs, and
that textual form is going to be maintained precisely because we already
know the function is of general utility, what is gained by insisting
that it remain only in textual form and not in code form that can
actually be used?
This is clearly different from other cases in the docs where functions
or code snippets are provided solely as EXAMPLES that no one would
actually use as-is in real life. The "grouper" example isn't an example
or sketch of how to write a function that groups into chunks: it IS a
function that groups into chunks. Yeah, sure, you might sometimes want
to write a slight tweak on it, but I don't get why that means that an
already-working version has to be dangled in front of people in text
form without actually being usable (or discoverable via autocomplete).
The way the "recipes" are presented in the existing docs clearly
indicates that they are widely useful as-is, and they already have to be
maintained as text, so why not just put them in for real?
--
Brendan Barnwell
"Do not follow where the path may lead. Go, instead, where there is no
path, and leave a trail."
--author unknown
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/URV4E3M6MPP7QZWITYYJZ66ZY3HSSTXH/
Code of Conduct: http://python.org/psf/codeofconduct/
