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

R. David Murray rdmurray at bitdance.com
Fri Jul 29 18:13:44 CEST 2011

On Fri, 29 Jul 2011 11🔞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

More information about the Python-Dev mailing list