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@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
