On 15 August 2013 14:08, Steven D'Aprano email@example.com wrote:
- The API doesn't really feel very Pythonic to me. For example, we write:
rather than mystring.justify(width, "right") or dict.iterate("items"). So I think individual methods is a better API, and one which is more familiar to most Python users. The only innovation (if that's what it is) is to have median a callable object.
Although you're talking about median() above I think that this same reasoning applies to the mode() signature. In the reference implementation it has the signature:
def mode(data, max_modes=1): ...
The behaviour is that with the default max_modes=1 it will return the unique mode or raise an error if there isn't a unique mode:
mode([1, 2, 3, 3])
StatisticsError: no mode
mode([1, 1, 2, 3, 3])
You can use the max_modes parameter to specify that more than one mode is acceptable and setting max_modes to 0 or None returns all modes no matter how many. In these cases mode() returns a list:
mode([1, 1, 2, 3, 3], max_modes=2)
mode([1, 1, 2, 3, 3], max_modes=None)
I can't think of a situation where 1 or 2 modes are acceptable but 3 is not. The only forms I can imagine using are mode(data) to get the unique mode if it exists and mode(data, max_modes=None) to get the set of all modes. But for that usage it would be better to have a boolean flag and then either way you're at the point where it would normally become two functions.
Also I dislike changing the return type based on special numeric values:
mode([1, 2, 3, 3], max_modes=0)
mode([1, 2, 3, 3], max_modes=1)
mode([1, 2, 3, 3], max_modes=2)
mode([1, 2, 3, 3], max_modes=3)
My preference would be to have two functions, one called e.g. modes() and one called mode(). modes() always returns a list of the most frequent values no matter how many. mode() returns a unique mode if there is one or raises an error. I think that that would be simpler to document and easier to learn and use. If the user is for whatever reason happy with 1 or 2 modes but not 3 then they can call modes() and check for themselves.
Also I think that:
 but I expect others to disagree.