Creating and Importing Modules in Python

Introduction

In Python, a module is a self-contained file with Python statements and definitions. For example, file.py, can be considered a module named file. This differs from a package in that a package is a collection of modules in directories that give structure and hierarchy to the modules.

Modules help us break down large programs into small files that are more manageable. With modules, code reusability becomes a reality. Suppose we have a function that is frequently used in different programs. We can define this function in a module then import it into the various programs without having to copy its code each time.

In this article, we will see how to create Python modules and how to use them in Python code.

Writing Modules

A module is simply a Python file with the .py extension. The name of the file becomes the module name. Inside the file, we can have definitions and implementations of classes, variables, or functions. These can then be used in other Python programs.

Let us begin by creating a function that simply prints "Hello World". To do this, create a new Python file and save it as hello.py. Add the following code to the file:

def my_function():
    print("Hello World")

If you run the above code, it will return nothing. This is because we have not told the program to do anything. It is true that we have created a function named my_function() within the code, but we have not called or invoked the function. When invoked, this function should print the text "Hello World".

Now, move to the same directory where you have saved the above file and create a new file named main.py. Add the following code to the file:

import hello

hello.my_function()

Output

Hello World

The function was invoked successfully. We began by importing the module. The name of the file was hello.py, hence the name of the imported module is hello.

Also, note the syntax that we have used to invoke the function. This is called the "dot notation", which allows us to call the function by first specifying the module name, and then the name of the function.

However, that is just one way of importing the module and invoking the function. We could have done it as follows:

from hello import my_function

my_function()

Output

Hello World

In the above example, the first line commands the Python interpreter to import a function named my_function from a module named hello. In such a case, you don't have to use the dot notation to access the function, you can just call it directly.

However, in the case where our hello module has multiple functions, the statement from hello import my_function will not import all hello's functions into our program, only my_function. If you attempt to access any other function, an error will be generated. You have to import the whole module or import each individual function in order to use them.

We can define a variable within a module, which can then be used by other modules. To demonstrate this, open the file hello.py and add the following code to it:

def my_function():
    print("Hello World")

# The variable that'll be used in other modules
name = "Nicholas"

Now, open the main.py file and modify it as follows:

import hello

hello.my_function()

print(hello.name)

Output

Hello World
Nicholas

We have successfully invoked both the function and the variable defined in the module since we imported the whole module instead of just the my_function() function.

We stated earlier that we can define a class within a module. Let's see how to do this in the next example. Open the hello.py file and modify it as follows:

def my_function():
    print("Hello World")

# Defining our variable
name = "Nicholas"

# Defining a class
class Student:
    def __init__(self, name, course):
        self.course = course
        self.name = name

    def get_student_details(self):
        print("Your name is " + self.name + ".")
        print("You are studying " + self.course)

Here we have defined a class named Student. Two variables have been defined in this class, name and course. The method get_student_details() has also been defined within this, which prints the student details to the console.

Now, open the file main.py and modify it as follows:

import hello

hello.my_function()

print(hello.name)

nicholas = hello.Student("Nicholas", "Computer Science")
nicholas.get_student_details()

Output

Hello World
Nicholas
Your name is Nicholas.
You are studying Computer Science

In the script above, we again used the dot notation to create an object of the student class from the hello module. We then used the get_student_details() function to get the student details.

Although modules mostly consist of class definitions (in most cases), it is possible for them to actually run their own code as well when imported. To demonstrate this, let us modify the hello.py file, where we have a definition of the function my_function(), along with the call to the function:

def my_function():
    print("Hello World")
    
my_function()

Now, open the file main.py and delete all the lines except the following:

import hello

Output

Hello World

The above output shows that we defined and called the function within the module. When the module is imported, it directly returns the result from the function without having to invoke the function. This behavior isn't always desired, but it's helpful for certain use-cases, like preloading data from cache when the module is imported.

Importing all Module Objects

To import all objects (functions, variables, classes, etc.) from a module, we can use the import * statement. For example, to import all objects contained in the hello module, we can use the following statement:

from hello import *

After adding the above statement to a program, we will be able to use any function, variable, or class contained in the hello module without having to prefix it with hello.

Accessing a Module from Another Path

In Python, modules are used in more than one project. Hence, it makes no sense if you keep your modules in the directory of one of the projects, since other projects wouldn't be able to use it as easily.

You have a couple of options whenever you need to access a module that is not stored in the same directory as your program. Let us discuss these in the next few sections:

Appending Paths

To import a module from another path, you first need to import the sys module as well as any other Python modules that you would like to use in your program.

The sys module is provided by the Python Standard Library and it provides functions and parameters that are system-specific. The path.append() function from the sys module can be used to add the path of the module to the current project.

To demonstrate this, cut the hello.py file from the directory where you have the file main.py. Paste it in another directory. In my case, I have pasted it in the directory "F:\Python."

Now, open the file main.py, import the sys module and specify the path in which the Python interpreter will look for files. This is demonstrated below:

import sys
sys.path.append('F:/Python/')

import hello

Output

Hello World

In the above script, the line sys.path.append('F:/Python/') tells the Python interpreter to include this path in the list of paths that will be searched while importing the modules.

Adding a Module to Python Path

The above method works only if you import the sys module. If you don't import the sys module and specify the path to the module, an error will be generated. To make the module available to the entire system, you can add it to the path where Python normally checks for modules and packages. This way, you will not have to import the sys module and specify the path to the module as we have done in the previous section.

Before doing anything else, you should first identify the path that Python searches for modules and packages. Just open the command line of your operating system and run the python command. This will take you to the Python terminal.

Import the sys module as follows:

import sys

You can then run the following command to print out the path:

print(sys.path)

The output will contain at least one system path. If you do it from a programming environment, you will get several paths. In my case, I got the following:

$ python
Python 2.7.10 (default, Oct 23 2015, 19:19:21) 
[GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> print(sys.path)
['', '/Library/Python/2.7/site-packages/six-1.10.0-py2.7.egg', '/Library/Python/2.7/site-packages/cffi-1.2.1-py2.7-macosx-10.9-intel.egg', '/Library/Python/2.7/site-packages/pycparser-2.14-py2.7.egg', '/Library/Python/2.7/site-packages/virtualenv-13.1.2-py2.7.egg', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python27.zip', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/plat-darwin', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/plat-mac', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/plat-mac/lib-scriptpackages', '/System/Library/Frameworks/Python.framework/Versions/2.7/Extras/lib/python', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-tk', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-old', '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload', '/Library/Python/2.7/site-packages']
>>> 

Your goal should be to find the one in the environment that you are currently using. You should look for something like the following:

/Library/Python/2.7/site-packages

Move your hello.py file to the path. After that, you will be able to import the hello module from any directory in the usual way, as shown below:

import hello

Output

Hello World

Conclusion

This marks the end of this article. A module is simply a Python file with a set of variables and function definitions. A module facilitates code reusability since you can define a function in a module and invoke it from different programs instead of having to define the function in every program. Although a module is mostly used for function and class definitions, it may also export variables and class instances.