[David Mertz] > I often use doctests to verify APIs and behaviors when I update code. I
> > know I'm in a minority and most developers slightly disparage doctests. [Steven D'Aprano] > I don't know why you think that "most developers" disparage doctests. > Perhaps they're the same ones who think that "read the source" is all > the documentation anyone needs. > Or ones who aren't happy unless they can demonstrate their mastery of a convoluted class hierarchy with hundreds of methods to memorize. Or unless they're Guido! He was never fond of doctest either. I know I don't. I love them. Tim Peters loves them (he should, he wrote > the module) and if its good enough for Uncle Timmy then anyone who > disparages them better have a damn good reason. > Nope! They don't need any reason at all. I don't mind :-) It was a sneaky, although minor, purpose of doctest to raise the bar for making gratuitous changes to Python's output. Developers have approximately no appreciation for how off-putting it can be for users to struggle with docs showing output they don't actually see. Is the installation buggy? Did they type something wrong? Was the doc author just making stuff up? Etc. "Something's wrong here, but I don't know what" is not a happy experience :-( So I always count it as a Good Thing when someone points out "but doctests will break". _That_ developers can understand. It's a proxy for the real costs of making gratuitous changes, which are pretty much invisible to developers. Not that it should drive a decision - but it should be counted as _a_ cost. ... I think we'd need to ask on Python-Dev to be sure, but my understanding > is that backwards compatibility guarantees for reprs are weaker than > those for regular APIs but stronger than those for error messages. > That sounds about right to me. The docs for doctest already point out that relying on reprs is dubious in various cases, so if someone is relying on the repr of OrderedDict in their doctests they presumably care about the repr more than the semantics. Or they were just confused ;-) In any case, since OrderedDict seems to be viewed as a legacy feature now, making any change to it is an odd idea on the face of it.
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
