I’m not really sure if this is the right place to ask this, but I’m kind of confused about why the itertools module has recipes like grouper and sliding_window in the documentation, rather than in the module itself.
I know that the itertools module itself is written in C for performance reasons, and the recipes are written in pure-Python but make use of code written in C (e.g. grouper calls zip_longest) so they’re presumably “fast enough” without needing to be written in C, but I’m not asking “why aren’t they implemented in C”.
There could be, say, a itertools.recipes submodule of pure Python code which contains those recipes, and that would, at least at first glance, seem to make more sense than including them in the module documentation and making people copy-paste them when they need them.
But, I suspect that if such an obvious option wasn’t taken that there’s a reason for it. So, what is the reason that the recipes are provided via the documentation?
Also, as a follow-up question, are there any other modules in the stdlib that do something similar?
Once you add something to the stdlib, changing the implementation (even fixing bugs) becomes much more tedious, and sometimes even close to impossible. Breaking changes need deprecation warnings for a minimum of two release cycles before the problematic behaviour can change (see PEP 387). Other times, one need to add a new API and keep the old, malfunctioning API. Using recipes is very lightweight; adding, removing, or modifying recipes are simply doc updates that can easily be backported to all bugfix branches.
To summarize the itertools doc, it mostly contains basic iterators that have proven useful in other languages, that combine well to produce more iterators, and that significantly benefit from being written, carefully, in C. There are now 20, plus builtins map and filter.
The standard library is where modules go to die, and when it comes to making itertator constructs for efficient looping, your space for continuous improvement is virtually infinite. The reason why itertools recipes/more-itertools exist is the same reason why requests exists - including them as a part of standard library would mean that they would need to pass an arduous bureaucratic mess for good ideas and proposals to get accepted, especially when a change might break backwards compatibility. Keeping cool itertools recipes as a part of documentation allows them to get changed in an instant.
It is however, pretty annoying to have to copy and paste that code along and comment containing a reference link pointing to where it came from, every single time I want to use it (now over the years, far more times than I can remember). Given the fact that the implementation of the recipes do in fact change over time, now there are nearly-but-not-quote-identical duplicated version of the code all over the place, which is not great. Python should absorb these, or at least some of them most common ones, for the benefit of users.
But assuming that won’t actually happen, it would at least be good for the recipes section to directly link to the relevant license right there, so that users having to copy and paste can at least have easy access to the information they need to be able to do so.