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

Terry Reedy tjreedy at udel.edu
Tue Dec 20 11:27:41 CET 2011

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

More information about the Python-Dev mailing list