Capstone Project: CLI Contact Book with File Persistence0%

Capstone Project: CLI Contact Book with File Persistence

Beginner16 min read•Updated: 2026-09-30

Capstone Project: CLI Contact Book with File Persistence

Welcome to your first end-to-end Python capstone project! Up to this point, you have mastered variables, strings, data structures (lists, tuples, sets, dictionaries), conditionals, loops, functions, and file handling.

In this project, you will integrate all these concepts into a production-grade Command-Line Contact Book Application featuring full CRUD (Create, Read, Update, Delete) operations, Indian mobile number validation, and deterministic disk persistence using the context manager.

Real-World Analogy: The Classic Indian Household Telephone Diary

In Indian homes before smartphones, every family kept a spiral-bound telephone diary beside the landline phone:

Visual Architecture Blueprint

+-------------------------------------------------------------------------+
|                  INDIAN HOUSEHOLD TELEPHONE DIARY ARCHITECTURE          |
+-------------------------------------------------------------------------+
|                                                                         |
|   [ CLI Menu Interface ]                                                |
|          │                                                              |
|          ▼                                                              |
|   [ Input Validation Layer ] ──> Validates 10-digit Indian Mobile & Email|
|          │                                                              |
|          ▼                                                              |
|   [ In-Memory Hash Map (Dict) ] ──> Fast O(1) Search, Add, Update, Delete|
|          │                                                              |
|   Save   │  ▲ Load at Startup                                           |
|          ▼  │                                                           |
|   [ Storage Engine: contacts.txt via 'with open()' Context Manager ]    |
|                                                                         |
+-------------------------------------------------------------------------+

1
Bootup: When you open the diary, all prior numbers are already inked in (contacts.txt read into RAM).
2
Adding a contact: You verify the phone number is valid before writing it down (input validation).
3
Searching: You flip directly to the matching letter or name (instant dictionary lookup).
4
Shutdown: Every time you write an entry, it remains safely preserved on paper even if the power goes out (disk persistence).

Project Specification & Architecture

Our Contact Book requires the following specifications:

Data Model: An in-memory dictionary where normalized contact names serve as keys:

contacts = {
    "rahul sharma": {
        "name": "Rahul Sharma",
        "phone": "9876543210",
        "email": "rahul.sharma@example.com",
        "category": "Work"
    }
}

File Persistence: Contacts are serialized to a pipe-delimited text file (contacts_db.txt) using the format:

Name|Phone|Email|Category\n

Validation Rules:
Phone number must consist of exactly 10 numeric digits.
Email must contain @ and a period . after @.
Duplicate contact names trigger an overwrite confirmation.
Menu System: An infinite while True loop with interactive options 1 to 6.

Step-by-Step Implementation

Step 1: Input Validation Helper Functions

1def validate_phone(phone: str) -> bool:
  """Validates that a phone number contains exactly 10 digits."""
  cleaned = phone.strip()
  return len(cleaned) == 10 and cleaned.isdigit()
5 
6def validate_email(email: str) -> bool:
  """Basic validation for email format."""
  cleaned = email.strip()
  if "@" in cleaned and "." in cleaned:
      at_index = cleaned.find("@")
      dot_index = cleaned.rfind(".")
      return at_index > 0 and dot_index > at_index + 1 and dot_index < len(cleaned) - 1
  return False

Step 2: Storage Engine with Context Manager

1import os
2 
3STORAGE_FILE = "contacts_db.txt"
4 
5def load_contacts() -> dict:
  """Loads saved contacts from disk into an in-memory dictionary."""
  contacts = {}
  if not os.path.exists(STORAGE_FILE):
      return contacts
10 
  with open(STORAGE_FILE, "r", encoding="utf-8") as f:
      for line in f:
          line = line.strip()
          if not line:
              continue
          parts = line.split("|")
          if len(parts) == 4:
              name, phone, email, category = parts
              contacts[name.lower()] = {
                  "name": name,
                  "phone": phone,
                  "email": email,
                  "category": category
              }
  return contacts
