[Python-Dev] Undocumenting test.support in 3.x (was Py3k DeprecationWarning in stdlib)

[Nick Coghlan]

Benjamin Peterson wrote:
> On Wed, Jun 25, 2008 at 4:00 PM, Guido van Rossum <guido at python.org> wrote:
>> I'm a little worried about making stuff undocumented that every core
>> developer needs to use -- everyone writing tests needs to continue to
>> use test_support (now test.support?). I imagine people writing unit
>> test suites for 3rd party libraries might want to use its services
>> too.
> 
> I think undocumented is a little unspecific here. What I mean is
> "reserved for core Python tests and no promise is made to retain
> compatibility." Of course, we would keep docs for them (perhaps in
> Lib/test/README), so new core developers could write their tests.

Alternatively, we could just leave them out of the docs table of 
contents, and stick a big warning at the top saying that these are 
internal APIs and subject to change without warning between releases.

(This discussion actually argues somewhat in favour of having _test as 
the top-level package name for the regression test suite - after all, we 
make *zero* promises about keeping the API of any of the test modules 
the same from release to release, so we should really be using the 
standard leading underscore convention to flag internal implementation 
details that are not really intended for use by third parties)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org