On 2019-08-01 12:31, Andrew Barnert via Python-ideas wrote:
On Aug 1, 2019, at 10:48, Eli Berkowitzeliberkowitz@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?