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

[Barry Warsaw]

On Jul 29, 2011, at 08:24 AM, Eli Bendersky wrote:

>Alright, I think there's now a sufficiently wide consensus to move the
>documentation of Lib/test and Lib/test/support in particular to the
>devguide, which raises a question:

I haven't been following this thread, so I caught up on Gmane.

I'm somewhat uncomfortable with this decision.  I understand why you want to
do this, but I still think it might not be the right thing.

For better or worse, test.support is part of the standard library, so moving
its documentation elsewhere sets a bad precedent to me.  Many times I work on
Python while completely off-line.  If I've had the foresight to build the docs
before I go off-line, all the better, but even if not, I have the .rst files
to consult.  Now I'll have to remember to *also* grab the devguide so that I
have the complete documentation of the stdlib.

I also think this underestimates how blurry the line is between users and
developers.  Think about yourself: when did you suddenly graduate from user of
Python to developer of Python?  I know that I often talk to people who would
consider themselves "just" users of Python, but feel comfortable with their
occasional spelunking into the Python tree looking for whatever nugget of code
or documentation will help them understand their problem.

The devguide, as useful and cool as it is, is still immature and hard to
discover.  I think more time will improve its organization, and it's not even
linked to from docs.python.org.

So I'm curious, why is this move better than adding noindexes, or just
trusting users to understand the difference between test.support.unlink() and
os.unlink()?  If I currently search for 'unlink', os.unlink comes up first,
which is good, and that should be preserved.  The presence or not of some
test.support.unlink documentation isn't going to make the search results that
much better or worse (there's already 14 hits).

Cheers,
-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/740a53c0/attachment.pgp>