📘 Custom Data Structures: Building Your Own

🎯 Introduction

Welcome to this exciting tutorial on custom data structures in Python! 🎉 In this guide, we’ll explore how to create your own powerful data structures that go beyond Python’s built-in types.

You’ll discover how custom data structures can transform your Python development experience. Whether you’re building web applications 🌐, analyzing data 📊, or creating games 🎮, understanding how to build custom data structures is essential for writing efficient, maintainable code.

By the end of this tutorial, you’ll feel confident creating your own data structures tailored to your specific needs! Let’s dive in! 🏊‍♂️

📚 Understanding Custom Data Structures

🤔 What are Custom Data Structures?

Custom data structures are like building your own LEGO sets 🧱. Think of it as creating specialized containers that perfectly fit your data, just like designing a custom toolbox 🧰 with compartments exactly where you need them!

In Python terms, custom data structures are classes that organize and manage data in ways that make sense for your specific problem. This means you can:

✨ Create intuitive interfaces for complex data
🚀 Optimize performance for specific use cases
🛡️ Enforce data integrity and validation rules

💡 Why Build Custom Data Structures?

Here’s why developers love creating custom data structures:

Domain-Specific Logic 🔒: Encapsulate business rules and behavior
Better Performance 💻: Optimize for your specific access patterns
Code Clarity 📖: Make your code more readable and self-documenting
Reusability 🔧: Create once, use everywhere in your project

Real-world example: Imagine building a music playlist 🎵. With a custom data structure, you can ensure songs flow smoothly, manage play counts, and handle shuffling efficiently!

🔧 Basic Syntax and Usage

📝 Simple Example: A Stack

Let’s start with a friendly example - building our own Stack:

# 👋 Hello, Custom Data Structures!
class Stack:
    def __init__(self):
        # 🎨 Creating our internal storage
        self.items = []
    
    def push(self, item):
        # ➕ Add item to top of stack
        self.items.append(item)
        print(f"Pushed {item} onto stack! 📦")
    
    def pop(self):
        # 📤 Remove and return top item
        if not self.is_empty():
            item = self.items.pop()
            print(f"Popped {item} from stack! 🎯")
            return item
        return None
    
    def is_empty(self):
        # 🔍 Check if stack is empty
        return len(self.items) == 0
    
    def peek(self):
        # 👀 Look at top item without removing
        if not self.is_empty():
            return self.items[-1]
        return None

# 🎮 Let's use it!
stack = Stack()
stack.push("Python 🐍")
stack.push("JavaScript 🌟")
stack.push("TypeScript 💙")
print(f"Top item: {stack.peek()}")

💡 Explanation: Notice how we use emojis in print statements to make output more fun! The Stack follows Last-In-First-Out (LIFO) principle.

🎯 Common Patterns

Here are patterns you’ll use when building custom data structures:

# 🏗️ Pattern 1: Node-based structures
class Node:
    def __init__(self, data):
        self.data = data    # 📦 Store the data
        self.next = None    # 🔗 Link to next node

# 🎨 Pattern 2: Size tracking
class BoundedQueue:
    def __init__(self, max_size):
        self.items = []
        self.max_size = max_size  # 🚧 Set capacity limit
    
    def enqueue(self, item):
        if len(self.items) < self.max_size:
            self.items.append(item)
        else:
            print("Queue is full! 🚫")

# 🔄 Pattern 3: Magic methods for Pythonic behavior
class CustomList:
    def __init__(self):
        self.data = []
    
    def __len__(self):
        # 📏 Support len() function
        return len(self.data)
    
    def __getitem__(self, index):
        # 🎯 Support indexing: my_list[0]
        return self.data[index]
    
    def __str__(self):
        # 🖨️ Pretty printing
        return f"CustomList({self.data})"

💡 Practical Examples

🛒 Example 1: Shopping Cart with History

Let’s build something real - a shopping cart that tracks your shopping history:

# 🛍️ Define our product
class Product:
    def __init__(self, name, price, emoji="🛍️"):
        self.name = name
        self.price = price
        self.emoji = emoji
    
    def __str__(self):
        return f"{self.emoji} {self.name} - ${self.price:.2f}"

