The dir function and packages

The dir function

You can use the built-in dir function to list the identifiers that an object defines. For example, for a module, the identifiers include the functions, classes and variables defined in that module.

When you supply a module name to the dir() function, it returns the list of the names defined in that module. When no argument is applied to it, it returns the list of names defined in the current module.

Example:

$ python
 
>>> import sys # get list of attributes, in this case, for the sys module
 
>>> dir(sys)
['__displayhook__', '__doc__', '__excepthook__', '__name__', '__package__', '__s
tderr__', '__stdin__', '__stdout__', '_clear_type_cache', '_compact_freelists',
'_current_frames', '_getframe', 'api_version', 'argv', 'builtin_module_names', '
byteorder', 'call_tracing', 'callstats', 'copyright', 'displayhook', 'dllhandle'
, 'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix', 'executable',
'exit', 'flags', 'float_info', 'getcheckinterval', 'getdefaultencoding', 'getfil
esystemencoding', 'getprofile', 'getrecursionlimit', 'getrefcount', 'getsizeof',
 'gettrace', 'getwindowsversion', 'hexversion', 'intern', 'maxsize', 'maxunicode
', 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache', 'platfor
m', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setprofile', 'setrecursionlimit
', 'settrace', 'stderr', 'stdin', 'stdout', 'subversion', 'version', 'version_in
fo', 'warnoptions', 'winver']
 
>>> dir() # get list of attributes for current module
['__builtins__', '__doc__', '__name__', '__package__', 'sys']
 
>>> a = 5 # create a new variable 'a'
 
>>> dir()
['__builtins__', '__doc__', '__name__', '__package__', 'a', 'sys']
 
>>> del a # delete/remove a name
 
>>> dir()
['__builtins__', '__doc__', '__name__', '__package__', 'sys']
 
>>>

How It Works:

First, we see the usage of dir on the imported sys module. We can see the huge list of attributes that it contains.

Next, we use the dir function without passing parameters to it. By default, it returns the list of attributes for the current module. Notice that the list of imported modules is also part of this list.

In order to observe the dir in action, we define a new variable a and assign it a value and then check dir and we observe that there is an additional value in the list of the same name. We remove the variable/attribute of the current module using the del statement and the change is reflected again in the output of the dir function.

A note on del - this statement is used to delete a variable/name and after the statement has run, in this case del a, you can no longer access the variable a - it is as if it never existed before at all.

Note that the dir() function works on any object. For example, run dir('print') to learn about the attributes of the print function, or dir(str) for the attributes of the str class.

Packages

By now, you must have started observing the hierarchy of organizing your programs. Variables usually go inside functions. Functions and global variables usually go inside modules. What if you wanted to organize modules? That's where packages come into the picture.

Packages are just folders of modules with a special __init__.py file that indicates to Python that this folder is special because it contains Python modules.

Let's say you want to create a package called 'world' with subpackages 'asia', 'africa', etc. and these subpackages in turn contain modules like 'india', 'madagascar', etc.

This is how you would structure the folders:

   - /
       - world/
           - __init__.py
           - asia/
               - __init__.py
               - india/
                   - __init__.py
                   - foo.py
           - africa/
               - __init__.py
               - madagascar/
                   - __init__.py
                   - bar.py

Packages are just a convenience to hierarchically organize modules.

-Swaroopch