[Python-Dev] Documentation idea
tjreedy at udel.edu
Fri Oct 10 22:45:02 CEST 2008
glyph at divmod.com wrote:
> On 9 Oct, 11:12 pm, python at rcn.com wrote:
>> 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:
> 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?
The ancient string module did something like this, except that the
rebinding of function names was done at the end by 'from _string import
*' where _string had C versions of some but not all of the functions in
string. (And the list of replacements could vary by version and
platform and compiler switches.) This was great for documenting the
string module. It was some of the first Python code I studied after the
The problem with that and the above (with modification, see below) is
the creation and discarding of unused function objects and the time
required to do so.
The advantage of the decorator version is that the compiler or module
loader could be special cased to recognize the 'C' decorator and try it
first *before* using the Python version, which would serve as a backup.
There could be a standard version in builtins that people could
replace to implement non-standard loading on a particular system. To
cater to other implementations, the name could be something other than
'C', or we could define 'C' to be the initial of "Code" (in the
implementation language). Either way, other implementation could start
with a do-nothing "C" decorator and run the file as is, then gradually
replace with lower-level code.
Terry Jan Reedy
More information about the Python-Dev