#04 – Modules & Modern Python Project Structure

Welcome to Day 4! Today is all about clean architecture, dependency isolation, and modern Python tooling. You will learn how to structure your files, control execution flows, use modern tools like uv to manage virtual environments at lightning speed, and organize a codebase like a professional software engineer. 🚀

1. Modules & Packages 📦

• Module: A single .py file containing variables, functions, or classes you want to reuse.
• Package: A directory of modules.
• __init__.py: Runs automatically when a package is imported, allowing you to expose a clean top-level API and hide internal folder nesting.
• Absolute Import: Imports specifying the full path from the project root (from app.core import analyze). Preferred by PEP 8.
• Relative Import: Imports relative to the current file using dots (from .utils import clean). Single dot . is current folder; double dot .. is parent folder.

A. Core Modules & Packages

🌱 Easy Starter Example

Creating a basic module and importing it:

# file: calculator.py (Our module)
def add(a, b):
    return a + b

# file: main.py (Importing our module)
import calculator
print(calculator.add(5, 3))  # Output: 8

Enter fullscreen mode Exit fullscreen mode

🏛️ Real-World Example: Database Package API

Exposing internal package functions cleanly using __init__.py:

# Project Layout:
database/
   ├── __init__.py
   ├── auth.py       (defines login_user())
   └── query.py      (defines fetch_data())

Enter fullscreen mode Exit fullscreen mode

# database/__init__.py
# Expose functions relative to this folder so users don't need deep imports
from .auth import login_user
from .query import fetch_data

Enter fullscreen mode Exit fullscreen mode

# main.py
# Clean absolute package import for the end-user
from database import login_user, fetch_data  

login_user("admin", "password123")

Enter fullscreen mode Exit fullscreen mode

B. Built-In vs. Third-Party Modules

• Built-In: Included with Python out-of-the-box (e.g., os, sys, json).
• Third-Party: Built by the community and installed from PyPI (e.g., requests, rich).

🌱 Easy Starter Example

import math              # Built-in math operations
print(math.sqrt(25))     # Output: 5.0

# import requests        # Third-party (Will fail until installed!)

Enter fullscreen mode Exit fullscreen mode

🏛️ Real-World Example: System Health Report

Combining built-ins with third-party styling packages to log environmental diagnostics:

import os
import sys
import json
# from rich import print  # Third-party library for colorized terminal output

def generate_report():
    sys_info = {
        "os_name": os.name,
        "python_ver": sys.version.split()[0],
        "current_directory": os.getcwd()
    }
    # Convert Python dictionary to formatted JSON string using built-in library
    json_report = json.dumps(sys_info, indent=2)
    print(json_report)

generate_report()

Enter fullscreen mode Exit fullscreen mode

2. Special Variables & Entry Points 🪄

Python tracks a hidden string variable named __name__ for every file.

• If you run a file directly, __name__ evaluates to "__main__".
• If a file is imported, __name__ evaluates to its actual filename.

The Entry Point Pattern (if __name__ == "__main__":) acts as a safety guardrail. It prevents script logic from running automatically when a module is imported.

🌱 Easy Starter Example

# file: greeter.py
def hello():
    print("Hello from greeter!")

# Direct run safety guard
if __name__ == "__main__":
    print("This runs ONLY when executing greeter.py directly.")
    hello()

Enter fullscreen mode Exit fullscreen mode

🏛️ Real-World Example: Database Seeder Script

A script that imports utility functions, but includes local testing/seeding operations that should never run during production imports.

# file: db_migrator.py
def run_migrations():
    print("Applying schema updates to database...")

if __name__ == "__main__":
    # Local CLI testing execution block. Safe from running on production imports!
    print("--- Local Debug Mode: Initializing Test Seeder ---")
    run_migrations()
    print("Test migrations complete.")

Enter fullscreen mode Exit fullscreen mode

3. Modern Project Structure 🏛️

For professional applications, organizing your project elements systematically keeps your codebase scalable, deployable, and testable.

🌱 Easy Starter Example

A basic folder layout for a small personal script:

my_script_project/
├── .gitignore
├── README.md
├── main.py
└── utils.py

Enter fullscreen mode Exit fullscreen mode

🏛️ Real-World Example: Enterprise Layout

A highly structured layout for a production microservice:

my_project/
├── .git/                 # Git Version Control
├── .gitignore            # Excludes build caches and virtual environments
├── README.md             # Setup guide and API documentation
├── pyproject.toml        # Unified project metadata and dependencies (PEP 621)
├── uv.lock               # Pinned reproducible environment version lockfile
├── main.py               # Main application entry point
├── app/                  # Core application package folder
│   ├── __init__.py
│   ├── core.py
│   └── utils.py
└── tests/                # Automated test suite
    └── test_core.py

