[Python-Dev] Documentation idea

glyph at divmod.com glyph at divmod.com
Fri Oct 10 05:37:24 CEST 2008


On 9 Oct, 11:12 pm, python at rcn.com wrote:
>Background
>----------
>In the itertools module docs, I included pure python equivalents for 
>each of the C functions.  Necessarily, some of those equivalents are 
>only approximate but they seem to have greatly enhanced the docs.

Why not go the other direction?

Ostensibly the reason for writing a module like 'itertools' in C is 
purely for performance.  There's nothing that I'm aware of in that 
module which couldn't be in Python.

Similarly, cStringIO, cPickle, etc.  Everywhere these diverge, it is (if 
not a flat-out bug) not optimal.  External projects are encouraged by a 
wealth of documentation to solve performance problems in a similar way: 
implement in Python, once you've got the interface right, optimize into 
C.

So rather than have a C implementation, which points to Python, why not 
have a Python implementation that points at C?  'itertools' (and 
similar) can actually be Python modules, and use a decorator, let's call 
it "C", to do this:

    @C("_c_itertools.count")
    class count(object):
        """
        This is the documentation for both the C version of 
itertools.count
        and the Python version - since they should be the same, right?
        """

In Python itself, the Python module would mostly be for documentation, 
and therefore solve the problem that Raymond is talking about, but it 
could also be a handy fallback for sanity checking, testing, and use in 
other Python runtimes (ironpython, jython, pypy).  Many third-party 
projects already use ad-hoc mechanisms for doing this same thing, but an 
officially-supported way of saying "this works, but the optimized 
version is over here" would be a very useful convention.

In those modules which absolutely require some C stuff to work, the 
python module could still serve as documentation.


More information about the Python-Dev mailing list