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

[Dirkjan Ochtman]

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