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

[Barry Warsaw]

On Jul 30, 2011, at 01:02 AM, Nick Coghlan wrote:

>It's worthwhile because it is what the devguide is for: documenting
>how to *change* Python, rather than just using it as it is delivered
>to you. There's a clear transition from user of Python to developer of
>Python: you stop treating the standard library (and perhaps even the
>interpreter core) as sacrosanct, and will actually change the code in
>those files if its wrong (and is affecting your own application).

I'm not so sure the line's that bright.  But anyway...

Using the criteria in your first sentence, test.support is clearly "what's
delivered to you" not "changing Python".  IOW, we ship test.support in the
tarball, so *if* it's to be documented, then the stdlib is the right place to
document it, IMO.

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.

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.

-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-dev/attachments/20110729/724d320f/attachment.pgp>