# 🛒 Shopping cart with superpowers!
class SmartShoppingCart:
    def __init__(self):
        self.items = {}          # 📦 Current items {product: quantity}
        self.history = []        # 📜 Track all actions
        self.total_saved = 0     # 💰 Track savings
    
    # ➕ Add item to cart
    def add_item(self, product, quantity=1):
        if product in self.items:
            self.items[product] += quantity
        else:
            self.items[product] = quantity
        
        self.history.append(f"Added {quantity}x {product}")
        print(f"Added {product} to cart! ✅")
    
    # 💰 Calculate total with discount
    def get_total(self, discount_percent=0):
        subtotal = sum(product.price * qty 
                      for product, qty in self.items.items())
        discount = subtotal * (discount_percent / 100)
        self.total_saved += discount
        return subtotal - discount
    
    # 📋 Display cart contents
    def display(self):
        print("🛒 Your Shopping Cart:")
        print("-" * 30)
        for product, quantity in self.items.items():
            total = product.price * quantity
            print(f"{quantity}x {product} = ${total:.2f}")
        print("-" * 30)
        print(f"💰 Total: ${self.get_total():.2f}")
        
    # 📜 Show shopping history
    def show_history(self):
        print("\n📜 Shopping History:")
        for action in self.history[-5:]:  # Last 5 actions
            print(f"  • {action}")
        print(f"💸 Total saved: ${self.total_saved:.2f}")

# 🎮 Let's go shopping!
cart = SmartShoppingCart()
cart.add_item(Product("Python Book", 29.99, "📘"), 1)
cart.add_item(Product("Coffee", 4.99, "☕"), 3)
cart.add_item(Product("Mechanical Keyboard", 89.99, "⌨️"), 1)
cart.display()
print(f"\n🎉 With 10% discount: ${cart.get_total(10):.2f}")
cart.show_history()

🎯 Try it yourself: Add a remove_item method and a wishlist feature!

🎮 Example 2: Game Leaderboard

Let’s make it fun with a self-sorting leaderboard:

# 🏆 Player score entry
class Player:
    def __init__(self, name, score, avatar="🎮"):
        self.name = name
        self.score = score
        self.avatar = avatar
        self.achievements = []
    
    def __str__(self):
        return f"{self.avatar} {self.name}: {self.score} points"
    
    def __lt__(self, other):
        # 🔄 For automatic sorting (higher scores first)
        return self.score > other.score

# 📊 Smart leaderboard
class GameLeaderboard:
    def __init__(self, max_players=10):
        self.players = []           # 🏆 Top players
        self.max_players = max_players
        self.hall_of_fame = set()  # 🌟 All-time high scorers
    
    # 🎯 Add or update player score
    def add_score(self, name, score, avatar="🎮"):
        # Check if player exists
        existing = next((p for p in self.players if p.name == name), None)
        
        if existing:
            # 📈 Update existing score
            if score > existing.score:
                existing.score = score
                print(f"🎯 {name} improved their score to {score}!")
                self._check_achievement(existing, score)
        else:
            # 🆕 New player
            player = Player(name, score, avatar)
            self.players.append(player)
            print(f"🎉 Welcome {name} to the leaderboard!")
            self._check_achievement(player, score)
        
        # 🔄 Keep sorted and trim to max size
        self.players.sort()
        if len(self.players) > self.max_players:
            removed = self.players.pop()
            print(f"😢 Sorry {removed.name}, you've been bumped off!")
    
    # 🏆 Check for achievements
    def _check_achievement(self, player, score):
        if score >= 1000 and "🌟 Thousand Club" not in player.achievements:
            player.achievements.append("🌟 Thousand Club")
            self.hall_of_fame.add(player.name)
            print(f"🏆 {player.name} joined the Thousand Club!")
        
        if score >= 5000 and "💎 Elite Player" not in player.achievements:
            player.achievements.append("💎 Elite Player")
            print(f"💎 {player.name} is now an Elite Player!")
    
    # 📊 Display leaderboard
    def display(self):
        print("\n🏆 GAME LEADERBOARD 🏆")
        print("=" * 35)
        for i, player in enumerate(self.players, 1):
            medals = {1: "🥇", 2: "🥈", 3: "🥉"}
            medal = medals.get(i, "  ")
            print(f"{medal} {i}. {player}")
            if player.achievements:
                print(f"      Achievements: {', '.join(player.achievements)}")
        print("=" * 35)
        
        if self.hall_of_fame:
            print(f"\n🌟 Hall of Fame: {', '.join(self.hall_of_fame)}")

