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

[Barry Warsaw]

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
- make the methods non-public by prepending an underscore
- leaving them public but adding deprecation warnings to the code

>All of those methods are already called automatically by 
>assertEqual(), so those methods never need to be called directly.  
>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.

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

Cheers,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101031/0155b28d/attachment.pgp>