[Python-Dev] cpython (3.2): don't mention implementation detail (original) (raw)

Dirkjan Ochtman dirkjan at ochtman.nl
Tue Dec 20 11:14:15 CET 2011

On Tue, Dec 20, 2011 at 11:08, Antoine Pitrou <solipsis at pitrou.net> wrote:

If this documentation is to be used by other python implementations, then mentions of performance are outright harmful, since the performance characteristics differ quite drastically. Written in C is also not a part of specification as far as I know :) But that's basically the only reason to invoke the operator.attrgetter("foo") ugliness, instead of writing the explicit and obvious lambda x: x.foo. So not mentioning that it provides a speed benefit on CPython hides the primary reason for using the operator module. Overwise it's just a bunch of useless wrappers.

So the question is if the docs are Python documentation or CPython documentation? On PyPy, I'm guessing lambda x: x.foo might (some day) be just as fast as operator.attrgetter("foo").

Implementation details deserve to be documented when they have an impact on behaviour (including performance / resource usage). Python is not just a platonic ideal. Do you suggest we also remove this part: http://docs.python.org/dev/library/io.html#performance ?

I agree that it's good to document some implementation details, but it seems like the paragraph, as it was before, documented too many details. It seems like a paragraph that mentions the specificity of this aspect for CPython and omits the reference to C as the VM implementation should be acceptable to all parties.

Cheers,

Dirkjan

More information about the Python-Dev mailing list