# 🎮 Game time!
leaderboard = GameLeaderboard(max_players=5)

# Add some players
players = [
    ("Alice", 1200, "👩‍💻"),
    ("Bob", 850, "🧑‍💻"),
    ("Charlie", 5500, "👨‍💻"),
    ("Diana", 950, "👩‍🎮"),
    ("Eve", 1100, "🦸‍♀️"),
    ("Frank", 2000, "🥷")
]

for name, score, avatar in players:
    leaderboard.add_score(name, score, avatar)

leaderboard.display()

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Binary Search Tree

When you’re ready to level up, try this self-balancing data structure:

# 🎯 Advanced tree node
class TreeNode:
    def __init__(self, value):
        self.value = value
        self.left = None   # 👈 Left child
        self.right = None  # 👉 Right child
        self.height = 1    # 📏 For balancing

# 🌳 Self-organizing binary search tree
class SmartBST:
    def __init__(self):
        self.root = None
        self.size = 0
        self.traverse_path = []  # 🗺️ Track navigation
    
    def insert(self, value):
        # 🌱 Plant a new value
        self.root = self._insert_recursive(self.root, value)
        self.size += 1
        print(f"🌱 Inserted {value} into the tree!")
    
    def _insert_recursive(self, node, value):
        # 🎯 Find the right spot
        if not node:
            return TreeNode(value)
        
        if value < node.value:
            self.traverse_path.append("Left 👈")
            node.left = self._insert_recursive(node.left, value)
        else:
            self.traverse_path.append("Right 👉")
            node.right = self._insert_recursive(node.right, value)
        
        return node
    
    def search(self, value):
        # 🔍 Hunt for a value
        self.traverse_path = []
        found = self._search_recursive(self.root, value)
        
        if found:
            path = " → ".join(self.traverse_path)
            print(f"✅ Found {value}! Path: {path}")
        else:
            print(f"❌ {value} not found in tree")
        
        return found
    
    def _search_recursive(self, node, value):
        if not node:
            return False
        
        if value == node.value:
            self.traverse_path.append(f"Found {value}! 🎯")
            return True
        elif value < node.value:
            self.traverse_path.append(f"Go left from {node.value} 👈")
            return self._search_recursive(node.left, value)
        else:
            self.traverse_path.append(f"Go right from {node.value} 👉")
            return self._search_recursive(node.right, value)

🏗️ Advanced Topic 2: LRU Cache

For the brave developers - a cache that remembers what you use most:

from collections import OrderedDict

# 🚀 Least Recently Used Cache
class LRUCache:
    def __init__(self, capacity):
        self.cache = OrderedDict()  # 📦 Maintains order
        self.capacity = capacity
        self.hits = 0               # ✅ Cache hits
        self.misses = 0             # ❌ Cache misses
    
    def get(self, key):
        # 🔍 Retrieve with tracking
        if key in self.cache:
            # 🎯 Cache hit! Move to end (most recent)
            self.cache.move_to_end(key)
            self.hits += 1
            print(f"✅ Cache hit for '{key}'!")
            return self.cache[key]
        else:
            # 😢 Cache miss
            self.misses += 1
            print(f"❌ Cache miss for '{key}'")
            return None
    
    def put(self, key, value):
        # 📥 Store with eviction
        if key in self.cache:
            # 🔄 Update existing
            self.cache.move_to_end(key)
        
        self.cache[key] = value
        
        # 🗑️ Evict least recently used if over capacity
        if len(self.cache) > self.capacity:
            oldest_key = next(iter(self.cache))
            del self.cache[oldest_key]
            print(f"🗑️ Evicted '{oldest_key}' from cache")
        
        print(f"💾 Stored '{key}' in cache")
    
    def stats(self):
        # 📊 Performance metrics
        total = self.hits + self.misses
        hit_rate = (self.hits / total * 100) if total > 0 else 0
        
        print("\n📊 Cache Statistics:")
        print(f"  ✅ Hits: {self.hits}")
        print(f"  ❌ Misses: {self.misses}")
        print(f"  🎯 Hit Rate: {hit_rate:.1f}%")
        print(f"  📦 Current Size: {len(self.cache)}/{self.capacity}")

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Forgetting to Handle Edge Cases

