[Python-Dev] Convention on functions that shadow existing stdlib functions (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Sat Jul 30 17:23:40 CEST 2011

On Sat, Jul 30, 2011 at 1:49 AM, Barry Warsaw <barry at python.org> wrote:

On Jul 30, 2011, at 01:02 AM, Nick Coghlan 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.

Aside from test.regrtest and test.support, the entirety of the rest of the test package is completely undocumented. test.support is unique, as it is the only component other than the main executable that is documented at all, solely for the benefits of people writing new tests. We don't even document the resources that can be enabled from the command line, instead telling people to look at the command line help output.

The entire test package is an implementation detail, underscore or no underscore - we will never, ever, offer any kind of backwards compatibility guarantee for code in that part of the package hierarchy.

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.

By that reasoning, we should just give up and delete the test.support docs entirely (since they're already treated with disrespect by contrast to the real stdlib docs).

It sounds to me like you're really objecting to the devguide living in a separate clone. This doesn't bode well for the prospects of ever splitting the stdlib out from the CPython interpreter core...

Cheers, Nick.

-- Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list