django.test._doctest deprecation warning too agressive

[Anssi Kääriäinen]

Both django.test.simple and django.test.testcases import django.test._doctest, and django.test._doctest gives deprecation warning on import. So, any project using any tests will give a false deprecation warning. Applies to 1.6 alpha.

I think giving the warning when some _doctest code is actually used is the correct approach.

[Carl Meyer]

django.test.simple is itself deprecated (the entire module), so I'm not concerned about it using django.test._doctest, but django.test.testcases is a problematic oversight. Not sure why I never noticed these deprecation warnings in my tests.

I'm hesitant to make your suggested fix for a couple reasons:

1. There are quite a number of different functions and classes in django.test._doctest; adding a deprecation warning to all of them would be quite invasive surgery.

2. The entire module will be removed at the end of the deprecation period, and _any_ import from it (even just an import of the module itself without using anything from it) will break at that time. Thus, if the goal of a deprecation warning is to warn in the same cases that will break in the future, a module-level import-time warning is the only correct option when the module itself will be removed.

The only alternative I see is to move OutputChecker and DocTestRunner from django.test.testcases to django.test.simple (which is where the other deprecated test-running code lives, and is the only place they are used; it's a bit strange that they are defined in django.test.testcases to begin with). This would quarantine all of the deprecated code in the two deprecated modules (django.test.simple and django.test._doctest) and solve the problem. This has the potential to break user code which imported those two classes directly from django.test.testcases; on the other hand, they were never public or documented classes in the first place, so I think we could do this.

I lean towards that latter option; thoughts?

[Aymeric Augustin]

Yes, that option sounds good enough.

[Carl Meyer <carl@…>]

In cd79f337233be3f2dfa22316314c9d4834093e31:

Fixed #20503 - Moved doctest utilities in with the rest of the deprecated test code.

The DocTestRunner and OutputChecker were formerly in
django.test.testcases, now they are in django.test.simple. This avoids
triggering the django.test._doctest deprecation message with any import
from django.test. Since these utility classes are undocumented internal
API, they can be moved without a separate deprecation process.

Also removed the deprecation warnings specific to these classes, as they are
now covered by the module-level warning in django.test.simple.

Thanks Anssi for the report.

Refs #17365.