Does python `str()` function call `__str__()` function of a class?

Question

If I define a class with its own __str__() function, is str(a) equivalent to a.__str__(), where a is an instance of my class?

I checked the python doc, it doesn't say explicitly that this is the case.

Answer 1

Short answer: Yes!

---

According to the Python docs (I highlighted the relevant part):

object.__str__(self)

Called by str(object) and the built-in functions format() and print() to compute the “informal” or nicely printable string representation of an object. The return value must be a string object.

This method differs from object.__repr__() in that there is no expectation that __str__() return a valid Python expression: a more convenient or concise representation can be used.

The default implementation defined by the built-in type object calls object.__repr__().

So your_instance.__str__ is generally called when you do str(your_instance).

---

Longer answer: With "Special Methods" (the methods with two leading underscores and two trailing underscores) there is an exception because these are looked up on the class, not the instance. So str(a) is actually type(a).__str__(a) and not a.__str__(). But in most cases these are the same, because one rarely overrides methods of the class on the instance. Especially not special methods.

See also the relevant documentation on "Special method lookup":

For custom classes, implicit invocations of special methods are only guaranteed to work correctly if defined on an object’s type, not in the object’s instance dictionary.

So like @zzh1996 pointed out in the comments the following code will use the method defined on the class even though the instance has a custom callable __str__ attribute:

>>> class A(object):
...     def __str__(self):
...         return 'a'
>>> instance = A()
>>> instance.__str__ = lambda: 'b'
>>> str(instance)
'a'
>>> instance.__str__()
'b'