26 
27def save_contacts(contacts: dict) -> None:
  """Persists the dictionary state to disk safely using with open()."""
  with open(STORAGE_FILE, "w", encoding="utf-8") as f:
      for contact in contacts.values():
          f.write(f"{contact['name']}|{contact['phone']}|{contact['email']}|{contact['category']}\n")

Step 3: Complete Production-Grade Contact Book Script

Here is the complete, modular, runnable code for the entire Contact Book system:

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

def validate_phone

phone: str

Step 2

bool:

Expected Output

1=== Populating Initial Contacts ===
2[SUCCESS] Contact 'Amitabh Sharma' saved successfully.
3[SUCCESS] Contact 'Pooja Hegde' saved successfully.
4[SUCCESS] Contact 'Suresh Kumar' saved successfully.
5 
6=== Displaying All Stored Contacts ===
7===========================================================================
8NAME                 | PHONE        | EMAIL                     | CATEGORY  
9===========================================================================
10Amitabh Sharma       | 9876543210   | amitabh@example.com       | Work      
11Pooja Hegde          | 9123456780   | pooja.h@example.com       | Friends   
12Suresh Kumar         | 9988776655   | suresh.k@example.com      | Family    
13===========================================================================
14 
15=== Searching for 'sharma' ===
16Found: Amitabh Sharma (9876543210) - amitabh@example.com
17 
18=== Deleting 'Pooja Hegde' ===
19[SUCCESS] Contact 'Pooja Hegde' deleted successfully.
20 
21=== Loading Fresh from Disk to Prove Persistence ===
22===========================================================================
23NAME                 | PHONE        | EMAIL                     | CATEGORY  
24===========================================================================
25Amitabh Sharma       | 9876543210   | amitabh@example.com       | Work      
26Suresh Kumar         | 9988776655   | suresh.k@example.com      | Family    
27===========================================================================

Best Practices & Comparison: Do's and Don'ts

Practice	Bad Implementation	Gold-Standard Implementation
Lookup Keys	Using case-sensitive keys (`"Rahul"` vs `"rahul"`)	Normalize keys with `.strip().lower()`
Input Validation	Trusting user input blindly without checks	Validate 10-digit format and email structure before saving
Persistence	Keeping contacts purely in RAM (lost on crash)	Persist every mutation to disk using `with open()`
Data Format	Unstructured arbitrary string writes	Consistent structured delimiter (`\	` or CSV/JSON)
Search	Exact match only	Substring search across both name and phone fields
Deletion	Crashing with `KeyError` if name is missing	Verify key existence with `if key in contacts:`

Quick Revision Summary Cheat Sheet

CRUD Architecture:
Create: contacts[normalized_key] = {...}
Read: display_all() and search_contacts()
Update: Overwrite dictionary entry with new fields and sync to disk.
Delete: del contacts[key] with prior key existence check.
Normalization: Always use name.strip().lower() for dictionary keys so queries like "AMIT", "amit", and " Amit " match seamlessly.
File I/O Sync: Call save_contacts() immediately after any mutating operation (add, update, delete).
Validation: Enforce validation rules before mutating data state to maintain clean, uncorrupted databases.

⚠️ Production Development Best Practices & Common Traps

1
Always Validate User Input: Never trust raw user inputs. Wrap numeric casts with try...except ValueError to prevent sudden crashes.
2
Defensive File Loading: Always check whether a storage file exists or catch FileNotFoundError when initializing terminal databases.
3
Modular Function Design: Keep functions focused on a single responsibility (e.g. load_data(), save_data(), display_menu(), add_record()).

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

Why is it best practice to normalize contact names with .strip().lower() when storing them as dictionary keys?

Question 2

Which method safely removes a contact key from a dictionary without raising a KeyError if the contact does not exist?

Question 3

In the Contact Book persistence layer, what happens if the storage file does not yet exist on startup?

Question 4

