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

[Antoine Pitrou]

On Tue, 20 Dec 2011 11:14:15 +0100
Dirkjan Ochtman <dirkjan at ochtman.nl> wrote:
> 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").

I would expect it to be just as fast right now, although that's just
an uninformed guess. That said, CPython is both the dominant
implementation and the only one (AFAIR) to have stable 3.2 support.

> > 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.

Agreed. The original wording was poor since it mentioned C while what
is really significant is performance. There are probably Python
programmers who don't even know what C is.

Regards

Antoine.