<br><div class="gmail_quote">On Sun, Oct 31, 2010 at 9:11 AM, Barry Warsaw <span dir="ltr"><<a href="mailto:barry@python.org">barry@python.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">On Oct 29, 2010, at 08:14 PM, Raymond Hettinger wrote:<br>
<br>
>I would like to simplify and clean-up the API for the unittest module<br>
>by de-documenting assertSetEqual(), assertDictEqual(),<br>
>assertListEqual, and assertTupleEqual().<br>
<br>
</div>As a general principle, I think all public API methods should be documented.<br>
<br>
That still leaves plenty of room for simplification. Some ways to address<br>
both concerns could be:<br>
<br>
- moving the documentation to an "advanced" or "complete reference" section<br></blockquote><div><br></div><div>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:</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
- make the methods non-public by prepending an underscore<br>
- leaving them public but adding deprecation warnings to the code<br></blockquote><div><br></div><div>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.</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im"><br>
>All of those methods are already called automatically by<br>
>assertEqual(), so those methods never need to be called directly.<br></div></blockquote><div><br></div><div>For new code I agree and we should document them as such.</div><div><br></div><div>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.</div>
<div><br></div><div>The smarts about automagically calling an appropriate method from assertEqual were added during the sprints while contributing them at PyCon 2009.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">
>Or, if you need to be more explicit about the type checking for<br>
>sequences, the assertSequenceEqual() method will suffice.<br>
>Either way, there's no need to expose the four type specific methods.<br>
<br>
</div>It sounds like those methods should not be public then.<br></blockquote><div><br></div><div>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.</div>
<div><br></div><div>There is no maintenance burden to keeping these trivial methods for the convenience of code that has already used them.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im"><br>
>Given the purpose of the unittest module, it's important that<br>
>the reader have a crystal clear understanding of what a test<br>
>is doing. Their attention needs to be focused on the subject<br>
>of the test, not on questioning the semantics of the test method.<br>
<br>
</div>That's different documentation than a complete reference manual. A reference<br>
manual should contain all public methods, functions, classes and attributes.<br>
It's there so that when you see some third party code that uses it, you have<br>
an authoritative description of the semantics of that method. We owe it to<br>
our users to have complete reference material.<br>
<br>
OTOH, we also owe them clear guidelines on best practices for the use of our<br>
API. Often, this is either obvious or can live in the same documentation. By<br>
sectioning the documentation, the module docs can be organized to give both a<br>
user guide with opinionated recommendations, and a complete reference manual.<br></blockquote><div><br></div><div>Agreed.</div><div><br></div><div>-gps</div></div>