# ❌ Wrong way - No bounds checking!
class UnsafeArray:
    def __init__(self, size):
        self.data = [None] * size
    
    def get(self, index):
        return self.data[index]  # 💥 IndexError if out of bounds!

# ✅ Correct way - Always validate!
class SafeArray:
    def __init__(self, size):
        self.data = [None] * size
        self.size = size
    
    def get(self, index):
        if 0 <= index < self.size:
            return self.data[index]
        else:
            print(f"⚠️ Index {index} out of bounds!")
            return None

🤯 Pitfall 2: Memory Leaks in Linked Structures

# ❌ Dangerous - Circular references!
class LeakyNode:
    def __init__(self, data):
        self.data = data
        self.next = None
        self.prev = None  # 💥 Can create reference cycles!

# ✅ Safe - Proper cleanup!
class CleanNode:
    def __init__(self, data):
        self.data = data
        self.next = None
        self.prev = None
    
    def disconnect(self):
        # 🧹 Clean up references
        self.next = None
        self.prev = None
        print(f"🧹 Node {self.data} disconnected safely!")

🛠️ Best Practices

🎯 Define Clear Interfaces: Make methods intuitive and consistent
📝 Use Magic Methods: Implement __str__, __len__, __getitem__ for Pythonic behavior
🛡️ Validate Input: Always check bounds and types
🎨 Keep It Simple: Don’t over-engineer - start simple, add features as needed
✨ Document Behavior: Use docstrings to explain what your structure does

🧪 Hands-On Exercise

🎯 Challenge: Build a Priority Queue

Create a priority queue that handles tasks by importance:

📋 Requirements:

✅ Tasks with priority levels (1-5, where 5 is highest)
🏷️ Task categories (work, personal, urgent)
👤 Task assignment to team members
📅 Due dates with automatic priority boost
🎨 Each task needs a status emoji!

🚀 Bonus Points:

Add task dependencies
Implement priority aging (tasks get more important over time)
Create a visualization method

💡 Solution

🔍 Click to see solution

import heapq
from datetime import datetime, timedelta

# 🎯 Our priority queue task system!
class Task:
    def __init__(self, title, priority, category, assignee=None, due_date=None):
        self.title = title
        self.priority = priority  # 1-5
        self.category = category
        self.assignee = assignee
        self.due_date = due_date
        self.created_at = datetime.now()
        self.status_emoji = "📋"
        self.completed = False
    
    def __lt__(self, other):
        # 🔄 For heap comparison (higher priority first)
        return self.get_effective_priority() > other.get_effective_priority()
    
    def get_effective_priority(self):
        # 📈 Boost priority based on age and deadline
        base_priority = self.priority
        
        # Age boost: +0.1 per day old
        age_days = (datetime.now() - self.created_at).days
        age_boost = age_days * 0.1
        
        # Deadline boost: +1 if due within 24 hours
        deadline_boost = 0
        if self.due_date:
            time_until_due = self.due_date - datetime.now()
            if time_until_due < timedelta(days=1):
                deadline_boost = 1
                self.status_emoji = "🔥"  # Urgent!
        
        return base_priority + age_boost + deadline_boost
    
    def __str__(self):
        assignee_str = f" → {self.assignee}" if self.assignee else ""
        due_str = f" 📅 {self.due_date.strftime('%Y-%m-%d')}" if self.due_date else ""
        return f"{self.status_emoji} [{self.priority}⭐] {self.title}{assignee_str}{due_str}"

