What's the difference between dir() and __dir__?

Question

in python what's the difference between dir() function and __dir__ attribute in python?

>>> 2 .__dir__()
['__divmod__', 'real', '__rxor__', '__floor__', '__hash__', '__index__', '__lt__', '__ceil__', '__repr__', '__reduce_ex__', '__rpow__', '__rand__', '__truediv__', '__subclasshook__', '__doc__', '__radd__', '__or__', '__pow__', '__trunc__', '__rrshift__', '__delattr__', '__reduce__', '__rlshift__', 'conjugate', '__xor__', '__rtruediv__', '__rfloordiv__', '__ge__', '__setattr__', '__class__', 'bit_length', '__neg__', '__mod__', '__int__', '__pos__', 'from_bytes', '__format__', '__rmul__', '__lshift__', '__rsub__', '__new__', '__add__', '__floordiv__', 'imag', 'to_bytes', 'numerator', '__dir__', '__abs__', '__init__', '__sizeof__', '__getnewargs__', '__getattribute__', '__invert__', '__gt__', '__rshift__', '__ne__', '__rdivmod__', '__mul__', '__and__', '__sub__', '__rmod__', '__round__', '__ror__', '__le__', '__eq__', '__float__', '__bool__', '__str__', 'denominator']
>>> dir(2)
['__abs__', '__add__', '__and__', '__bool__', '__ceil__', '__class__', '__delattr__', '__dir__', '__divmod__', '__doc__', '__eq__', '__float__', '__floor__', '__floordiv__', '__format__', '__ge__', '__getattribute__', '__getnewargs__', '__gt__', '__hash__', '__index__', '__init__', '__int__', '__invert__', '__le__', '__lshift__', '__lt__', '__mod__', '__mul__', '__ne__', '__neg__', '__new__', '__or__', '__pos__', '__pow__', '__radd__', '__rand__', '__rdivmod__', '__reduce__', '__reduce_ex__', '__repr__', '__rfloordiv__', '__rlshift__', '__rmod__', '__rmul__', '__ror__', '__round__', '__rpow__', '__rrshift__', '__rshift__', '__rsub__', '__rtruediv__', '__rxor__', '__setattr__', '__sizeof__', '__str__', '__sub__', '__subclasshook__', '__truediv__', '__trunc__', '__xor__', 'bit_length', 'conjugate', 'denominator', 'from_bytes', 'imag', 'numerator', 'real', 'to_bytes']

Answer 1

The docs explain it:

If the object has a method named __dir__(), this method will be called and must return the list of attributes. This allows objects that implement a custom __getattr__() or __getattribute__() function to customize the way dir() reports their attributes.

If the object does not provide __dir__(), the function tries its best to gather information from the object’s __dict__ attribute, if defined, and from its type object. The resulting list is not necessarily complete, and may be inaccurate when the object has a custom __getattr__().

Answer 2

dir calls __dir__ internally:

In [1]: class Hello():
   ...:     def __dir__(self):
   ...:         return [1,2,3]
   ...:     

In [2]: dir(Hello())
Out[2]: [1, 2, 3]

Answer 3

dir calls __dir__ method if it is present, from python documentation :

dir([object])¶ Without arguments, return the list of names in the current local scope. With an argument, attempt to return a list of valid attributes for that object.

If the object has a method named __dir__(), this method will be called and must return the list of attributes. This allows objects that implement a custom __getattr__() or __getattribute__() function to customize the way dir() reports their attributes.

If the object does not provide __dir__(), the function tries its best to gather information from the object’s __dict__ attribute, if defined, and from its type object. The resulting list is not necessarily complete, and may be inaccurate when the object has a custom __getattr__().

Answer 4

It's worth pointing out that the __dir__ on many objects cannot be customized, so if you call it directly there is no opportunity to place a shim/wrapper in there.

It's easy to replace the builtin dir and give it some special powers if you need to. Tricks like this can be very useful when debugging.