[Python-Dev] Documentation idea

[Brett Cannon]

On Thu, Oct 9, 2008 at 8:37 PM,  <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?
>       """
>

And that decorator is generic enough to work for both classes and functions.

> 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).

Which is why I would love to make this almost a policy for new modules
that do not have any C dependency.

>  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.
>

Add to this some function to help test both the pure Python and C
implementation, like ``py_version, c_version =
import_versions('itertools', '_c_itertools')``, so you can run the
test suite against both versions, and you then have pretty much
everything covered for writing the code in Python to start and
optimizing as needed in C.

-Brett