class PriorityTaskQueue:
    def __init__(self):
        self.tasks = []  # 📦 Min heap (we negate priority)
        self.completed_tasks = []
        self.task_counter = 0
    
    def add_task(self, title, priority=3, category="general", assignee=None, due_date=None):
        # ➕ Add a new task
        if not 1 <= priority <= 5:
            print("⚠️ Priority must be between 1-5!")
            return
        
        task = Task(title, priority, category, assignee, due_date)
        
        # Set emoji based on category
        emoji_map = {
            "work": "💼",
            "personal": "🏠",
            "urgent": "🚨",
            "general": "📋"
        }
        task.status_emoji = emoji_map.get(category, "📋")
        
        # Use negative priority for max heap behavior
        heapq.heappush(self.tasks, task)
        self.task_counter += 1
        print(f"✅ Added task: {task}")
    
    def get_next_task(self):
        # 🎯 Get highest priority task
        if self.tasks:
            task = heapq.heappop(self.tasks)
            print(f"📤 Next task: {task}")
            return task
        else:
            print("📭 No tasks in queue!")
            return None
    
    def complete_task(self, task):
        # ✅ Mark task as done
        task.completed = True
        task.status_emoji = "✅"
        self.completed_tasks.append(task)
        print(f"🎉 Completed: {task.title}")
    
    def show_queue(self):
        # 📊 Display all pending tasks
        print("\n📋 TASK QUEUE")
        print("=" * 50)
        
        # Create a copy to preserve heap
        temp_tasks = sorted(self.tasks, reverse=True)
        
        if not temp_tasks:
            print("📭 No pending tasks!")
        else:
            for i, task in enumerate(temp_tasks, 1):
                eff_priority = task.get_effective_priority()
                print(f"{i}. {task} (Effective: {eff_priority:.1f}⭐)")
        
        print("=" * 50)
        print(f"📊 Total: {len(self.tasks)} pending, {len(self.completed_tasks)} completed")
    
    def get_stats_by_assignee(self):
        # 👥 Show workload distribution
        assignee_tasks = {}
        for task in self.tasks:
            if task.assignee:
                assignee_tasks[task.assignee] = assignee_tasks.get(task.assignee, 0) + 1
        
        print("\n👥 Workload Distribution:")
        for assignee, count in assignee_tasks.items():
            print(f"  {assignee}: {count} tasks")

# 🎮 Test it out!
queue = PriorityTaskQueue()

# Add various tasks
queue.add_task("Fix critical bug", 5, "urgent", "Alice")
queue.add_task("Write documentation", 2, "work", "Bob")
queue.add_task("Buy groceries", 3, "personal")
queue.add_task("Deploy to production", 4, "work", "Alice", 
               datetime.now() + timedelta(hours=3))
queue.add_task("Team meeting", 3, "work", due_date=datetime.now() + timedelta(days=2))

queue.show_queue()
queue.get_stats_by_assignee()

# Process some tasks
print("\n🔄 Processing tasks...")
for _ in range(2):
    task = queue.get_next_task()
    if task:
        queue.complete_task(task)

queue.show_queue()

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create custom data structures with confidence 💪
✅ Implement special methods for Pythonic behavior 🛡️
✅ Design efficient algorithms for your data 🎯
✅ Handle edge cases like a pro 🐛
✅ Build real-world applications with custom structures! 🚀

Remember: Custom data structures are tools in your toolbox. Choose the right one for each job! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered custom data structures in Python!

Here’s what to do next:

💻 Practice with the exercises above
🏗️ Build a custom data structure for your current project
📚 Move on to our next tutorial: Advanced Data Structure Patterns
🌟 Share your creative data structures with others!

Remember: Every Python expert started by building their first custom class. Keep coding, keep learning, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨

Prerequisites

What you'll learn