[Python-Dev] Documentation idea

[Jared Grubb]

This is a really interesting idea. If extra memory/lookup overhead is  
a concern, you could enable this new feature by default when the  
interactive interpreter is started (where it's more likely to be  
invoked), and turn it off by default when running scripts/modules.

Jared

On 9 Oct 2008, at 20:37, glyph at divmod.com wrote:

>
> 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.
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/jared.grubb%40gmail.com