ndarray should offer __format__ that can adjust precision

In many wonderful cases an ndarray can be used in place of a Python float and Just Work.

But not in one case:

import numpy as np

n = 1.23
print('{0:.6} AU'.format(n))

n = np.array([1.23, 4.56])
print('{0:.6} AU'.format(n))

The output of the above code, at least under Python 3.4, is:

1.23 AU
Traceback (most recent call last):
  File "tmp9.py", line 7, in <module>
    print('{0:.6} AU'.format(n))
TypeError: non-empty format string passed to object.__format__

It would be a great convenience if the ndarray grew a __format__() method that understood the tiny mini-language of float formatting, and used the number of digits of precision specified there to make its own call to the standard NumPy vector array formatting. Users could control array appearance on the screen using a Python standard that many programmers already understand.

[shoyer]

@gustavla see here for the numpy-discussion mailing list. But I don’t think this has been discussed before.

Our rule is that API changes need to reach consensus on the mailing list. This feature feels like a pretty clear win to me (especially with the arrival of f-strings), so I don’t anticipate any objections. Still, it would be good to come up with a concrete proposal on how it should work and run that by the mailing list before starting work.

[brandon-rhodes]

Python lists and tuples do not support __format__() because (a) they are non-uniform — they can have any sorts of data inside, so it is not clear whether a format string would be interpreted numerically or for strings or what, and (b) because they really do no formatting of their own: they just wrap their own parens and commas around the repr()'s of whatever strings, ints, floats, and other objects that they happen to contain.

A NumPy array—unless its members are of dtype object_, in which case I entirely agree with you that the array should follow the excellent lead of tuple() and list() by refusing any format string—is in a quite different situation: if it is numeric, then it does not contain smaller objects, and therefore cannot delegate to them with repr(). Instead it takes charge of formatting the floats or ints inside for the screen, making all kinds of format-y decisions like indentation, breaking its output into lines, and even omitting sections of data if there are too may floats.

The change in behavior was simply to avoid disappointing users who provide a format string: if the string is accepted by a type, and raises no error, then people reasonably expect to see some change in format, but were not doing so — under the old Python 2 behavior — and instead were having their format string accepted quietly but then just ignored. Here is the issue in which it was negotiated that an error was better for uses than an ignored formatting string:

http://bugs.python.org/issue7994

I propose that NumPy arrays adhere quite strictly to this standard behavior: in situations where the array itself is formatting its contents, accepting and using the string will allow the user to decide how many decimal places are shown, in the standard way that users already set the precision of data they are printing. In situations where the NumPy array contains other objects, and is doing no numeric formatting of its own, then I see no problem with its ignoring the format string (unless someone wants to make the argument that a NumPy array ought to broadcast it to its members!) and raising the “you gave me a format string I can’t use!” exception that is now standard in Python to warn users away from trying to format things in situations where the format will be ignored.