On Apr 30, 2020, at 07:58, Christopher Barker <python...@gmail.com> wrote: > >> I think that the issue of searchability and signature are pretty >> compelling reasons for such a simple feature to be part of the >> function name. > > I would absolutely agree with that if all three function were in the same > namespace (like the string methods referred to earlier), but in this case, > one is a built in and the others will not be — which makes a huge difference > in discoverability. > > Imagine someone that uses zip() in code that works for a while, and then > discovers a bug triggered by unequal length inputs. > > If it’s a flag, they look at the zip docstring, and find the flag, and their > problem is solved. > > Is it’s in itertools, they have to think to look there. Granted, some > googling will probably lead them there, and the zip() docstring can point > them there, but it’s still a heavier lift.
I don’t understand. You’re arguing that being discoverable in the docstring is sufficient for the flag, but being discoverable in the docstring is a heavier lift from the function. Why would this be true, unless you intentionally write the docstring badly? To make this more concrete, let’s say we want to just add on to the existing doc string (even though it seems aimed more at reminding experts of the exact details than at teaching novices) and stick to the same style. We’re then talking about something like this: > Return a zip object whose .__next__() method returns a tuple where > the i-th element comes from the i-th iterable argument. The .__next__() > method continues until the shortest iterable in the argument sequence > is exhausted and then it raises StopIteration, or, if equal is true, > it checks that the remaining iterables are exhausted and otherwise > raises ValueError. … vs. this: > Return a zip object whose .__next__() method returns a tuple where > the i-th element comes from the i-th iterable argument. The .__next__() > method continues until the shortest iterable in the argument sequence > is exhausted and then it raises StopIteration. If you need to check > that all iterables are exhausted, use itertools.zip_equal, > which raises ValueError if they aren’t. If they can figure out that equal=True is what they’re looking for from the first one, it’ll be just as easy to figure out that zip_equal is what they’re looking for from the second. Of course it might be better to rewrite the whole thing to be more novice-friendly and to describe what zip iterates at a higher level instead of describing how its __next__ method operates, but that applies to both versions.
_______________________________________________ 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/BGTNMWVD3THOYV2GILT7LNNYHMBGAW77/ Code of Conduct: http://python.org/psf/codeofconduct/
