Documentation idea

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.  Something similar is in
the builtin docs for 
any() and all().  The new collections.namedtuple() factory function also includes a verbose option that
prints a pure python 
equivalent for the generated class. And in the decimal module, I took examples directly from the spec and
included them in 
doc-testable docstrings.  This assured compliance with the spec while providing clear examples to anyone
who bothers to look at the 
docstrings.

For itertools docs, I combined those best practices and included sample calls in the pure-python code (see
the current docs for 
itertools to see what I mean -- perhaps look at the docs for a new tool like itertools.product() or
itertools.izip_longest() to see 
how useful it is).

Bright idea
----------
Let's go one step further and do this just about everywhere and instead of putting it in the docs, attach an
exec-able string as an 
attribute to our C functions.  Further, those pure python examples should include doctests so that the user
can see a typical 
invocation and calling pattern.

Say we decide to call the attribute something like ".python", then you could write something like:

    >>> print(all.python)
   def all(iterable):
        '''Return True if all elements of the iterable are true.

        >>> all(isinstance(x, int) for x in [2, 4, 6.13, 8])
        False
        >>> all(isinstance(x, int) for x in [2, 4, 6, 8])
        True
        '''

        for element in iterable:
            if not element:
                 return False
        return True

There you have it, a docstring, doctestable examples, and pure python equivalent all in one place.  And
since the attribute is 
distinguished from __doc__, we can insist that the string be exec-able (something we can't insist on for
arbitrary docstrings).

Benefits
--------

* I think this will greatly improve the understanding of tools like str.split() which have proven to be
difficult to document with 
straight prose.  Even with simple things like any() and all(), it makes it self-evident that the functions
have early-out behavior 
upon hitting the first mismatch.

* The exec-able definitions and docstrings will be testable

* It will assist pypy style projects and other python implementations when they have to build equivalents
to CPython.

* We've gotten good benefits from doctests for pure python functions, why not extend this best practice to
our C functions.

* The whole language will become more self-explanatory and self-documenting.

* Will eliminate confusion about what functions were exactly intended to do.

* Will confer benefits similar to test driven development where the documentation and  pure python version
are developed first and 
doctests gotten to pass, then the C version is created to match.

* For existing code, this is a perfect project for people who want to start contributing to the language but
aren't ready to start 
writing C (the should be able to read C however so that the equivalent really does match the C code).

Limits
-----

* In some cases, there may be no pure python equivalent (i.e. sys.getsize()).

* Sometimes the equivalent can only be approximate because the actual C function is too complex (i.e. itertools.tee()).

* Some cases, like int(), are useful as a type, have multiple functions, and are hard to write as pure python equivalents.

* For starters, it probably only makes to do this for things that are more "algorithmic" like any() and all()
or things that have a 
straight-forward equivalent like property() written using descriptors.

Premise
-------

Sometimes pure python is more expressive, precise, and easy to read than English prose. 

_______________________________________________
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/python-python-dev%40m.gmane.org