[Python-Dev] Cleaning-up the new unittest API (original) (raw)
Barry Warsaw barry at python.org
Sun Oct 31 17:11:50 CET 2010
- Previous message: [Python-Dev] Cleaning-up the new unittest API
- Next message: [Python-Dev] Cleaning-up the new unittest API
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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>
- Previous message: [Python-Dev] Cleaning-up the new unittest API
- Next message: [Python-Dev] Cleaning-up the new unittest API
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]