Locked learning resources

Join us and get access to thousands of tutorials and a community of expert Pythonistas.

Unlock This Lesson

Locked learning resources

This lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.

Unlock This Lesson

The dir() Function

In this lesson, you’ll learn about the built-in function dir(). It returns a list of defined names in a namespace. Without arguments, it produces an alphabetically sorted list of names in the current local symbol table:

Python
>>> dir()
['__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'help']
>>> spam = [1, 2, 3, 4, 5]
>>> spam
[1, 2, 3, 4, 5]
>>> dir()
['__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'help', 'spam']
>>> class Extraclassy():
...     pass
...
>>> x = Extraclassy()
>>> dir()
['Extraclassy', '__builtins__', '__doc__', '__loader__', '__name__',
'__package__', '__spec__', 'help', 'spam', 'x']

Note how the first call to dir() above gives several names that are automatically defined and already in the namespace when the interpreter starts. As new names are defined (spam, Extraclassy, x), they appear on subsequent invocations of dir().

This can be useful for identifying what exactly has been added to the namespace by an import statement:

Python
>>> dir()
['__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'help']
>>> import mod
>>> dir()
['__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'help', 'mod']
>>> mod.s
'Computers are useless. They can only give you answers.'
>>> mod.printy([1, 2, 3])
arg = [1, 2, 3]
>>> from mod import a, Classy
>>> dir()
['Classy', '__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'a', 'help', 'mod']
>>> a
[100, 200, 300]
>>> y = Classy()
>>> y
<mod.Classy object at 0x1034a5978>
>>> from mod import s as string
>>> dir()
['Classy', '__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'a', 'help', 'mod', 'string', 'y']
>>> s
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    s
NameError: name 's' is not defined
>>> string
'Computers are useless. They can only give you answers.'

When given an argument that is the name of a module, dir() gives the names defined in the module:

Python
>>> import mod
>>> dir()
['__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'help', 'mod']
>>> dir(mod)
['Classy', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__',
'__name__', '__package__', '__spec__', 'a', 'printy', 's']
>>> dir()
['__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'help', 'mod']
>>> from mod import *
>>> dir()
['Classy', '__builtins__', '__doc__', '__loader__', '__name__', '__package__',
'__spec__', 'a', 'help', 'mod', 'printy', 's']

00:01 This video is about the dir() function.

00:04 After learning the various ways that you could import a module or the contents of your module and how that affects calling those objects, you might be interested in learning how to view the defined names that are inside of a namespace.

00:15 And that’s where the dir(), or directory, function comes in. It’s a built-in function and it returns a list of defined names in a namespace.

00:24 If you don’t give it any arguments, it produces an alphabetically sorted list of all the names that are in the current local symbol table. Let’s take a look at that. Throughout this example, I’m going to be exiting the REPL multiple times and entering back in, and the reason for that is it’s going to clear out the local symbol table.

00:43 We’re starting with a brand new session here, and if you were to type dir(), one kind of nice thing—change the zoom level a little bit here—is you can see here in bpython, it’s showing that dir(), if called without an argument, returns the names in the current scope. I’m going to close this off here.

01:00 When running dir() just by itself, you’ll see these objects.

01:07 If you were to create a new object, make a list named spam,

01:15 and if you were to run dir() now, you’ll see 'spam' as an object that’s also now in the local symbol table. If you were to create a class named Extraclassy—it’s a very simple class that just passes—and you were to create an object, say x that is of the class Extraclassy.

01:36 Now, if you type dir(), you can see here 'Extraclassy', and then you can see the other objects, 'spam' and 'x'.

01:45 So these are all objects that are now in the local symbol table, their names are. I’m going to type exit() to end my REPL session and restart it.

01:54 So here, starting from scratch, dir().

01:59 Those are the current objects, like before. This time, now if you import the module mod and type in dir(), you can see that only 'mod' is there.

02:08 The individual objects that are part of the module mod are not part of the local symbol table. They would have to be accessed by typing mod.a or mod.s, using dot notation syntax. Or mod.printy().

02:27 But if you were to import individual items, which you learned how to do last time, import a, Classy, now if you type dir(), Classy—that class—is there, and athat object—is there and, again, accessible without having to type mod.a, which is actually still there also.

02:48 So the two different contexts for a is available. But also Classy is there. You can make an object x—oh, let’s make it y. You can make an object y of the Classy class. There’s y, and there it is!

03:01 It’s available. And then the other way that could be imported is to import but with a different name. So you could import s and give it the name string.

03:11 So now dir() would bring up—'string' is now in that local table also. s is not, it’s not defined, but string is. So up to now, you’ve been using the built-in function dir() without any argument. What if you do give it an argument? Well, one of the ways that you can use it is giving it the name of the module as an argument. And then in that case, the dir() function lists the defined names inside that module.

03:44 If you were to import mod by itself, you can see it here, but you can’t see the names of the objects that were imported when you imported mod.

03:53 Those are in its own symbol table. To see those, you type dir() and as an argument put in mod. It has the Classy class inside of it, the string a, function printy(), and the string s, along with its own __name__.

04:08 I’ll show you a little bit more about __name__ in your next video. And the last we discussed, as far as importing, was using a wildcard. from mod import *, what does that put in the directory?

04:23 Well, that puts all the objects in, so there’s 'Classy', 'mod'. The module is still already in there from when you imported it before.

04:29 But 'printy' and 's' and 'a' are all now in the local symbol table.

04:36 In the next video, you’ll learn about executing a module as a script.

Avatar image for keyurratanghayra

keyurratanghayra on April 14, 2020

Could not be easier than this. Awsome job here, Chris!

Become a Member to join the conversation.