[Python-Dev] Cleaning-up the new unittest API (original) (raw)

Gregory P. Smith greg at krypto.org
Sun Oct 31 17:54:11 CET 2010

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:

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

More information about the Python-Dev mailing list