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

[Barry Warsaw]

On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:

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

How common are those mistakes right now?  I get way more complaints about
squishy APIs in third party libraries and actual *supported* parts of the
stdlib than I do about test.support APIs.

What's the real problem we're trying to solve anyway?  Is it "protect the
harried user from some future breakage" or "eliminate complaints we Python
developers get from harried users"?

I'd much rather solve this problem by adding markup to functions that
explicitly disclaim our normal backward compatibility guarantees.  Squirreling
away documentation for some parts of the stdlib seems similar to
security-by-obscurity arguments.

test.support *is* part of the stdlib.  If you want to propose moving it out of
the stdlib, that's a different argument to make.  Maybe Python's entire test
suite should be in some Cheeseshop package instead of in the core source
tree.  (I wouldn't agree with that either, but I'm just saying.)

So once again, is this a real actual problem you've witnessed in enough cases
to go through all the trouble of moving the documentation, and making it more
difficult to find?

>> 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'm not saying the devguide isn't handy - in fact it's incredibly handy!  I
love that it explains the nuances of how we structure our Mercurial branches,
and define our workflow for example.  I readily admit those are not things I
know by heart. (But actually, those instructions are not always easy to find,
which is why I think the organization is immature.  I'm not faulting the
devguide authors, I just think it needs more time to bake.)

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

Again, I think that line is blurred here.  Let's say you're working on some
off-beat or new hardware and you want to know if your basic tool chain works
for it.  You build Python, run the test suite, and something fails.  You
probably don't consider yourself a Python developer, but now you're digging
through the test.support to figure out your problem.  Yes, I've seen this
happen.

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

Sure, there are issues that can be fixed, but they're unrelated to documenting
test.support.

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

Let's see!

I think the devguide should document things like "how to submit bugs", "how to
use Mercurial", "how to propose changes to Python", "how to ensure code works
across all existing interpreter implementations", "where to find continuous
integration results and how to interpret them", "what's the right forum to
discuss Python", etc.  I.e. processes, workflows, and conventions that are
important cultural artifacts we've built up over 20 years.

I don't think the devguide should document the actual code we ship.

-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/4178ed5a/attachment.pgp>