dir()

The built-in dir() function lists the names in the current local scope when you call it without arguments. When you call it using an object as an argument, it attempts to return a list of valid attributes for that object:

Python 
>>> dir()
[
    '__annotations__',
    '__builtins__',
    '__doc__',
    ...
]

>>> dir(str)
[
    '__add__',
    '__class__',
    '__contains__',
    ...
]

dir() Signatures

Python Syntax 
dir()
dir(object)

Arguments

Argument Description
object The object whose attributes you want to list

Return Value

  • Without an argument, dir() returns a list of names in the current local scope.
  • With an object as an argument, it returns a list of attributes and methods of that object, which may include class attributes and instance attributes.

dir() Examples

With no arguments, to list names in the current scope:

Python 
>>> dir()
[
    '__annotations__',
    '__builtins__',
    '__doc__',
    ...
]

With a built-in class object as an argument:

Python 
>>> dir(list)
[
    '__add__',
    '__class__',
    '__contains__',
    ...,
    'append',
    'clear',
    ...
]

With a module object as an argument:

Python 
>>> import math
>>> dir(math)
[
    '__doc__',
    '__loader__',
    '__name__',
    ...,
    'acos',
    'acosh',
    'asin',
    'asinh',
    ...
]

dir() Common Use Cases

The most common use cases for the dir() function include:

  • Inspecting the list of names in the current scope during interactive sessions
  • Exploring the attributes and methods of an object
  • Debugging by checking which names are available in a given context

dir() Real-World Example

Suppose you’re working on a project and need to explore the attributes and methods of a module you just imported. You can use dir() to list everything available in the module, which can help you understand how to interact with it:

Python 
>>> import json
>>> dir(json)
[
    'JSONDecodeError',
    'JSONDecoder',
    'JSONEncoder',
    '__all__',
    '__builtins__',
    ...,
    'decoder',
    'dump',
    'dumps',
    'encoder',
    ...
]

By calling dir(json), you get a list of available functions and classes in the json module, which helps you understand how to use the module effectively.

dir() in Custom Classes

You can support the dir() function in a custom class by implementing the .__dir__() special method. Here’s an example of a class where dir() won’t list the non-public attributes:

Python person.py 
class Person:
    def __init__(self, name, age, salary):
        self.name = name
        self.age = age
        self._salary = salary

    def profile(self):
        print(f"Name: {self.name}")
        print(f"Age: {self.age}")

    def __dir__(self):
        all_attrs = super().__dir__()
        return [attr for attr in all_attrs if not attr.startswith("_")]

# Usage
alice = Person("Alice", 30, 50000)
print(dir(alice)) # Output: ['age', 'name', 'profile']

In this example, the Person class defines a .__dir__() method that filters out the non-public attributes. With this implementation, the output of dir() only shows the public attributes.

Python's Built-in Functions: A Complete Exploration

Tutorial

Python's Built-in Functions: A Complete Exploration

In this tutorial, you'll learn the basics of working with Python's numerous built-in functions. You'll explore how to use these predefined functions to perform common tasks and operations, such as mathematical calculations, data type conversions, and string manipulations.

basics python

For additional information on related topics, take a look at the following resources:

By Leodanis Pozo Ramos • Updated Nov. 21, 2024 • Reviewed by Dan Bader
Python’s Built-in Functions Share Feedback