Python Modules: Organizing Code Effectively

A Python module is a .py file that groups related functions, classes, constants, and other definitions. Splitting a growing program into modules makes code easier to navigate, test, reuse, and maintain.

Create a Module

Create my_module.py:

def greet(name):
    return f"Hello, {name}!"


def add(a, b):
    return a + b

Then import it from another file in the same importable project location:

import my_module

print(my_module.greet("Alice"))
print(my_module.add(2, 3))

Using the module name keeps the origin of each function explicit.

Import Specific Names

from my_module import greet, add

print(greet("Charlie"))
print(add(10, 20))

This can be convenient for frequently used names, but avoid importing many unrelated symbols into the same namespace.

Use Aliases

import my_module as helpers

print(helpers.greet("Alice"))

Aliases are especially common for established library conventions such as:

import pandas as pd
import numpy as np

Avoid Wildcard Imports

Although Python supports:

from my_module import *

it makes it harder to tell where names came from and can cause collisions. Explicit imports are usually clearer.

Code Runs When a Module Is Imported

Top-level module code executes the first time the module is imported in a process. Keep top-level work lightweight and predictable.

To make a file usable both as an importable module and as a script, use:

def main():
    print("Running as a script")


if __name__ == "__main__":
    main()

The guarded block runs when the file is executed directly, but not when another module imports it.

Modules vs Packages

A module is normally one Python file. A package organizes multiple modules under a package namespace:

my_package/
├── __init__.py
├── users.py
└── reports.py

You can then import:

from my_package.users import create_user

Keep Responsibilities Focused

A useful module should represent a coherent responsibility. Instead of putting unrelated helpers into one large utils.py, consider domain-oriented modules such as:

project/
├── auth.py
├── database.py
├── email.py
└── reports.py

As a project grows further, these can become packages with smaller submodules.

Understand Import Paths

Python resolves imports using locations in sys.path, which normally includes the executing project’s environment and installed packages. Avoid modifying sys.path in application code unless you have a specific advanced use case. Proper package structure and installation are more reliable.

Conclusion

Modules are the basic building blocks for organizing Python programs. Keep each module focused, prefer explicit imports, avoid expensive import-time side effects, and move to packages when a group of related modules needs its own namespace.