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

[Nick Coghlan]

On Fri, Jul 29, 2011 at 7:26 PM, Barry Warsaw <barry at python.org> wrote:
> 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).

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).

Agreed that docs.python.org front page should have a link to
docs.python.org/devguide, though.

Cheers.
Nick.

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