What is the time complexity of searching for a contact by exact name when using a Python dictionary?

Question 5

Why should save_contacts() be called immediately after adding or deleting a contact?

Practice Challenge

Scenario: Contact Book with VIP Favorite Flag & CSV Export

Enhance the Contact Book with two features:

1
VIP Favorite Flag: Add an is_favorite boolean field to each contact (defaulting to False).
2
Toggle VIP Status: Create a function toggle_favorite(contacts, name) that flips the boolean status and saves to disk.
3
Filter Favorites: Implement a function get_favorites(contacts) that returns only VIP contacts.
4
CSV Export: Implement export_to_csv(contacts, filename) that writes the contacts with a standard CSV header: Name,Phone,Email,Category,Favorite.

Starter Code

1# Starting dictionary
2contacts = {
  "arun sharma": {
      "name": "Arun Sharma",
      "phone": "9876543210",
      "email": "arun@example.com",
      "category": "Work",
      "is_favorite": False
  },
  "kavita rani": {
      "name": "Kavita Rani",
      "phone": "9811223344",
      "email": "kavita@example.com",
      "category": "Family",
      "is_favorite": True
  }
17}
18 
19# TODO: Implement toggle_favorite, get_favorites, and export_to_csv

Complete Solution

1contacts = {
2    "arun sharma": {
3        "name": "Arun Sharma",
4        "phone": "9876543210",
5        "email": "arun@example.com",
6        "category": "Work",
7        "is_favorite": False
8    },
9    "kavita rani": {
10        "name": "Kavita Rani",
11        "phone": "9811223344",
12        "email": "kavita@example.com",
13        "category": "Family",
14        "is_favorite": True
15    }
16}
17 
18def toggle_favorite(book: dict, name: str) -> bool:
19    key = name.strip().lower()
20    if key in book:
21        book[key]["is_favorite"] = not book[key]["is_favorite"]
22        status = "Starred VIP" if book[key]["is_favorite"] else "Standard"
23        print(f"[STATUS] {book[key]['name']} is now: {status}")
24        return True
25    print(f"[ERROR] Contact '{name}' not found.")
26    return False
27 
28def get_favorites(book: dict) -> list:
29    return [c for c in book.values() if c.get("is_favorite", False)]
30 
31def export_to_csv(book: dict, filename: str) -> None:
32    with open(filename, "w", encoding="utf-8") as f:
33        f.write("Name,Phone,Email,Category,Favorite\n")
34        for c in book.values():
35            f.write(f"{c['name']},{c['phone']},{c['email']},{c['category']},{c['is_favorite']}\n")
36    print(f"[SUCCESS] Exported {len(book)} contacts to '{filename}'.")
37 
38# Test the enhancements
39toggle_favorite(contacts, "Arun Sharma")
40vip_list = get_favorites(contacts)
41print("\n--- VIP Favorites List ---")
42for vip in vip_list:
43    print(f"⭐ {vip['name']} ({vip['phone']}) - {vip['category']}")
44 
45export_to_csv(contacts, "vip_contacts.csv")
46 
47# Verify exported CSV
48print("\n--- Exported CSV Contents ---")
49with open("vip_contacts.csv", "r", encoding="utf-8") as f:
50    print(f.read().strip())

Expected Output

1[STATUS] Arun Sharma is now: Starred VIP
2 
3--- VIP Favorites List ---
4⭐ Arun Sharma (9876543210) - Work
5⭐ Kavita Rani (9811223344) - Family
6[SUCCESS] Exported 2 contacts to 'vip_contacts.csv'.
7 
8--- Exported CSV Contents ---
9Name,Phone,Email,Category,Favorite
10Arun Sharma,9876543210,arun@example.com,Work,True
11Kavita Rani,9811223344,kavita@example.com,Family,True

🚀 What's Next?

In the next lesson, we will continue your Python learning journey with Quiz Application (16: Projects).

👉 Continue to Next Lesson: Quiz Application →

Next Lesson

