[Python-Dev] Convention on functions that shadow existing stdlib functions

[R. David Murray]

On Fri, 29 Jul 2011 11:49:01 -0400, Barry Warsaw <barry at python.org> wrote:
> If test.support is truly and only an internal implementation detail, then it
> should adhere to Pythonic convention for such things, and be renamed
> test._support.  Then you won't need to document it at all except in the
> module.

I'd be fine with renaming it and not documenting it, myself.  Other
developers prefer to have as much as practical documented in html form.

> Here's another problem with moving the documentation for test.support to the
> devguide.  They will invariably get out of sync.  It's hard enough to keep
> stdlib code and stdlib docs in sync, but I think it will be even harder to
> keep stdlib code in sync with devguide documentation.  It will also be harder
> to know what version of the devguide corresponds to what version of the code
> repository.

Which wouldn't be any more of a problem than the regular python docs if
the devguide were in the normal doc tree.  Just saying :)

--
R. David Murray           http://www.bitdance.com