The Python import statement allows us to import a Python module. In turn, A Python module helps us organize and reuse our code. In this article, you learn about:
- How to create modules and organize code in modules
- The Python import statement that allows us to import a module or parts of a module
- Some best practices when it comes to modules
- How to create runnable modules
In the follow-up article, you’ll learn how to bundle modules in Python packages.
Table of contents
What is a module?
If you create a single Python file to perform some tasks, that’s called a script. If you create a Python file to store functions, classes, and other definitions, that’s called a module. We use modules by importing from them, using the Python
So a module is a file that contains Python code, ending with the
.py extension. In other words: any Python file is also a module. The name of a module is the same as the file name, excluding the extension. For example, if you create a file named
mymodule.py, the name of your module is
Why do you need Python modules?
Modules have a lot to offer:
- They allow us to organize code. For example, you could store all functions and data related to math in a module called ‘math.py’. This is exactly what Python does in the math module, actually!
- We can reuse code more easily. Instead of copying the same functions from one project to the next, we can now use the module instead. And if we properly package the module, we can even share it with others on the Python package index.
You can import a Python module by using Python’s
import keyword. Module imports are often placed at the top of a script, but they don’t have to be. E.g., sometimes you want to dynamically decide if you need to import a module, especially when that module takes up a lot of memory or other resources.
A simple Python module
Let’s create a simple module, called
mymodule.py. All it contains is the following function:
def my_function(): print('Hello world!')
We can import this module in another script, but you need to make sure the two files are in the same directory. To import the module, use the following command:
This imports the entire module and makes it available to the rest of the program under the name
mymodule. After importing the module with
import, we can use the function by using the following command:
To see this in action, you can run and play around with the following code crumb:
Importing specific parts of a Python module
from mymodule import my_function
my_funcion function is now available to the rest of the program under the name
my_function, as if it was defined inside the file itself. So we can use it like this:
In the same fashion, we can import multiple elements from a Python module. To do so, use the following syntax:
from mymodule import my_function, my_variable
It’s up to you when to do what. Sometimes, you need a function so often that referencing the entire module each time looks messy. Other times, it’s better to import the module name because you need a lot of different functions from that same module. Another consideration might be that it’s more clear to the readers of your code where a specific function, variable, or class is from when you reference it by using the entire module name.
Wildcard imports (are bad practice)
When a module has a lot of functions and other elements that you want to import, it can be tempting to import them all at once with a special
from module import * syntax. To import everything from a module, we can use the following syntax:
from mymodule import *
You should avoid using the
* syntax in most cases, because it can lead to unexpected results, especially when using third-party modules over which you have no control. After all, you don’t know what’s inside a third-party module, or what will be inside of it in the future. By importing everything, you ‘pollute’ your namespace with unnecessary variables, classes, and functions. You might even overwrite some existing definitions without noticing. My advice: only import specific elements to stay in control of your namespace.
Sometimes Python module names are not what you like them to be. Perhaps you need to type the name a lot, like in a Jupyter Notebook. In this case, you can use an alias to make the module name shorter. For example, if you have a module named
mymodule.py, you can import it as
import mymodule as m
Some common aliases that you will encounter, especially in fields like data science, are:
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
Valid Python module names
There are some restrictions on the names of Python modules because we must be able to import them from Python code and use/reference them with a regular variable. As a result, a valid Python module name has a lot in common with regular variable names.
A module name:
- Is a string of letters, digits
- Can contain underscores if it helps with readability
- Cannot start with a digit
- Does not contain spaces or other whitespace characters
- Cannot contain any of the following additional characters: \ / : * ? ” < > | –
In addition to these rules, there are some best practices to follow when naming modules. Notable:
- Use lowercase letters for the module name.
- Make sure names are short and descriptive.
A common mistake is to use reserved words or existing module names for your module. I’ve done so myself, e.g. by creating a module called
http while Python already has a module with this name.
Another common cause of hard to debug errors is naming your module the same as a directory.
How to create runnable Python modules
Inside a module, you can detect if it is used as a module or a script. This is useful because it allows you to both run a module on its own and import it at the same time from other code as well.
If __name__ == '__main__' check
You might have seen it before, and you might have wondered what it does. Why do Python programmers include this check in their script so often? It has everything to do with modules and using modules as scripts.
When we import a module, its name (stored in the variable
__name__) is equal to the module name. When a script is executed, its name is always set to the string
__main__. Hence, if we check for this name, we can detect if we are running as a script or if we’re being included somewhere as a module.
In the following code crumb, I created a simple module that does this check. Because we don’t import this file but run it directly, the function is executed and we see something printed to our screen. If you would import this module, however, the function would not be called:
By only executing code when running in ‘scripting mode’, we can effectively create files that can both act as a script and as a module that can be imported.
Classes vs modules
Especially when you’re familiar with other object-oriented programming languages, like Java or C#, it is completely normal to wonder how modules compare to classes. They both group functionality, after all. There are significant differences though, and there are good reasons for Python to have both modules and classes.
A module groups similar functionality into one place. A module, for example, might contain functions and constants that can be used to connect to a particular type of database. There only needs to be one instance of this module, also called a singleton.
A class models your problem domain. It provides a blueprint for one or more objects. E.g., a student class holds student data and related functions that work on that data. There can be many students, and hence there can be many student objects at the same time. For more on this, read the chapter on classes and objects.
The python.org page listing the Python standard library gives a nice overview of built-in modules.
You’ve learned how to bundle code into a module, helping you structure your project. In the process, your project will become more maintainable. Modules are just one piece of the puzzle. In the next article on Python packages, you’ll learn how modules and packages work together to structure your project even further.