Quiz Application

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
File Methods (read, readline, write)	Quiz Application

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext

MSK Institute • Shikohabad

Loading Page Content...

Preparing courses, live labs, and learning resources.सामग्री लोड हो रही है, कृपया प्रतीक्षा करें...

Connecting serverPlease wait...

💻 Practical Labs🚀 Free Demo📜 Verified Certificates

Quiz Application

Capstone Project: CLI Contact Book with File Persistence

Beginner16 min read•Updated: 2026-09-30

Study Materials Cheatsheet

Capstone Project: CLI Contact Book with File Persistence

Real-World Analogy: The Classic Indian Household Telephone Diary

In Indian homes before smartphones, every family kept a spiral-bound telephone diary beside the landline phone:

Visual Architecture Blueprint

+-------------------------------------------------------------------------+
|                  INDIAN HOUSEHOLD TELEPHONE DIARY ARCHITECTURE          |
+-------------------------------------------------------------------------+
|                                                                         |
|   [ CLI Menu Interface ]                                                |
|          │                                                              |
|          ▼                                                              |
|   [ Input Validation Layer ] ──> Validates 10-digit Indian Mobile & Email|
|          │                                                              |
|          ▼                                                              |
|   [ In-Memory Hash Map (Dict) ] ──> Fast O(1) Search, Add, Update, Delete|
|          │                                                              |
|   Save   │  ▲ Load at Startup                                           |
|          ▼  │                                                           |
|   [ Storage Engine: contacts.txt via 'with open()' Context Manager ]    |
|                                                                         |
+-------------------------------------------------------------------------+

1
Bootup: When you open the diary, all prior numbers are already inked in (contacts.txt read into RAM).
2
Adding a contact: You verify the phone number is valid before writing it down (input validation).
3
Searching: You flip directly to the matching letter or name (instant dictionary lookup).
4
Shutdown: Every time you write an entry, it remains safely preserved on paper even if the power goes out (disk persistence).

Project Specification & Architecture

Our Contact Book requires the following specifications:

Data Model: An in-memory dictionary where normalized contact names serve as keys:

contacts = {
    "rahul sharma": {
        "name": "Rahul Sharma",
        "phone": "9876543210",
        "email": "rahul.sharma@example.com",
        "category": "Work"
    }
}

File Persistence: Contacts are serialized to a pipe-delimited text file (contacts_db.txt) using the format:

Name|Phone|Email|Category\n

Validation Rules:
Phone number must consist of exactly 10 numeric digits.
Email must contain @ and a period . after @.
Duplicate contact names trigger an overwrite confirmation.
Menu System: An infinite while True loop with interactive options 1 to 6.

Step-by-Step Implementation

Step 1: Input Validation Helper Functions

1def validate_phone(phone: str) -> bool:
  """Validates that a phone number contains exactly 10 digits."""
  cleaned = phone.strip()
  return len(cleaned) == 10 and cleaned.isdigit()
5 
6def validate_email(email: str) -> bool:
  """Basic validation for email format."""
  cleaned = email.strip()
  if "@" in cleaned and "." in cleaned:
      at_index = cleaned.find("@")
      dot_index = cleaned.rfind(".")
      return at_index > 0 and dot_index > at_index + 1 and dot_index < len(cleaned) - 1
  return False

Step 2: Storage Engine with Context Manager

1import os
2 
3STORAGE_FILE = "contacts_db.txt"
4 
5def load_contacts() -> dict:
  """Loads saved contacts from disk into an in-memory dictionary."""
  contacts = {}
  if not os.path.exists(STORAGE_FILE):
      return contacts
10 
  with open(STORAGE_FILE, "r", encoding="utf-8") as f:
      for line in f:
          line = line.strip()
          if not line:
              continue
          parts = line.split("|")
          if len(parts) == 4:
              name, phone, email, category = parts
              contacts[name.lower()] = {
                  "name": name,
                  "phone": phone,
                  "email": email,
                  "category": category
              }
  return contacts
