On Thu, Oct 9, 2008 at 4:12 PM, Raymond Hettinger <[EMAIL PROTECTED]> wrote: [SNIP] > 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). >
The idea is great. I assume the special file support is mostly for the built-ins since extension modules can do what heapq does; have a pure Python version people import and that code pulls in any supporting C code. As for an implementation, you could go as far as to have a flag in the extension module that says, "look for Python equivalents" and during module initialization find the file and pull it in. Although doing it that way would not necessarily encourage people as much to start with the pure Python version and then only do C equivalents when performance or design requires it. > 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 > And have some way to test both the Python and C version with the same tests (when possible)? -Brett _______________________________________________ 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
