[Django] #20503: django.test._doctest deprecation warning too agressive

[Django]

#20503: django.test._doctest deprecation warning too agressive
---------------------------------------------+------------------------
Reporter: akaariai | Owner: nobody
Type: Bug | Status: new
Component: Testing framework | Version: master
Severity: Normal | Keywords:
Triage Stage: Accepted | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
---------------------------------------------+------------------------
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.

--
Ticket URL: <https://code.djangoproject.com/ticket/20503>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#20503: django.test._doctest deprecation warning too agressive

-----------------------------------+---------------------------------------

Reporter: akaariai | Owner: nobody
Type: Bug | Status: new

Component: Testing framework | Version: 1.6-alpha-1
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-----------------------------------+---------------------------------------
Changes (by akaariai):

* version: master => 1.6-alpha-1

--
Ticket URL: <https://code.djangoproject.com/ticket/20503#comment:1>

[Django]

#20503: django.test._doctest deprecation warning too agressive

-----------------------------------+---------------------------------------

Reporter: akaariai | Owner: nobody
Type: Bug | Status: new

Component: Testing framework | Version: 1.6-alpha-1
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-----------------------------------+---------------------------------------

Comment (by carljm):

`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?

--
Ticket URL: <https://code.djangoproject.com/ticket/20503#comment:2>

[Django]

#20503: django.test._doctest deprecation warning too agressive

-----------------------------------+---------------------------------------

Reporter: akaariai | Owner: nobody
Type: Bug | Status: new

Component: Testing framework | Version: 1.6-alpha-1
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-----------------------------------+---------------------------------------

Comment (by aaugustin):

Yes, that option sounds good enough.

--
Ticket URL: <https://code.djangoproject.com/ticket/20503#comment:3>

[Django]

#20503: django.test._doctest deprecation warning too agressive

-----------------------------------+---------------------------------------
Reporter: akaariai | Owner: nobody
Type: Bug | Status: closed

Component: Testing framework | Version: 1.6-alpha-1

Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-----------------------------------+---------------------------------------
Changes (by Carl Meyer <carl@…>):

* status: new => closed
* resolution: => fixed

Comment:

In [changeset:"cd79f337233be3f2dfa22316314c9d4834093e31"]:
{{{
#!CommitTicketReference repository=""
revision="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.
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/20503#comment:4>