26 
27def save_contacts(contacts: dict) -> None:
  """Persists the dictionary state to disk safely using with open()."""
  with open(STORAGE_FILE, "w", encoding="utf-8") as f:
      for contact in contacts.values():
          f.write(f"{contact['name']}|{contact['phone']}|{contact['email']}|{contact['category']}\n")

Step 3: Complete Production-Grade Contact Book Script

Here is the complete, modular, runnable code for the entire Contact Book system:

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

def validate_phone

phone: str

Step 2

bool:

Expected Output

1=== Populating Initial Contacts ===
2[SUCCESS] Contact 'Amitabh Sharma' saved successfully.
3[SUCCESS] Contact 'Pooja Hegde' saved successfully.
4[SUCCESS] Contact 'Suresh Kumar' saved successfully.
5 
6=== Displaying All Stored Contacts ===
7===========================================================================
8NAME                 | PHONE        | EMAIL                     | CATEGORY  
9===========================================================================
10Amitabh Sharma       | 9876543210   | amitabh@example.com       | Work      
11Pooja Hegde          | 9123456780   | pooja.h@example.com       | Friends   
12Suresh Kumar         | 9988776655   | suresh.k@example.com      | Family    
13===========================================================================
14 
15=== Searching for 'sharma' ===
16Found: Amitabh Sharma (9876543210) - amitabh@example.com
17 
18=== Deleting 'Pooja Hegde' ===
19[SUCCESS] Contact 'Pooja Hegde' deleted successfully.
20 
21=== Loading Fresh from Disk to Prove Persistence ===
22===========================================================================
23NAME                 | PHONE        | EMAIL                     | CATEGORY  
24===========================================================================
25Amitabh Sharma       | 9876543210   | amitabh@example.com       | Work      
26Suresh Kumar         | 9988776655   | suresh.k@example.com      | Family    
27===========================================================================

Best Practices & Comparison: Do's and Don'ts

Practice	Bad Implementation	Gold-Standard Implementation
Lookup Keys	Using case-sensitive keys (`"Rahul"` vs `"rahul"`)	Normalize keys with `.strip().lower()`
Input Validation	Trusting user input blindly without checks	Validate 10-digit format and email structure before saving
Persistence	Keeping contacts purely in RAM (lost on crash)	Persist every mutation to disk using `with open()`
Data Format	Unstructured arbitrary string writes	Consistent structured delimiter (`\	` or CSV/JSON)
Search	Exact match only	Substring search across both name and phone fields
Deletion	Crashing with `KeyError` if name is missing	Verify key existence with `if key in contacts:`

Quick Revision Summary Cheat Sheet

CRUD Architecture:
Create: contacts[normalized_key] = {...}
Read: display_all() and search_contacts()
Update: Overwrite dictionary entry with new fields and sync to disk.
Delete: del contacts[key] with prior key existence check.
Normalization: Always use name.strip().lower() for dictionary keys so queries like "AMIT", "amit", and " Amit " match seamlessly.
File I/O Sync: Call save_contacts() immediately after any mutating operation (add, update, delete).
Validation: Enforce validation rules before mutating data state to maintain clean, uncorrupted databases.

⚠️ Production Development Best Practices & Common Traps

1
Always Validate User Input: Never trust raw user inputs. Wrap numeric casts with try...except ValueError to prevent sudden crashes.
2
Defensive File Loading: Always check whether a storage file exists or catch FileNotFoundError when initializing terminal databases.
3
Modular Function Design: Keep functions focused on a single responsibility (e.g. load_data(), save_data(), display_menu(), add_record()).

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

Why is it best practice to normalize contact names with .strip().lower() when storing them as dictionary keys?

Question 2

Which method safely removes a contact key from a dictionary without raising a KeyError if the contact does not exist?

Question 3

In the Contact Book persistence layer, what happens if the storage file does not yet exist on startup?

Question 4

What is the time complexity of searching for a contact by exact name when using a Python dictionary?

Question 5

