Python Modules and Packages

The Problem: Code Duplication Across Programs

Imagine you write a function to calculate the area of a circle. It works perfectly in your first program. Now you need that same function in a second program, and a third, and a tenth. You could copy and paste the function into every new file, but that creates a maintenance nightmare: if you find a bug in the function, you have to fix it in ten places. If you want to improve the function, you update ten copies. This is the problem modules solve.

What Is a Module?

A module is simply a .py file containing functions, variables, or classes that you want to reuse. There is nothing special about the file itself—it is just Python code organized in a way that makes it easy to import into other programs. When you create a module, you are creating a reusable library of code.

The simplest real way to create a module is to write a regular file with a .py extension containing the functions and variables to be reused. You do not need to do anything special—no decorators, no special syntax, no registration step. Just write your code in a .py file, and it becomes a module that other programs can import.

Creating Your First Module

Let us create a concrete example. Suppose you have a file called math_tools.py in your project directory. Inside it, you write two functions that you know you will use in multiple programs.

# math_tools.py

def circle_area(radius):
    """Calculate the area of a circle given its radius."""
    pi = 3.14159
    return pi * radius * radius

def rectangle_area(length, width):
    """Calculate the area of a rectangle."""
    return length * width

# You can also define variables in a module
PI_VALUE = 3.14159
CONVERSION_FACTOR = 2.54

That is it. math_tools.py is now a module. It contains two functions and two variables, all available for other programs to import and use.

Importing and Using a Module

Now imagine you have a second program in the same directory called my_program.py. You want to use the functions from math_tools.py without rewriting them. You import the module using the import statement.

# my_program.py

import math_tools

# Now you can call functions from the module
area1 = math_tools.circle_area(5)
print(f"Circle area: {area1}")

area2 = math_tools.rectangle_area(10, 4)
print(f"Rectangle area: {area2}")

# You can also access variables from the module
print(f"PI value: {math_tools.PI_VALUE}")

Circle area: 78.53975
Rectangle area: 40
PI value: 3.14159

When you write import math_tools, Python looks for a file called math_tools.py in the same directory (or in the Python path). It loads the file and makes all its functions and variables available through the module name. You access them using dot notation: module_name.function_name() or module_name.variable_name.

How Code Reuse Actually Works

When you import a module into a program, Python does not copy the code into your program. Instead, it creates a connection to the module file. The functions and variables live in one place—the module file—and multiple programs can access them. This is the key benefit: you maintain the code in one location, and all programs that import it automatically use the updated version.

This design means that if you fix a bug in circle_area() inside math_tools.py, all three programs automatically benefit from the fix the next time they run. You do not have to update the function in three separate places.

Modules vs. Packages

As your code grows, you may end up with many modules. A package is a way to organize multiple modules into a directory structure. While a module is a single .py file, a package is a directory containing multiple .py files and a special file called __init__.py.

For example, if you have multiple related modules like math_tools.py and string_tools.py, you might organize them into a package called utilities. Inside the utilities directory, you would place both modules and an __init__.py file. Then other programs can import from the package using syntax like: from utilities import math_tools or from utilities.math_tools import circle_area.

The Python Standard Library

One program can import another module to make use of its functionality. This is exactly how the Python Standard Library itself is used from ordinary programs. The Standard Library is a collection of pre-built modules that come with Python, covering everything from file I/O to mathematics to web requests. You have already used it whenever you wrote import math or import random.

When you write import math, Python finds the math module (which is part of the Standard Library) and loads it. The math module contains functions like sqrt(), sin(), and cos() that are already written and tested. You do not have to write them yourself. This is the power of modules and packages: they let you stand on the shoulders of giants, reusing code that others have written.

Common Mistakes When Creating and Using Modules

• Forgetting that the module file must be in the same directory as the program that imports it (or in the Python path)

  Python searches for modules in specific locations. If the module is not in the same directory or in a directory listed in the Python path, the import fails.

  Fix: Either place the module in the same directory as your program, or add the module's directory to the Python path using sys.path.append().

• Using the wrong import syntax and then trying to call functions without the module name

  When you use import module_name, the functions are not added to your program's namespace directly. You must use the module name as a prefix.

  Fix: Either use import math_tools and call math_tools.circle_area(5), or use from math_tools import circle_area and then call circle_area(5) directly.

• Editing a module file and expecting the changes to appear in a running program without restarting

  Python loads a module into memory when it is first imported. Changes to the file are not automatically reloaded during execution.

  Fix: Restart the program to reload the updated module.

• Creating a package directory without an __init__.py file

  Python uses __init__.py to recognize a directory as a package. Without it, Python treats the directory as a regular folder, not a package.

  Fix: Create an empty __init__.py file in the package directory.

Modules Written in Other Languages

While the simplest way to create a module is to write a .py file, modules can also be written in a different underlying language that the Python interpreter itself is written in, such as C. These compiled modules offer performance benefits for computationally intensive tasks. However, for most learning purposes and typical use cases, Python modules are sufficient and much easier to create and maintain.

Practice: Create and Import Your Own Module

Summary

1. A module is a .py file containing functions, variables, or classes designed to be reused across multiple programs.
2. The simplest way to create a module is to write a regular Python file with the code you want to reuse.
3. You import a module using the import statement, which makes its functions and variables available through dot notation (module_name.function_name).
4. Multiple programs can import the same module, ensuring that code is maintained in one place and all programs benefit from updates and bug fixes.
5. A package is a directory containing multiple modules and an __init__.py file, used to organize related modules into a namespace.
6. The Python Standard Library is a collection of pre-built modules that come with Python and are imported the same way as your own modules.