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

[Guido van Rossum]

On Thu, Jun 26, 2008 at 7:08 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> 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)

That would also remove the problem users encounter from time to time
with module files named "test.py".

But I think we should think about this more. I don't think anyone
expects the code inside any particular test_foo.py to have a stable
public interface. But quite a bit of the test support infrastructure
is reused by third party test frameworks. I think we should
acknowledge and support such reuse.

-- 
--Guido van Rossum (home page: http://www.python.org/~guido/)