Why should save_contacts() be called immediately after adding or deleting a contact?

Practice Challenge

Scenario: Contact Book with VIP Favorite Flag & CSV Export

Enhance the Contact Book with two features:

1
VIP Favorite Flag: Add an is_favorite boolean field to each contact (defaulting to False).
2
Toggle VIP Status: Create a function toggle_favorite(contacts, name) that flips the boolean status and saves to disk.
3
Filter Favorites: Implement a function get_favorites(contacts) that returns only VIP contacts.
4
CSV Export: Implement export_to_csv(contacts, filename) that writes the contacts with a standard CSV header: Name,Phone,Email,Category,Favorite.

Starter Code

1# Starting dictionary
2contacts = {
  "arun sharma": {
      "name": "Arun Sharma",
      "phone": "9876543210",
      "email": "arun@example.com",
      "category": "Work",
      "is_favorite": False
  },
  "kavita rani": {
      "name": "Kavita Rani",
      "phone": "9811223344",
      "email": "kavita@example.com",
      "category": "Family",
      "is_favorite": True
  }
17}
18 
19# TODO: Implement toggle_favorite, get_favorites, and export_to_csv

Complete Solution

1contacts = {
2    "arun sharma": {
3        "name": "Arun Sharma",
4        "phone": "9876543210",
5        "email": "arun@example.com",
6        "category": "Work",
7        "is_favorite": False
8    },
9    "kavita rani": {
10        "name": "Kavita Rani",
11        "phone": "9811223344",
12        "email": "kavita@example.com",
13        "category": "Family",
14        "is_favorite": True
15    }
16}
17 
18def toggle_favorite(book: dict, name: str) -> bool:
19    key = name.strip().lower()
20    if key in book:
21        book[key]["is_favorite"] = not book[key]["is_favorite"]
22        status = "Starred VIP" if book[key]["is_favorite"] else "Standard"
23        print(f"[STATUS] {book[key]['name']} is now: {status}")
24        return True
25    print(f"[ERROR] Contact '{name}' not found.")
26    return False
27 
28def get_favorites(book: dict) -> list:
29    return [c for c in book.values() if c.get("is_favorite", False)]
30 
31def export_to_csv(book: dict, filename: str) -> None:
32    with open(filename, "w", encoding="utf-8") as f:
33        f.write("Name,Phone,Email,Category,Favorite\n")
34        for c in book.values():
35            f.write(f"{c['name']},{c['phone']},{c['email']},{c['category']},{c['is_favorite']}\n")
36    print(f"[SUCCESS] Exported {len(book)} contacts to '{filename}'.")
37 
38# Test the enhancements
39toggle_favorite(contacts, "Arun Sharma")
40vip_list = get_favorites(contacts)
41print("\n--- VIP Favorites List ---")
42for vip in vip_list:
43    print(f"⭐ {vip['name']} ({vip['phone']}) - {vip['category']}")
44 
45export_to_csv(contacts, "vip_contacts.csv")
46 
47# Verify exported CSV
48print("\n--- Exported CSV Contents ---")
49with open("vip_contacts.csv", "r", encoding="utf-8") as f:
50    print(f.read().strip())

Expected Output

1[STATUS] Arun Sharma is now: Starred VIP
2 
3--- VIP Favorites List ---
4⭐ Arun Sharma (9876543210) - Work
5⭐ Kavita Rani (9811223344) - Family
6[SUCCESS] Exported 2 contacts to 'vip_contacts.csv'.
7 
8--- Exported CSV Contents ---
9Name,Phone,Email,Category,Favorite
10Arun Sharma,9876543210,arun@example.com,Work,True
11Kavita Rani,9811223344,kavita@example.com,Family,True

🚀 What's Next?

In the next lesson, we will continue your Python learning journey with Quiz Application (16: Projects).

👉 Continue to Next Lesson: Quiz Application →

Next Lesson

Quiz Application

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
File Methods (read, readline, write)	Quiz Application

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next