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

[Antoine Pitrou]

On Tue, 20 Dec 2011 05:27:41 -0500
Terry Reedy <tjreedy at udel.edu> wrote:
> >
> > I disagree with this change. Knowing that they are written in C is
> > important when deciding to pass them to e.g. sort() or sorted(),
> > because you know it will be faster than an arbitrary pure Python
> > function.
> >
> > You could tag it as a "CPython implementation detail" if you want, or
> > talk about performance rather than mention "C".
> 
> The existence of operator and the behavior of its functions is not a C 
> implementation detail.

And?

> I think a programmer 
> can assume that they are are written in the implementation language to 
> be as fast as possible.

Yeah, you can assume anything, and then get bitten by the fact that
e.g. OrderedDict is pure Python and thus massively slower than dict.
But at least you've achieved some platonic ideal of how documentation
should not talk about implementation details, which is great, right?

Why you think we should leave users in the dark rather than inform them
is beyond me. While we certainly should find a good compromise between
readability and completeness, and should certainly tweak the doc's
wording and layout adequately, removing useful information is nonsense.

> For instance, 
> there is nothing is the library manual that I can see that specifies 
> that the builtin functions and types are written in C (for CPython).

I guess everyone expects builtin functions and types to be
reasonably fast, regardless of the language or implementation.
(even though I did see some beginner code rewrite its own slow "list"
wrapper, so it's probably not an universal expectation)

> Perhaps Python Setup and Usage could be renamed CPython Setup and Usage 
> and expanded with more info on gc (ref counting), O() notes, Python vs. 
> C code, etc.

Really? That's a perfectly inappropriate place to talk about performance
details of *any* implementation.

Regards

Antoine.