Built-in Functions for Inspection

The dir() function reveals all capabilities (methods and attributes) of any Python object by returning a list of strings.

Programming

A Capability Inventory

When you work with a Python object, you may need to discover what it can do. Can it add items, sort them, reverse them, or provide other attributes? Instead of memorizing every capability of every object type, you can use the built-in dir() function. It returns a list of strings containing the names of the methods and attributes available on the object.

What do you think happens?

What kind of value does dir() return when you inspect a list object?

A single string
A number
A list of strings
A method that must be called again

Reveal answer

Answer:

A list of strings

Each string is the name of a capability that the object has. The names include both ordinary methods and double-underscore, or dunder, methods.

python

my_list = [3, 1, 2]
dir(my_list)

my_list = [3, 1, 2]
dir(my_list)

Output

A list of strings containing names such as append, sort, reverse, __add__, and __len__. The complete list can contain additional names.

Reading the Returned Names

The result of dir(my_list) is not a list of the object's current values. It is a list of names. Each name represents an actual capability available on the object. For example, seeing append tells you that the list has an append method. Seeing sort tells you that the list has a sort method. Seeing an attribute name tells you that the object exposes that attribute. In this way, dir() acts like an inventory of what the object can do or provide at the moment you inspect it.

How does each string returned by dir(obj) relate to an actual capability of the object?

Worked example

Interpreting Three Names

Suppose dir(my_list) includes append, sort, and __len__. What does each name tell you?

1
append
The object has an append method. The method can be called as my_list.append(5).
2
sort
The object has a sort method. The method can be called as my_list.sort().
3
__len__
The object has a dunder method associated with the len() function. Python uses __len__ internally when len() is used.

Result

The names returned by dir() are clues to real operations or attributes available on the object.

Standard and Dunder Methods

Name category	How it appears	How it is used
Standard method	append, sort, reverse	Called directly as an object action, such as my_list.append(5)
Dunder method	__add__, __len__	Usually used by Python internally for operators or built-in functions

Two categories of names that can appear in dir() output

Names wrapped in double underscores are called dunder methods, short for double underscore methods. Python uses these special methods to implement core language features. For example, __add__ is what Python calls when you use the plus operator, and __len__ is what Python calls when you use the len() function. You usually use the operator or built-in function rather than calling the dunder method directly.

What is the difference between ordinary method names and dunder method names in the same dir() result?

Exploring an Unfamiliar Object

dir() is especially useful when you receive an object from a library or another part of a program and do not yet know which operations it supports. Inspect the object first, read the returned names, and then investigate a capability that matches your goal. For example, if the returned names include append, sort, or reverse, those names identify actions available on the object.

How can a programmer move from an unfamiliar object to a capability worth investigating?

python

my_list = [3, 1, 2]
dir(my_list)
my_list.append(5)
my_list.sort()
my_list.reverse()

my_list = [3, 1, 2]
dir(my_list)
my_list.append(5)
my_list.sort()
my_list.reverse()

The inspection call does not perform the listed actions. It reveals their names. You still choose whether to call a standard method such as append, sort, or reverse, depending on what you want the object to do.

Inspecting the Current State

dir() reflects the actual state of an object at the moment you call it. If an attribute is added to an object dynamically, that name appears the next time you inspect the object. This makes dir() useful during debugging: it can show which capabilities are available now and help you notice when an expected capability is missing.

Worked example

Using an Inspection Result as a Snapshot

You inspect an object and do not see a capability you expected. What should you consider?

1
Check the object
Confirm that you are inspecting the object you intended to use.
2
Consider its type
The object might be a custom object with dynamically added attributes, or it might be a subclass that inherits capabilities from a parent class.
3
Inspect again
Call dir() again if the object's state may have changed. The result represents the capabilities available at that moment.

Result

A dir() result is a current snapshot of available names, not a permanent description of every object you might later work with.

Mistakes with dir()

Common mistake
Treating dir() as if it returns the object's data values
What it looks like
```
Expecting dir(my_list) to return 3, 1, and 2
```
Why it fails
dir() returns a list of strings containing capability names, not the current values stored in the object.
Do this instead
Read each returned string as the name of an attribute or method available on the object.
Common mistake
Assuming every returned name is a standard method to call directly
What it looks like
Calling __len__ by name simply because it appears in the result
Why it fails
Dunder methods are used by Python internally to implement features such as operators and built-in functions.
Do this instead
Recognize names such as __len__ as special methods and understand that len() uses __len__ behind the scenes.
Common mistake
Assuming the output contains only familiar actions
What it looks like
Ignoring names such as __add__ and __len__ because they do not look like append or sort
Why it fails
dir() includes both standard methods and dunder methods.
Do this instead
Separate ordinary names from double-underscore names when reading the result.
Common mistake
Treating one inspection result as permanent
What it looks like
Assuming the list of names cannot change after an attribute is added dynamically
Why it fails
dir() reflects the object's actual state when it is called.
Do this instead
Inspect the object again after its available attributes or capabilities may have changed.

Practice and Takeaways

EASY

Imagine that dir() returns the names append, reverse, __add__, and __len__ for an object. Classify each name as a standard method or a dunder method, then explain what the presence of append and __len__ tells you about the object.

Hints

Look for names wrapped in double underscores.
A standard method is an ordinary object action that can be called directly.
The source explains that __len__ is associated with the len() function.

Your attempt (not saved)

1
dir() returns a list of strings naming the capabilities available on a Python object. The result includes both standard methods, such as append, sort, and reverse, and dunder methods, such as __add__ and __len__. Each returned name corresponds to an actual attribute or method available through the object. Use dir() to explore unfamiliar objects, interpret unexpected capabilities, and inspect the object's current state while debugging.

At a glance

dir() returns a list of strings naming an object's available methods and attributes.
Ordinary names such as append, sort, and reverse identify standard methods that can be called directly.
Names surrounded by double underscores identify dunder methods that Python uses internally for features such as operators and built-in functions.
Each name in the result maps to an actual capability on the inspected object.
dir() is useful for exploring unfamiliar objects and checking their current capabilities during debugging.

More concepts starting with B