Previous | Tutorial index | Next

Tutorial 1: Understanding Modules – The Building Blocks of Python Code

Learning Objectives

Describe modules.

1. Introduction: Why Modules Matter

When you start writing Python programs, you usually put all your code in a single .py file. This works fine for small scripts. However, as your projects grow, a single file becomes messy, hard to navigate, and difficult to reuse.

Imagine writing a calculator app. You wouldn't want to rewrite the addition and subtraction logic every time you start a new project. Modules solve this problem. They allow you to save reusable code in separate files and bring that code into new projects whenever you need it.

2. What Exactly is a Module?

In Python, a module is simply a file containing Python code. The file must have the .py extension.

Inside this file, you can define:

• Functions (to perform specific actions)
• Classes (to create objects)
• Variables (to store data)
• Executable statements (code that runs immediately when the module is loaded)

Technical Definition: A module is an object of type module that serves as an organizational unit for code. The filename (excluding the .py) becomes the module's name.

Key Point

Every single Python file you create is a potential module that other Python files can use.

3. The Three Core Roles of Modules

Modules are not just about saving code; they serve three major purposes in professional software development:

4. Module Naming Rules and Conventions

The name of your module file becomes its identity when you import it.

Rules (Must follow):

• The name must be a valid Python identifier.
• It must start with a letter (A-Z or a-z) or an underscore (_).
• The rest of the name can contain letters, underscores, or digits (0-9).
• It cannot be a Python reserved keyword (like if, for, while, def, class, import, etc.).

Conventions (Good practice):

• Use snake_case for module names (e.g., data_processor.py, file_handler.py).
• Keep names short, all lowercase, and descriptive.
• Avoid special characters or spaces (e.g., my-module.py is invalid because of the hyphen; Python interprets it as a subtraction).

5. What Can a Module Contain?

A module can contain any valid Python constructs. Let's look at a concrete example.

Create a file named sample.py:

# 1. Variables (data)
PI = 3.14159
AUTHOR = "Jane Doe"

# 2. Functions (behavior)
def greet(name):
    return f"Hello, {name}!"

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

# 3. Classes (blueprints for objects)
class Student:
    def __init__(self, name):
        self.name = name

    def introduce(self):
        return f"I am {self.name}"

# 4. Executable statements (code that runs on import)
print(f"Module '{__name__}' has been loaded!")

Important Note about Executable Statements: When you import a module for the first time in a program, Python runs all the top-level executable statements (like that print function) immediately. If you import the same module again later in the same program, Python does not re-run the code; it uses a cached version to save time.

6. Types of Modules in Python

As a programmer, you will interact with three different categories of modules:

1. Built-in Modules:

   • These are written in C and compiled directly into the Python interpreter.
   • They are always available, but you still need to import them to use their functions.
   • Examples: sys (system functions), math (basic math), time (time functions).
   • Note: Technically, the term "built-in" refers to the C modules, but many courses loosely group the standard library here.

2. Standard Library Modules:

   • Python comes with a vast collection of pre-written modules known as the "Standard Library" (the "batteries included" philosophy).
   • You don't need to install these; they come with your Python installation. You just import and use them.
   • Examples: os (operating system interface), json (JSON data handling), re (regular expressions), csv (spreadsheet files).

3. Third-Party Modules:

   • These are created by the global Python community and are not included in the default Python installation.
   • You must install them using a package manager like pip (e.g., pip install requests) before you can import them.
   • Examples: numpy (numerical computing), pandas (data analysis), django (web framework).

4. Local/User-defined Modules:

   • These are the .py files you create yourself for your own projects.

7. How Does Python Find Your Module? (The Search Path)

When you type import something, Python searches for something.py in specific locations, in this specific order:

1. The current directory (where your main script is running).
2. Directories listed in the PYTHONPATH environment variable (if set).
3. The installation-dependent default paths (e.g., C:\Python312\Lib on Windows, or /usr/lib/python3.12/ on Linux).

You can view this search path by importing the sys module and printing sys.path:

import sys
print(sys.path)

If your module is not in one of these directories, Python will raise a ModuleNotFoundError.

8. Quiz: Check Your Understanding (Part 1)

Test your foundational knowledge before proceeding to the practical exercises.

Q1: What file extension must a Python module have?

A) .py B) .python C) .mod D) .txt

Q2: Which of the following is a valid name for a Python module file?

A) 2nd_calc.py B) my-calc.py C) my_calc.py D) class.py

Q3: True or False: If you define a function multiply() in a module named tools.py, and a different module also defines multiply(), you cannot use both in the same program.

Q4: Which keyword does Python use to bring a module into your current file?

A) include B) using C) import D) require

Q5: What is the key difference between a Standard Library module and a Third-Party module?

9. Hands-on Exercises (Practical Tasks)

Time to get your hands dirty! These exercises are designed to be done in a lab session or during self-study.

Exercise 1: Your First Module

Goal: Create a simple module, import it in the Python interactive shell, and inspect its contents.

Instructions:

1. Open your code editor (like VS Code, PyCharm, or even Notepad).

2. Create a new file and name it greetings.py.

3. Inside greetings.py, type the following exactly:

   # greetings.py
   AUTHOR = "Your Full Name"
   
   def say_hello():
       print("Hello, world!")
   
   def say_goodbye():
       print("Goodbye, world!")
   