Enter fullscreen mode Exit fullscreen mode

4. Virtual Environments & Package Management 🌐

Virtual Environments (.venv) act as isolated sandboxes. If Project A needs Django v4.0 and Project B needs Django v5.0, global installations will break one of them. Environments keep their setups completely separate.

While classic Python uses pip, uv (written in Rust) acts as the modern industry gold standard—performing setup, installation, and compilation tasks 10–100x faster.

Pip vs. UV Commands Reference

Action Classic pip + venv Way Modern uv Way Initialize Workspace (Manual directory config) uv init my_project Create .venv Room python -m venv .venv uv venv Activate Env (Mac/Linux) source .venv/bin/activate source .venv/bin/activate Activate Env (Windows) .venv\Scripts\activate .venv\Scripts\activate Install Package pip install requests uv add requests Upgrade Package pip install --upgrade requests uv add requests --upgrade Uninstall Package pip uninstall requests uv remove requests Lock Environment pip freeze > requirements.txt (Auto-tracked in pyproject.toml / uv.lock) Sync Environment pip install -r requirements.txt uv sync Run Script python main.py (Requires activation) uv run main.py (Auto-manages active env)

🌱 Easy Starter Example: Isolate a package with pip

# Classic manual setup
python -m venv .venv
source .venv/bin/activate
pip install requests
python -c "import requests; print(requests.__version__)"

Enter fullscreen mode Exit fullscreen mode

🏛️ Real-World Example: Modernized uv workflow

# Initialize a modern template in one command
uv init my_app && cd my_app

# Add dependencies instantly to local metadata & venv
uv add requests

# Run your application immediately (uv auto-manages the environment)
uv run hello.py

Enter fullscreen mode Exit fullscreen mode

5. Practice Challenge: Create a Modern Modular Project 🏋️

Let’s build a structured, modular Text Processor App under Git version control using uv.

Step 1: Initialize Workspace Layout

Open your terminal and build your project architecture:

uv init text_utility_app && cd text_utility_app
git init
mkdir app tests
touch app/__init__.py app/core.py app/utils.py tests/test_core.py

Enter fullscreen mode Exit fullscreen mode

Step 2: Establish the Project Ignore Bounds

Prevent tracking compiled cache databases or workspace binaries in Git:

# Create a .gitignore file in the root directory
# .gitignore
.venv/
__pycache__/
*.pyc
.uv/

Enter fullscreen mode Exit fullscreen mode

Step 3: Implement Code Base

Create your utility parsing module:

# app/utils.py
def clean_whitespace(text: str) -> str:
    """Strips extra outer spaces and condenses internal gaps."""
    return " ".join(text.split())

Enter fullscreen mode Exit fullscreen mode

Create your analysis core, calling your sibling utility relative to its position:

# app/core.py
import json # Built-in module dependency
from .utils import clean_whitespace # Relative package import

def analyze_to_json(text: str) -> str:
    """Cleans text and packs word counts into a JSON string."""
    cleaned = clean_whitespace(text)
    metrics = {
        "original_text": text,
        "cleaned_text": cleaned,
        "word_count": len(cleaned.split()) if text.strip() else 0
    }
    return json.dumps(metrics)

Enter fullscreen mode Exit fullscreen mode

Map imports inside your package initialization gateway:

# app/__init__.py
# Expose functions directly to package consumers
from .core import analyze_to_json

Enter fullscreen mode Exit fullscreen mode

Create the application entry point using a third-party styling package:

# main.py
from app import analyze_to_json # Custom package import
from rich import print # Third-party style library

if __name__ == "__main__":
    raw_payload = "   Day  4   Modules   System  Activated   "
    json_result = analyze_to_json(raw_payload)

    print("[bold cyan]=== Processing Dashboard ===[/bold cyan]")
    print(json_result)

Enter fullscreen mode Exit fullscreen mode

Create local verification assertions:

# tests/test_core.py
from app.utils import clean_whitespace # Absolute project import

def test_string_cleaner():
    assert clean_whitespace("   too    many   spaces   ") == "too many spaces"
    print("✓ Unit test diagnostics passed.")

if __name__ == "__main__":
    test_string_cleaner()

Enter fullscreen mode Exit fullscreen mode

Step 4: Resolve, Execute, and Save

Let uv handle installation, compile configurations, and build synchronization.

# Add third-party styling to pyproject.toml and env automatically
uv add rich

# Run the execution pipeline instantly
uv run main.py

# Run unit verification tests
uv run python tests/test_core.py

# Commit progress to Git
git add .
git commit -m "Feat: Complete modular project using uv and app package"

Enter fullscreen mode Exit fullscreen mode