[Python-Dev] Cleaning-up the new unittest API

[Gregory P. Smith]

On Sun, Oct 31, 2010 at 9:11 AM, Barry Warsaw <barry at python.org> wrote:

> On Oct 29, 2010, at 08:14 PM, Raymond Hettinger wrote:
>
> >I would like to simplify and clean-up the API for the unittest module
> >by de-documenting assertSetEqual(), assertDictEqual(),
> >assertListEqual, and assertTupleEqual().
>
> As a general principle, I think all public API methods should be
> documented.
>
> That still leaves plenty of room for simplification.  Some ways to address
> both concerns could be:
>
> - moving the documentation to an "advanced" or "complete reference" section
>

Agreed, I perfer simply deemphasizing these methods by reorganizing the
documentation and mentioning in their documentation to, "just use
assertEqual."  De-documenting them is the first step towards causing
unnecessary pain by taking either of the next two steps:

- make the methods non-public by prepending an underscore
> - leaving them public but adding deprecation warnings to the code
>

Please do not make any existing released methods from the unittest module
non-public or add any deprecation warnings.  That will simply cause
unnecessary code churn and pain for people porting their code from one
version to the next without benefiting anyone.


> >All of those methods are already called automatically by
> >assertEqual(), so those methods never need to be called directly.
>

For new code I agree and we should document them as such.

They _do_ have value on their own when called directly.  They offer an
explicit type check as part of their assertion and are much easier to read
for that than manually passing the parameter to assertSequenceEqual(a, b,
seq_type=xxx).  How often they are used for that reason is hard for me to
measure as the giant code base we have at work that uses these was written
over the years prior to assertEqual automagically calling these methods
based on input types so its uses tend to be a mix of cases where the type
check doesn't matter and a small fraction of cases where it is important.

The smarts about automagically calling an appropriate method from
assertEqual were added during the sprints while contributing them at PyCon
2009.


>  >Or, if you need to be more explicit about the type checking for
> >sequences, the assertSequenceEqual() method will suffice.
> >Either way, there's no need to expose the four type specific methods.
>
> It sounds like those methods should not be public then.
>

I strongly prefer de-documenting them to making anything already released as
public be nonpublic.  That leads to pain for people moving to new versions
of Python.

There is no maintenance burden to keeping these trivial methods for the
convenience of code that has already used them.


> >Given the purpose of the unittest module, it's important that
> >the reader have a crystal clear understanding of what a test
> >is doing.  Their attention needs to be focused on the subject
> >of the test, not on questioning the semantics of the test method.
>
> That's different documentation than a complete reference manual.  A
> reference
> manual should contain all public methods, functions, classes and
> attributes.
> It's there so that when you see some third party code that uses it, you
> have
> an authoritative description of the semantics of that method.  We owe it to
> our users to have complete reference material.
>
> OTOH, we also owe them clear guidelines on best practices for the use of
> our
> API.  Often, this is either obvious or can live in the same documentation.
>  By
> sectioning the documentation, the module docs can be organized to give both
> a
> user guide with opinionated recommendations, and a complete reference
> manual.
>

Agreed.

-gps
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101031/e9b48b9f/attachment-0001.html>