4. Save the file in a folder (e.g., C:\my_modules or ~/Desktop/modules_practice).

5. Open your terminal/command prompt and navigate to that exact folder using the cd command.

6. Type python to open the interactive interpreter.

7. Type import greetings and press Enter. Notice that nothing "happens" (no prints) – that's fine!

8. Type greetings.say_hello() and observe the output.

9. Type print(greetings.AUTHOR) and observe the output.

10. Try to call say_goodbye() directly (without greetings.). What error do you get? Why?

Exercise 2: Exploring Built-in Modules

Goal: Practice importing built-in modules and using the dir() function to explore what they offer.

Instructions:

1. In the Python interactive shell, type import math.
2. Type dir(math). This lists all the names (functions, constants, etc.) available inside the math module. Scroll through the list.
3. Type help(math.sqrt) to read the documentation for the square root function.
4. Use the math module to calculate the square root of 49.
5. Import the random module. Use random.randint(1, 10) to generate a random number between 1 and 10.

Exercise 3: Understanding Module Caching

Goal: Prove that a module's executable code runs only once.

Instructions:

1. Create a file called counter.py and write this inside:

   # counter.py
   print("Counter module is initializing...")
   LOAD_COUNT = 1
   

2. Save the file.

3. Open the Python interpreter in the same folder.

4. Type import counter – you will see the print message.

5. Type import counter a second time. Notice the print message does not appear again!

6. Type counter.LOAD_COUNT to see that the variable is still there. Python cached the module after the first import.

10. Homework Questions (Take-Home Assignment)

These are longer, more challenging questions to solidify your understanding of modules conceptually and practically.

Homework Question 1: Building a Profile Module

Task: Create a module named profile.py. Inside this module:

• Store three variables: NAME = "Alex", AGE = 30, and CITY = "New York".
• Define a function display() that prints all this information in a neatly formatted string.
• Define a function have_birthday() that increments the AGE variable by 1 and prints a "Happy Birthday!" message.

Now, create a second Python script (e.g., main.py) in the same directory. In main.py:

• Import the profile module.
• Call the display() function.
• Call the have_birthday() function.
• Call display() again to show the updated age.

Submission: Provide the code for profile.py and main.py.

# profile.py
NAME = "Alex"
AGE = 30
CITY = "New York"

def display():
    print(f"Name: {NAME}, Age: {AGE}, City: {CITY}")

def have_birthday():
    global AGE
    AGE += 1
    print("Happy Birthday!")

# main.py
import profile

profile.display()           # Name: Alex, Age: 30, City: New York
profile.have_birthday()     # Happy Birthday!
profile.display()           # Name: Alex, Age: 31, City: New York

Homework Question 2: Researching sys.modules

Task: When you import a module, Python stores it in a global dictionary called sys.modules.

• Write a Python script that imports math and random.
• Then, print the keys of sys.modules.
• In a short paragraph (3-5 sentences), explain what sys.modules does and why it is important for performance (hint: think about the "caching" concept from Exercise 3).

Submission: Provide your Python code and your written explanation.

import sys
import math
import random

print("Modules currently loaded:")
for module_name in sys.modules.keys():
    print(module_name)

Homework Question 3: The Execution Order Behavior

Task: Create a module named order_test.py with the following content:

print("Step 1: Top-level print")

def my_func():
    print("Step 3: Inside the function")

print("Step 2: Another top-level print")

if __name__ == "__main__":
    print("Step 4: Inside the main guard")

Now, open a Python interpreter, import order_test twice, and write down the exact console output you see.

• Why does "Step 4" NOT appear when you import the module?
• Modify the script so you can run it directly (e.g., python order_test.py) and see all 4 steps.

Submission: Write down the console outputs for both scenarios and explain your reasoning.

>>> import order_test
Step 1: Top-level print
Step 2: Another top-level print
>>> import order_test

python order_test.py

Step 1: Top-level print
Step 2: Another top-level print
Step 4: Inside the main guard

Homework Question 4: Planning a Project Structure

Task: Imagine you are building a simple Banking System. The system needs to handle:

• Customer account creation and management.
• Transaction processing (deposits, withdrawals, transfers).
• Data validation (checking if account numbers are valid).

Assignment: Without writing any code, design a modular structure for this project.

• Propose 3 distinct module names (e.g., accounts.py, transactions.py, etc.).
• For each module, list at least 2 functions or variables you would put inside it.
• Briefly explain why you chose to separate the functionality this way (how does it help with code organization?).

Submission: Submit your design as a bulleted list or a short table.

11. Summary of Tutorial 1

• A module is a single .py file containing Python definitions and statements.
• Modules enable reusability, organization, and namespace management.
• Module names must be valid Python identifiers (snake_case is recommended).
• Modules can contain variables, functions, classes, and runnable code.
• Python modules fall into Built-in, Standard Library, Third-party, and User-defined categories.
• Python uses a specific search path (sys.path) to locate modules.
• Code inside a module is executed only once on the first import due to the caching system.

This concludes the Tutorial 1. Once you fully understand these concepts, you are ready to move on to Tutorial 2, where we will dive into packages and their file system structures.

Previous | Tutorial index | Next