[Python-Dev] Documentation idea

Brett Cannon brett at python.org
Thu Oct 16 21:59:30 CEST 2008

On Thu, Oct 16, 2008 at 11:13 AM, Scott Dial
<scott+python-ideas at scottdial.com> wrote:
> Raymond Hettinger wrote:
>> * It will assist pypy style projects and other python implementations
>> when they have to build equivalents to CPython.
>> * 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.
> I haven't seen anyone comment about this assertion of "equivalence".
> Doesn't it strike you as difficult to maintain *two* versions of every
> function, and ensure they match *exactly*?

More time-consuming than difficult. Raymond is currently talking about
things like built-ins and methods on types who do not exactly change
very often.

> The utility to PyPy-style
> projects is minimized if the two version aren't identical. And while
> it's possible to say, "the tests say they are equiavelent, so they are;"
> history is quite clear about people depending on "features" that are
> untested and were unintended side-effects of the manner in which
> something was implemented.

Right, and when we find out that there is a difference, we typically
standardize on a specific version and developers using the bogus
semantics switch.

> I think it would be a dilution of developer
> man-hours to force them to maintain two versions in lock-step, and it
> significantly adds to the burden of writing and reviewing potential
> bugfixes.

Well, I don't see this applying to every extension module in the
stdlib that does not already have a pure Python equivalent. This view
also assumes that if this position was taken people will continue to
write extension modules when they are not necessarily needed. If this
actually makes people to write more pure Python code over extension
modules I think that is a plus.

And Raymond, more than probably anyone, can address the overhead he
has faced in maintaining both the pure Python version of itertools in
the docs and the extension module.

> While I applaud the idea of documenting C functions in this manner,
> let's not confuse documentation with equivalence. If the standard
> distribution of Python exports the C version, then all bets are off
> whether the Python version is a drop-in replacement (even if the
> buildbots regularly test them).

Well, considering we have not even gotten far enough to actually do
this for the documentation case, I think worrying about equivalence
might be jumping the gun slightly as it is more work as you point out,

But one thing about doing this is it might draw in the various
alternative VM folks to help maintain the Python code. If Jython,
IronPython, and/or PyPy actually use the Python code for themselves
then I suspect they would help with maintenance.


More information about the Python-Dev mailing list