Why does Python have a format function as well as a format method

Question

The format function in builtins seems to be like a subset of the str.format method used specifically for the case of a formatting a single object.

eg.

&         


        

Answer 1

tldr; format just calls obj.__format__ and is used by the str.format method which does even more higher level stuff. For the lower level it makes sense to teach an object how to format itself.

It is just syntactic sugar

The fact that this function shares the name and format specification with str.format can be misleading. The existence of str.format is easy to explain: it does complex string interpolation (replacing the old % operator); format can format a single object as string, the smallest subset of str.format specification. So, why do we need format?

The format function is an alternative to the obj.format('fmt') construct found in some OO languages. This decision is consistent with the rationale for len (on why Python uses a function len(x) instead of a property x.length like Javascript or Ruby).

When a language adopts the obj.format('fmt') construct (or obj.length, obj.toString and so on), classes are prevented from having an attribute called format (or length, toString, you got the idea) - otherwise it would shadow the standard method from the language. In this case, the language designers are placing the burden of preventing name clashes on the programmer.

Python is very fond of the PoLA and adopted the __dunder__ (double underscores) convention for built-ins in order to minimize the chance of conflicts between user-defined attributes and the language built-ins. So obj.format('fmt') becomes obj.__format__('fmt'), and of course you can call obj.__format__('fmt') instead of format(obj, 'fmt') (the same way you can call obj.__len__() instead of len(obj)).

Using your example:

>>> '{0:x}'.format(13)
'd'
>>> (13).__format__('x')
'd'
>>> format(13, 'x')
'd'

Which one is cleaner and easier to type? Python design is very pragmatic, it is not only cleaner but is well aligned with the Python's duck-typed approach to OO and gives the language designers freedom to change/extend the underlying implementation without breaking legacy code.

The PEP 3101 introduced the new str.format method and format built-in without any comment on the rationale for the format function, but the implementation is obviously just syntactic sugar:

def format(value, format_spec):
    return value.__format__(format_spec)

And here I rest my case.

What Guido said about it (or is it official?)

Quoting the very BDFL about len:

First of all, I chose len(x) over x.len() for HCI reasons (def __len__() came much later). There are two intertwined reasons actually, both HCI:

(a) For some operations, prefix notation just reads better than postfix — prefix (and infix!) operations have a long tradition in mathematics which likes notations where the visuals help the mathematician thinking about a problem. Compare the easy with which we rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of doing the same thing using a raw OO notation.

(b) When I read code that says len(x) I know that it is asking for the length of something. This tells me two things: the result is an integer, and the argument is some kind of container. To the contrary, when I read x.len(), I have to already know that x is some kind of container implementing an interface or inheriting from a class that has a standard len(). Witness the confusion we occasionally have when a class that is not implementing a mapping has a get() or keys() method, or something that isn’t a file has a write() method.

Saying the same thing in another way, I see ‘len‘ as a built-in operation. I’d hate to lose that. /…/

source: pyfaq@effbot.org (original post here has also the original question Guido was answering). Abarnert suggests also:

There's additional reasoning about len in the Design and History FAQ. Although it's not as complete or as good of an answer, it is indisputably official. – abarnert

Is this a practical concern or just syntax nitpicking?

This is a very practical and real-world concern in languages like Python, Ruby or Javascript because in dynamically typed languages any mutable object is effectively a namespace, and the concept of private methods or attributes is a matter of convention. Possibly I could not put it better than abarnert in his comment:

Also, as far as the namespace-pollution issue with Ruby and JS, it's worth pointing out that this is an inherent problem with dynamically-typed languages. In statically-typed languages as diverse as Haskell and C++, type-specific free functions are not only possible, but idiomatic. (See The Interface Principle.) But in dynamically-typed languages like Ruby, JS, and Python, free functions must be universal. A big part of language/library design for dynamic languages is picking the right set of such functions.

For example, I just left Ember.js in favor of Angular.js because I was tired of namespace conflicts in Ember; Angular handles this using an elegant Python-like strategy of prefixing built-in methods (with $thing in Angular, instead of underscores like python), so they do not conflict with user-defined methods and properties. Yes, the whole __thing__ is not particularly pretty but I'm glad Python took this approach because it is very explicit and avoid the PoLA class of bugs regarding object namespace clashes.

Answer 2

I think format and str.format do different things. Even though you could use str.format for both, it makes sense to have separate versions.

The top level format function is part of the new "formatting protocol" that all objects support. It simply calls the __format__ method of the object it is passed, and returns a string. This is a low-level task, and Python's style is to usually have builtin functions for those. Paulo Scardine's answer explains some of the rationale for this, but I don't think it really addresses the differences between what format and str.format do.

The str.format method is a bit more high-level, and also a bit more complex. It can not only format multiple objects into a single result, but it can also reorder, repeat, index, and do various other transformations on the objects. Don't just think of "{}".format(obj). str.format is really designed for more about complicated tasks, like these:

"{1} {0} {1!r}".format(obj0, obj1) # reorders, repeats, and and calls repr on obj1
"{0.value:.{0.precision}f}".format(obj) # uses attrs of obj for value and format spec
"{obj[name]}".format(obj=my_dict) # takes argument by keyword, and does an item lookup

For the low-level formatting of each item, str.format relies on the same machinery of the format protocol, so it can focus its own efforts on the higher level stuff. I doubt it actually calls the builtin format, rather than its arguments' __format__ methods, but that's an implementation detail.

While ("{:"+format_spec+"}").format(obj) is guaranteed to give the same results as format(obj, format_spec), I suspect the latter will be a bit faster, since it doesn't need to parse the format string to check for any of the complicated stuff. However the overhead may be lost in the noise in a real program.

When it comes to usage (including examples on Stack Overflow), you may see more str.format use simply because some programmers do not know about format, which is both new and fairly obscure. In contrast, it's hard to avoid str.format (unless you have decided to stick with the % operator for all of your formatting). So, the ease (for you and your fellow programmers) of understanding a str.format call may outweigh any performance considerations.