Creating and using your own modules in Python

Coding with Python

🕑 This lesson will take about 30 minutes

Modules are Python files that contain functions, classes, and variables. Modules allow you to organise your code into reusable components that you can easily import and use in other Python scripts.

The basic steps of creating and using a module are:

  1. Write the Python code that will belong to the module

    • Include functions, classes, or variables that serve a specific purpose in your module

  2. Save the module code as a Python file (ending in .py)

    • For example, my_module.py

  3. Import the module into another Python script

    • For example, write import my_module at the top of the Python code

  4. Call any functions or use variables and classes from your module in your other Python script(s) when you need them.

Here is an example.

Step 1 - Create the module

Create a new Python file and give it a name that ends in .py - in this example, the file will be called my_module.py , but you should normally give the module a unique name that describes the purpose of the module.

In the example code below, the module called my_module.py has to functions - a function (greet) that takes a person’s name as an argument and then greets the person, and another function (farewell) that takes a person’s name as an argument and then farewells them. Both functions return a string that can be used how you like when calling the functions from the module.

Step 2 - Import and use the module

Now create another Python file. In this file, you will need to import the module you just made using the import statement. Once the module has been imported, you can then use the functions (or variables and classes) that are defined in the module. Check out the example below.

You can also import specific components (eg. functions) from the module when using the import statement.

When you specify which components to import from a module using the from keyword, you don’t need to reference the module name later in the code when calling functions. For example, you only need to write greet("Joe") instead of my_module.greet("Joe") .

Note that when using the from keyword, any components you don’t identify will not be imported. Each component you wish to import can be listed, separated by a comma, like in the example below.

The statement from my_module import * can also be used, which means “import all components from my_module”.

How are modules located?

When you import a module into your code, Python will attempt to find the module in the following order:

  • the current directory/folder that your code is stored in

  • if the module cannot be found in the current directory, then Python will search each directory in the shell variable PYTHONPATH

  • if the module still cannot be found, Python will check the default path. On Unix systems, the default path is usually /usr/local/lib/python/.

The module search path is kept in the system module sys as the sys.path variable. This variable contains the current directory, PYTHONPATH, and the installation-dependent default.

The PYTHONPATH variable

The PYTHONPATH consists of a list of dictionaries.

  • On Windows, a typical PYTHONPATH would look like this: set PYTHONPATH=c:\python20\lib

  • On Unix, a typical PYTHONPATH would look like this: set PYTHONPATH=/usr/local/lib/python

Packages

Let's say you want to design a collection of different modules that are all in some way related. If you create many modules, the structure of your program can become very messy. We can organise our modules using packages.

Packages are basically a collection of related modules that can be imported into our programs. Those modules can contain a range of different functions, variables, etc. Let's check out the example below.

Say we want to create a collection of modules that can be used for converting different units eg. temperature, distance, weight, volume, etc. We could make each of these different conversion types a different module in a package called conversions.

Each module from the conversions package could then contain functions for different conversions. For example:

  • the temperature module could contain functions toCelsius() and toFahrenheit() to convert temperatures to celsius or Fahrenheit

  • the distance module could contain functions toMiles() or toKilometres().

To create the conversions package, we can create a new directory/folder called conversions. Inside this directory, we create an empty file called __init__.py (note that there are two underscores on each side of init) - this file will be empty. Then, we can create our modules (Python files ending in .py) within the conversions folder eg. temperature.py, distance.py, weight.py and so on. Inside the temperature.py file, for example, we could then create functions toCelsius() and toFahrenheit(). Our main code that uses modules and functions from the conversions package will be in the main directory. The structure will be as follows:

  • conversions (directory)

    • __init__.py (Python file)

    • temperature.py (Python file)

    • … other modules (Python files)

  • program.py (main code in main directory)

The image is a screenshot reflecting the same folder/file structure as listed above.

Here is some example code for the temperature.py module:

And here is some example code for the main program that imports the temperature module from the conversions package:

The dir() function

Another handy Python function is the dir() function which returns a sorted list of strings containing the names of all variables and functions that belong to a module. For example:

Did you know?

You can also create and organise sub-directories with more sub-modules within the conversions package directory, as long as each sub-directory contains an __init__.py file.

Next lesson: Exception handling