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

[Terry Reedy]

On 12/20/2011 3:51 AM, Antoine Pitrou wrote:
> On Mon, 19 Dec 2011 22:42:43 +0100
> benjamin.peterson<python-checkins at python.org>  wrote:
>> http://hg.python.org/cpython/rev/d85efd73b0e1
>> changeset:   74088:d85efd73b0e1
>> branch:      3.2
>> parent:      74082:71e5a083f9b1
>> user:        Benjamin Peterson<benjamin at python.org>
>> date:        Mon Dec 19 16:41:11 2011 -0500
>> summary:
>>    don't mention implementation detail
>>
>> files:
>>    Doc/library/operator.rst |  10 +++++-----
>>    1 files changed, 5 insertions(+), 5 deletions(-)
>>
>>
>> diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
>> --- a/Doc/library/operator.rst
>> +++ b/Doc/library/operator.rst
>> @@ -12,11 +12,11 @@
>>      from operator import itemgetter, iadd
>>
>>
>> -The :mod:`operator` module exports a set of functions implemented in C
>> -corresponding to the intrinsic operators of Python.  For example,
>> -``operator.add(x, y)`` is equivalent to the expression ``x+y``.  The function
>> -names are those used for special class methods; variants without leading and
>> -trailing ``__`` are also provided for convenience.
>
> 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. So some change was needed. I think a programmer 
can assume that they are are written in the implementation language to 
be as fast as possible. I do not think we should load the manual with 
'In CPython, this is implemented in C" notes all over. 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). And 
I remember that Guido has asked that the manual not discuss big O()
behavior of the methods of builtin classes.

I so see a note like "The binascii module contains low-level functions 
written in C for greater speed that are used by the higher-level 
modules." But that should be revised somehow for the same reason as 
operator. But I don't this this is typical. The heapq module makes no 
mention of _heapq. I think all this sort of stuff belong in a separate 
CPython Notes.

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. I presume that other implementations are not run with 
'python script.py', so the very first section is CPython specific 
anyway. In fact, I have the impression that for some *nix systems, that 
is CPython 2 specific.

-- 
Terry Jan Reedy