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

Eli Bendersky eliben at gmail.com
Fri Jul 29 13:07:50 CEST 2011

>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

Why is it part of stdlib though? Isn't the stdlib something that's exposed to all Python programmers? How should an ordinary programmer (not a core dev) know some parts of stdlib are out of limits, if they are even documented and appear in the index - should he read the note at the top of the documentation page? Imagine a desperate programmer behind schedule who is looking for some particular functionality in stdlib and finds it in test.support - will he not use it and later complain we don't keep backwards-compatibility. Sure, he's at fault, but I think we can make such cases much rarer by making the distinction between user-exposed modules and core-dev-exposed modules more explicit.

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 think this is because you're experienced and probably know all the contents of the devguide anyway. Junior core-devs need the devguide handy for other reasons as well.

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.

Isn't this what we're trying to prevent, though? One should never even have to look at test.support unless he's working on Python.

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. Maybe this is the main point here - what makes it immature? What makes it hard to discover? Maybe these issues can be fixed.

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

I think the unlink&rmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself.

Eli -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20110729/26b7cd0d/attachment.html>

More information about the Python-Dev mailing list