🔷 Introduction

As your Python projects grow, writing everything in a single file becomes messy and hard to maintain. Professional developers organize code into modules and packages to build scalable and maintainable applications.

In this lesson, you will learn:

✔ What modules and packages are
✔ How to import and organize code
✔ How to structure real-world Python projects
✔ Absolute vs relative imports
✔ Best practices for clean architecture

🟩 1. What is a Module?

A module is simply a Python file (.py) containing functions, classes, or variables.

🔹 Example

File: math_utils.py

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

def multiply(a, b):
    return a * b

Using the module:

import math_utils

print(math_utils.add(2, 3))

🔹 Import specific functions

from math_utils import add

print(add(5, 3))

🔹 Rename module (alias)

import math_utils as mu

print(mu.multiply(2, 4))

🟩 2. What is a Package?

A package is a folder that contains multiple modules.

my_project/
│
├── main.py
├── utils/
│   ├── __init__.py
│   ├── math_utils.py
│   └── file_utils.py

👉 __init__.py tells Python this folder is a package.

🟩 3. Absolute vs Relative Imports

🔹 Absolute Import (recommended)

from utils.math_utils import add

✔ Clear and readable
✔ Preferred in large projects

🔹 Relative Import

from .math_utils import add

✔ Used inside packages
✔ Less common for beginners

🟩 4. Organizing a Real Project

🔹 Example Structure

project/
│
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── user_service.py
│   ├── models/
│   │   └── user.py
│   └── utils/
│       └── helpers.py
│
├── tests/
├── requirements.txt
└── README.md

💡 Why structure matters

✔ Easier maintenance
✔ Better readability
✔ Scalable architecture
✔ Team collaboration

🟩 5. The __init__.py File

🔹 Purpose

• Marks a directory as a package
• Can initialize package-level code

🔹 Example

from .math_utils import add

🟩 6. The __name__ == "__main__" Pattern

🔹 Why it matters

Allows a file to be used as:

• a script
• a module

🔹 Example

def main():
    print("Running main")

if __name__ == "__main__":
    main()

🟩 7. Best Practices

✔ Use meaningful module names
✔ Avoid circular imports
✔ Keep files small and focused
✔ Group related logic
✔ Use virtual environments
✔ Add requirements.txt

🟧 8. Exercises (Hidden Solutions)

Exercise 1 — Create a module

Create a file with a function and import it.

# math_utils.py
def add(a, b):
    return a + b

# main.py
from math_utils import add
print(add(2, 3))

Exercise 2 — Create a package

utils/
  __init__.py
  file_utils.py

Exercise 3 — Absolute import

from utils.file_utils import function_name

Exercise 4 — Use name

if __name__ == "__main__":
    print("Run directly")

Exercise 5 — Organize a project

app/
  main.py
  services/
  models/

🟦 Conclusion

In this lesson, you learned how to:

✔ Structure Python code using modules and packages
✔ Use imports effectively
✔ Organize large projects
✔ Follow professional development practices

These concepts are critical for:

• Django projects
• APIs
• Large-scale applications
• Team development

🚀 Mini Project — CLI Task Manager with Real Project Structure

Project idea

Build a simple command-line Task Manager that allows the user to:

• add a task
• view all tasks
• mark a task as completed
• save tasks to a file

This project is excellent for practicing:

• modules
• packages
• imports
• project organization
• separation of concerns

📁 Project Structure

task_manager/
│
├── main.py
├── data/
│   └── tasks.txt
├── app/
│   ├── __init__.py
│   ├── task_service.py
│   ├── file_service.py
│   └── models.py
└── README.md

🧩 What each file does

• main.py → entry point of the program
• app/models.py → defines the task structure
• app/task_service.py → handles task operations
• app/file_service.py → handles file reading/writing
• data/tasks.txt → stores tasks
• app/init.py → marks app as a package

✅ Full Solution

class Task:
    def __init__(self, title, completed=False):
        self.title = title
        self.completed = completed

    def mark_completed(self):
        self.completed = True

    def to_line(self):
        return f"{self.title}|{self.completed}"

    @staticmethod
    def from_line(line):
        title, completed = line.strip().split("|")
        return Task(title, completed == "True")

    def __str__(self):
        status = "✓" if self.completed else "✗"
        return f"[{status}] {self.title}"

from app.models import Task

FILE_PATH = "data/tasks.txt"


def load_tasks():
    tasks = []
    try:
        with open(FILE_PATH, "r", encoding="utf-8") as f:
            for line in f:
                if line.strip():
                    tasks.append(Task.from_line(line))
    except FileNotFoundError:
        pass
    return tasks


def save_tasks(tasks):
    with open(FILE_PATH, "w", encoding="utf-8") as f:
        for task in tasks:
            f.write(task.to_line() + "\n")

from app.models import Task


def add_task(tasks, title):
    tasks.append(Task(title))


def show_tasks(tasks):
    if not tasks:
        print("No tasks found.")
        return

    for i, task in enumerate(tasks, start=1):
        print(f"{i}. {task}")


def complete_task(tasks, index):
    if 0 <= index < len(tasks):
        tasks[index].mark_completed()
        print("Task marked as completed.")
    else:
        print("Invalid task number.")

from app.file_service import load_tasks, save_tasks
from app.task_service import add_task, show_tasks, complete_task


def menu():
    print("\n=== Task Manager ===")
    print("1. Show tasks")
    print("2. Add task")
    print("3. Complete task")
    print("4. Save and exit")


def main():
    tasks = load_tasks()

    while True:
        menu()
        choice = input("Choose an option: ")

        if choice == "1":
            show_tasks(tasks)

        elif choice == "2":
            title = input("Enter task title: ")
            add_task(tasks, title)
            print("Task added.")

        elif choice == "3":
            show_tasks(tasks)
            try:
                num = int(input("Enter task number to complete: "))
                complete_task(tasks, num - 1)
            except ValueError:
                print("Please enter a valid number.")

        elif choice == "4":
            save_tasks(tasks)
            print("Tasks saved. Goodbye!")
            break

        else:
            print("Invalid option.")


if __name__ == "__main__":
    main()

python main.py

=== Task Manager ===
1. Show tasks
2. Add task
3. Complete task
4. Save and exit
Choose an option: 2
Enter task title: Finish Python lesson
Task added.

1. [✗] Finish Python lesson

1. [✓] Finish Python lesson

🔍 Why this project is useful

This mini project teaches you  how to organize a real Python app by separating:

• data model
• business logic
• file handling
• main program flow

That is exactly how larger applications are built.

🛠 Concepts practiced

With this project, you practice:

• creating modules
• creating packages
• importing functions from different files
• using __init__.py
• organizing a real project structure
• using if __name__ == "__main__"
• splitting responsibilities across files

📌 Possible improvements

You can extend the project with:

1. delete a task
2. edit a task
3. add due dates
4. store tasks in JSON instead of TXT
5. add task priority
6. create a GUI version later