Python Modules Tutorial: Importing, Writing, and Using Them

Importing Modules in Python

To use the functionality present in any module, you have to import it into your current program. You need to use the import keyword along with the desired module name. When the interpreter comes across an import statement, it imports the module to your current program.

You can use the functions inside a module by using a dot (.) operator along with the module name.

First, let's see how to use the standard library modules. In the example below, the math module is imported into the program so that you can use the sqrt() function.

import math  # Import the math module
num = 4
print(math.sqrt(num))  # Call the sqrt() function from the math module

For efficiency reasons, each module is only imported once per interpreter session. Therefore, if you change your modules, you must restart the interpreter.

If you want to reload a module you've already imported (e.g. after editing it), use importlib.reload().

Note that the old reload() built-in no longer exists in Python 3 — importlib.reload() is the current and official way to reload modules in Python 3.4+

import importlib
importlib.reload(module_name)

Note: Reloading sys, __main__, builtins, and other key modules is not recommended. Many extension modules are not designed to be initialized more than once and may fail in unpredictable ways when reloaded. Stick to reloading your own modules during development only.

Coming soon: Python is introducing "lazy imports." These will speed up startup times by deferring the loading of modules until they are first used. This is useful because, especially in large projects, many modules are imported at the top of a file, but aren't needed immediately.

How to Write Your Own Python Modules

Now that you have learned how to import a module in your program, it is time to write your own, and use it in another program. Writing a module is just like writing any other Python file. Let's start by writing a function to add/subtract two numbers in a file calculation.py.

def add(x,y):
    return (x+y)
def sub(x,y):
    return (x-y)

If you try to execute this script on the command line, nothing will happen because you have not instructed the program to do anything. Create another Python script in the same directory with the name module_test.py and write the following code into it.

import calculation            #Importing calculation module
print(calculation.add(1,2))   #Calling function defined in the calculation module 

If you execute module_test.py, you will see "3" as output. When the interpreter came across the import statement, it imported the calculation module in your code and then by using the dot operator, you were able to access the add() function.

Protecting runnable code with if __name__ == "main__"

There's one important habit to build when writing modules: wrapping any code you only want to run directly (not when imported) in an if __name__ == "__main__" guard.

# calculation.py
def add(x, y):
    return x + y

def sub(x, y):
    return x - y

if __name__ == "__main__":
    # This only runs when you execute calculation.py directly
    # It will NOT run when another script imports this module
    print(add(1, 2))

Other Ways to Import Modules in Python

There are more ways to import modules:

• from .. import statement

• from .. import * statement

• renaming the imported module

Using from module import name

The from..import statement allows you to import specific functions/variables from a module instead of importing everything. In the previous example, when you imported calculation into module_test.py both the add() and sub() functions were imported. But what if you only needed the add() function in your code? Here is an example to illustrate the use of from..import.

from calculation import add
print(add(1,2))

In the above example, only the add() function is imported and used. Notice the use of add()? You can now access it directly without using the module name. You can import multiple attributes as well, separating them with a comma in the import statement. Take a look at the following example:

from calculation import add,sub

Using from module import *

You can import all attributes of a module using this statement. This will make all attributes of imported module visible in your code.

Here is an example to illustrate the use of from .. import *:

from calculation import *
print(add(1,2))
print(sub(3,2))

Note that in the professional world, you should avoid using from..import and from..import*. It pollutes your namespace with every name from that module, makes it impossible to tell where a function came from when reading the code, and can silently overwrite names you've already defined. Use explicit imports instead.

Renaming Modules in Python

You can rename the module you are importing, which can be useful in cases when you want to give a more meaningful name to the module or the module name is too large to use repeatedly. You can use the as keyword to rename it. The following example explains how to use it in your program.

import calculation as cal
print(cal.add(1,2))

You saved yourself some typing time by renaming calculation as cal.

Note that you now can't use calculation.add(1,2) anymore, as calculation is no longer recognized in your program. What is happening: Once you alias a module with as, the original name is no longer available in that script.

Module Search Path in Python

You may need your modules to be used in different programs or projects and their physical location in the directory may be different. If you want to use a module residing in some other directory, you have some options provided by Python.

When you import a module named calculation, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named calculation.py in a list of directories given by the variable sys.path. sys.path contains these locations:

• The directory containing the input script (or the current directory)

• PYTHONPATH (a list of directory names with the same syntax as the shell variable PATH)

• The installation-dependent default

Assume module_test.py is in the /home/datacamp/ directory, and you moved calculation.py to /home/test/. You can modify sys.path to include /home/test/ in the list of paths, in which the Python interpreter will search for the module. For this, you need to modify module_test.py in the following way:

import sys
sys.path.append('/home/test/')

import calculation
print(calculation.add(1,2))

Byte Compiled Files in Python

Importing a module increases the execution time of programs, so Python has some tricks to speed it up. One way is to create byte-compiled files with the extension .pyc.

Internally, Python converts the source code into an intermediate form called bytecode. It then translates this into the native language of your computer and then runs it. This .pyc file is useful when you import the module the next time from a different program - it will be much faster since a portion of the processing required for importing a module is already done. Also, these byte-compiled files are platform-independent.

Note that these .pyc files are usually created in the same directory as the corresponding .py files. If Python does not have permission to write to files in that directory, then the .pyc files will not be created. These files are usually stored in the __pycache__ directory alongside your .py files, with names like calculation.cpython-312.pyc that reflect the Python version used. You can safely ignore or .gitignore this folder. Python manages it automatically.

The Python dir() Function

The dir() function is used to find out all the names defined in a module. It returns a sorted list of strings containing the names defined in a module.

import calculation
print(calculation.add(1,2))
print(dir(calculation))

['__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'add', 'sub']

In the output, you can see the names of the functions you defined in the module, add & sub. Attribute __name__ contains the name of the module. All attributes beginning with an underscore are default Python attributes associated with a module.

Conclusion

Creating a module is required for better management of code and reusability. Python provides you with some built-in modules, which can be imported by using the import keyword. Python also allows you to create your own modules and use them in your programs. It gives you byte-compiled files to overcome the cost of using modules, which makes execution faster. You can use dir() to know the attributes defined in the module being used in a program. This can be used both on pre-defined modules as well as user-defined modules.

If you would like to learn more about Python, you can take a look at our Intermediate Python for Data Science course.