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

[R. David Murray]

On Fri, 29 Jul 2011 11:18:37 -0400, Barry Warsaw <barry at python.org> wrote:
> On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:
> >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.

In that case, you are working *on Python*.  Not using Python.
Personally, I'd expect such information to be in a devguide, although
really I'd not expect it to be documented at all, for most projects.
Making the devguide a more prominent part of the documentation would be
good: it would invite more people to cross that line and help us improve
Python.

As someone else pointed out, there is lots of stuff in the stdlib that
is not public API, and therefore not documented.  The problem with
test.support is that it is not a public API, but *is* documented.  So
logically either we should remove the documentation, or we should not
only do as you suggested by marking each function as not-a-stable-API,
but also document as many of the other internal APIs as we care to in
the same way.  That would doubtless help our users, but more care than
just marking functions as unstable would be required, I think.

Personally, I always thought the devguide should be part of Docs anyway.
It isn't because people didn't want it versioned along side Python,
but I still don't see why that would be a problem.

--
R. David Murray           http://www.bitdance.com