📘 __len__, __getitem__: Container Protocol

🎯 Introduction

Welcome to this exciting tutorial on Python’s Container Protocol! 🎉 In this guide, we’ll explore how __len__ and __getitem__ transform your custom objects into powerful, container-like structures that work seamlessly with Python’s built-in functions.

You’ll discover how these special methods (also called “dunder methods” or “magic methods”) can make your objects behave like lists, dictionaries, or any other container you can imagine. Whether you’re building data structures 📊, game inventories 🎮, or custom collections 📚, understanding the container protocol is essential for writing elegant, Pythonic code.

By the end of this tutorial, you’ll feel confident creating your own container classes that integrate beautifully with Python’s ecosystem! Let’s dive in! 🏊‍♂️

📚 Understanding Container Protocol

🤔 What is the Container Protocol?

The Container Protocol is like giving your objects superpowers 🦸‍♂️. Think of it as teaching your custom objects to speak Python’s native language, allowing them to work with built-in functions like len(), indexing with [], and iteration.

In Python terms, the container protocol consists of special methods that define how your object behaves as a container. This means you can:

• ✨ Use len() to get the size of your object
• 🚀 Access items using square bracket notation obj[index]
• 🛡️ Make your objects iterable with for loops

💡 Why Use Container Protocol?

Here’s why developers love implementing container protocols:

1. Pythonic Interface 🐍: Your objects work like built-in types
2. Intuitive Usage 💻: Users already know how to use containers
3. Powerful Integration 📖: Works with Python’s built-in functions
4. Clean Code 🔧: No need for custom getter methods

Real-world example: Imagine building a playlist manager 🎵. With the container protocol, users can check playlist length with len(playlist) and access songs with playlist[0] - just like they would with a regular list!

🔧 Basic Syntax and Usage

📝 Simple Example

Let’s start with a friendly example:

# 👋 Hello, Container Protocol!
class SimplePlaylist:
    def __init__(self):
        self.songs = []  # 🎵 Our song collection
    
    def __len__(self):
        # 📏 Return the number of songs
        return len(self.songs)
    
    def __getitem__(self, index):
        # 🎯 Return song at given index
        return self.songs[index]
    
    def add_song(self, song):
        # ➕ Add a new song
        self.songs.append(song)
        print(f"🎵 Added: {song}")

# 🎮 Let's use it!
playlist = SimplePlaylist()
playlist.add_song("Python Blues 🎸")
playlist.add_song("Container Rock 🎹")

print(f"Playlist length: {len(playlist)}")  # Uses __len__
print(f"First song: {playlist[0]}")         # Uses __getitem__

💡 Explanation: Notice how we can use len() and [] indexing on our custom object! Python automatically calls our __len__ and __getitem__ methods.

🎯 Common Patterns

Here are patterns you’ll use daily:

# 🏗️ Pattern 1: Dictionary-like container
class ConfigManager:
    def __init__(self):
        self._config = {}  # 📦 Private storage
    
    def __len__(self):
        return len(self._config)
    
    def __getitem__(self, key):
        if key not in self._config:
            raise KeyError(f"🚫 Config '{key}' not found!")
        return self._config[key]
    
    def __setitem__(self, key, value):
        # 🎨 Bonus: Allow setting items too!
        self._config[key] = value
        print(f"✅ Set {key} = {value}")

# 🔄 Pattern 2: Slicing support
class NumberSequence:
    def __init__(self, start, end):
        self.numbers = list(range(start, end))
    
    def __len__(self):
        return len(self.numbers)
    
    def __getitem__(self, index):
        # 🚀 Support both indexing and slicing!
        if isinstance(index, slice):
            return NumberSequence(0, 0).__class__(self.numbers[index])
        return self.numbers[index]

💡 Practical Examples

🛒 Example 1: Shopping Cart Container

Let’s build something real:

# 🛍️ A smart shopping cart
class ShoppingCart:
    def __init__(self):
        self.items = []  # 📦 Cart items
        self.quantities = {}  # 🔢 Item quantities
    
    def __len__(self):
        # 📏 Total number of unique items
        return len(self.items)
    
    def __getitem__(self, index):
        # 🎯 Get item by index or name
        if isinstance(index, int):
            return self.items[index]
        elif isinstance(index, str):
            # 🎨 Allow string indexing too!
            for item in self.items:
                if item['name'] == index:
                    return item
            raise KeyError(f"🚫 Item '{index}' not in cart!")
    
    def add_item(self, name, price, emoji="🛍️"):
        # ➕ Add or update item
        for item in self.items:
            if item['name'] == name:
                self.quantities[name] += 1
                print(f"➕ Added another {emoji} {name}")
                return
        
        # 🆕 New item
        self.items.append({
            'name': name,
            'price': price,
            'emoji': emoji
        })
        self.quantities[name] = 1
        print(f"🛒 Added {emoji} {name} - ${price}")
    
    def __iter__(self):
        # 🔄 Make cart iterable
        return iter(self.items)
    
    def total(self):
        # 💰 Calculate total price
        total = 0
        for item in self.items:
            total += item['price'] * self.quantities[item['name']]
        return total

# 🎮 Let's go shopping!
cart = ShoppingCart()
cart.add_item("Python Book", 29.99, "📘")
cart.add_item("Coffee", 4.99, "☕")
cart.add_item("Python Book", 29.99, "📘")  # Adding another!

print(f"\n🛒 Cart has {len(cart)} unique items")
print(f"📘 First item: {cart[0]['name']}")
print(f"☕ Coffee details: {cart['Coffee']}")
print(f"💰 Total: ${cart.total():.2f}")

# 🔄 Iterate through cart
print("\n📋 Cart contents:")
for item in cart:
    qty = cart.quantities[item['name']]
    print(f"  {item['emoji']} {item['name']} x{qty} - ${item['price'] * qty:.2f}")

🎯 Try it yourself: Add a __delitem__ method to remove items from the cart!

🎮 Example 2: Game Inventory System

Let’s make it fun:

# 🏆 RPG-style inventory system
class GameInventory:
    def __init__(self, capacity=20):
        self.items = []  # 🎒 Inventory items
        self.capacity = capacity  # 📏 Max capacity
        self.categories = {
            'weapon': '⚔️',
            'armor': '🛡️',
            'potion': '🧪',
            'treasure': '💎',
            'food': '🍖'
        }
    
    def __len__(self):
        # 📏 Current inventory size
        return len(self.items)
    
    def __getitem__(self, key):
        # 🎯 Get by index, name, or category
        if isinstance(key, int):
            return self.items[key]
        elif isinstance(key, str):
            # 🔍 Search by name
            matching_items = [item for item in self.items if item['name'] == key]
            if matching_items:
                return matching_items[0] if len(matching_items) == 1 else matching_items
            # 🏷️ Search by category
            category_items = [item for item in self.items if item['category'] == key]
            if category_items:
                return category_items
            raise KeyError(f"🚫 No items found for '{key}'")
    
    def add_item(self, name, category, value, quantity=1):
        # ➕ Add item to inventory
        if len(self.items) >= self.capacity:
            print(f"🎒 Inventory full! Can't add {name}")
            return False
        
        # 🔍 Check if item exists
        for item in self.items:
            if item['name'] == name:
                item['quantity'] += quantity
                print(f"➕ Added {quantity} more {name}(s)")
                return True
        
        # 🆕 New item
        emoji = self.categories.get(category, '❓')
        self.items.append({
            'name': name,
            'category': category,
            'value': value,
            'quantity': quantity,
            'emoji': emoji
        })
        print(f"{emoji} Found {name}! (Value: {value} gold)")
        return True
    
    def __contains__(self, item_name):
        # 🔍 Check if item exists (enables 'in' operator)
        return any(item['name'] == item_name for item in self.items)
    
    def get_stats(self):
        # 📊 Inventory statistics
        total_value = sum(item['value'] * item['quantity'] for item in self.items)
        print(f"\n📊 Inventory Stats:")
        print(f"  🎒 Items: {len(self)}/{self.capacity}")
        print(f"  💰 Total Value: {total_value} gold")
        
        # 🏷️ Items by category
        for category, emoji in self.categories.items():
            category_items = self[category] if category in ['weapon', 'armor', 'potion', 'treasure', 'food'] else []
            if category_items:
                count = sum(item['quantity'] for item in category_items)
                print(f"  {emoji} {category.title()}: {count}")

# 🎮 Adventure time!
inventory = GameInventory(capacity=10)

# 🗡️ Finding loot!
inventory.add_item("Iron Sword", "weapon", 100)
inventory.add_item("Health Potion", "potion", 50, 3)
inventory.add_item("Dragon Scale", "armor", 500)
inventory.add_item("Bread", "food", 5, 2)
inventory.add_item("Ruby", "treasure", 250)

# 🎯 Using container protocol
print(f"\n🎒 Inventory has {len(inventory)} item types")
print(f"⚔️ First item: {inventory[0]['name']}")
print(f"🧪 Potions: {inventory['potion']}")

# 🔍 Check for items
if "Iron Sword" in inventory:
    print("⚔️ You have a weapon equipped!")

inventory.get_stats()

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Supporting Negative Indexing

When you’re ready to level up, add support for negative indexing:

# 🎯 Advanced container with full indexing support
class SmartList:
    def __init__(self, items=None):
        self._items = items or []
    
    def __len__(self):
        return len(self._items)
    
    def __getitem__(self, index):
        # 🚀 Support negative indexing and slicing!
        if isinstance(index, slice):
            # 🎨 Return new SmartList for slices
            return SmartList(self._items[index])
        
        # 🛡️ Handle negative indices
        if isinstance(index, int):
            if index < 0:
                index += len(self)
            if 0 <= index < len(self):
                return self._items[index]
            raise IndexError(f"🚫 Index {index} out of range!")
        
        raise TypeError(f"🚫 Invalid index type: {type(index)}")
    
    def __setitem__(self, index, value):
        # ✨ Allow item modification
        if isinstance(index, int):
            if index < 0:
                index += len(self)
            if 0 <= index < len(self):
                self._items[index] = value
                return
        raise IndexError(f"🚫 Cannot set index {index}")
    
    def __repr__(self):
        # 🎨 Pretty representation
        return f"SmartList({self._items})"

# 🪄 Using the smart list
smart = SmartList(['Python', 'is', 'awesome', '!'])
print(f"Last item: {smart[-1]}")  # Negative indexing!
print(f"Slice: {smart[1:3]}")     # Slicing support!
smart[-1] = '🚀'                   # Modify with negative index
print(f"Modified: {smart._items}")

🏗️ Advanced Topic 2: Lazy Evaluation Container

For the brave developers:

# 🚀 Container with lazy evaluation
class FibonacciSequence:
    def __init__(self, max_items=None):
        self.max_items = max_items
        self._cache = [0, 1]  # 💾 Cache computed values
    
    def __len__(self):
        # 📏 Return max items or infinity indicator
        if self.max_items is None:
            return float('inf')
        return self.max_items
    
    def __getitem__(self, index):
        # 🎯 Compute Fibonacci numbers on demand
        if isinstance(index, slice):
            # 🎨 Handle slicing
            start = index.start or 0
            stop = index.stop
            if stop is None:
                raise ValueError("🚫 Need a stop value for slicing!")
            return [self[i] for i in range(start, stop)]
        
        if index < 0:
            raise IndexError("🚫 Negative indices not supported")
        
        # 💡 Extend cache if needed
        while len(self._cache) <= index:
            self._cache.append(
                self._cache[-1] + self._cache[-2]
            )
        
        return self._cache[index]
    
    def __iter__(self):
        # 🔄 Iterate up to max_items
        for i in range(len(self)):
            yield self[i]

# 🎮 Infinite Fibonacci sequence!
fib = FibonacciSequence()
print(f"10th Fibonacci: {fib[10]}")
print(f"Slice [5:10]: {fib[5:10]}")

# 🎯 Limited sequence
fib_limited = FibonacciSequence(max_items=10)
print(f"\nFirst 10 Fibonacci numbers:")
for i, num in enumerate(fib_limited):
    print(f"  F({i}) = {num}")

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Forgetting Index Validation

# ❌ Wrong way - no bounds checking!
class UnsafeContainer:
    def __init__(self):
        self.items = [1, 2, 3]
    
    def __getitem__(self, index):
        return self.items[index]  # 💥 Will crash on bad index!

# ✅ Correct way - validate your indices!
class SafeContainer:
    def __init__(self):
        self.items = [1, 2, 3]
    
    def __len__(self):
        return len(self.items)
    
    def __getitem__(self, index):
        # 🛡️ Proper validation
        if not isinstance(index, int):
            raise TypeError(f"🚫 Index must be integer, not {type(index).__name__}")
        
        # 🎯 Handle negative indices
        if index < 0:
            index += len(self)
        
        # ✅ Bounds checking
        if 0 <= index < len(self):
            return self.items[index]
        raise IndexError(f"🚫 Index {index} out of range!")

🤯 Pitfall 2: Inconsistent Length

# ❌ Dangerous - len doesn't match actual items!
class ConfusingContainer:
    def __init__(self):
        self.items = [1, 2, 3]
    
    def __len__(self):
        return 10  # 💥 Lies about length!
    
    def __getitem__(self, index):
        return self.items[index]

# ✅ Safe - length matches reality!
class HonestContainer:
    def __init__(self):
        self.items = [1, 2, 3]
        self._virtual_size = 10  # 📏 Track separately if needed
    
    def __len__(self):
        return len(self.items)  # ✅ Always return true length
    
    def __getitem__(self, index):
        if 0 <= index < len(self):
            return self.items[index]
        elif index < self._virtual_size:
            return None  # 🎯 Return placeholder for virtual items
        raise IndexError(f"🚫 Index out of range!")

🛠️ Best Practices

1. 🎯 Always Implement __len__: If you have __getitem__, add __len__ too!
2. 📝 Validate Inputs: Check index types and ranges
3. 🛡️ Handle Edge Cases: Negative indices, slices, and special values
4. 🎨 Be Consistent: Your container should behave predictably
5. ✨ Consider Iterator Protocol: Add __iter__ for enhanced functionality

🧪 Hands-On Exercise

🎯 Challenge: Build a Matrix Container

Create a 2D matrix class that supports the container protocol:

📋 Requirements:

• ✅ Support 2D indexing with tuples: matrix[row, col]
• 🏷️ Implement len() to return total elements
• 👤 Add row and column access: matrix[0] gets first row
• 📅 Support slicing for submatrices
• 🎨 Pretty print the matrix

🚀 Bonus Points:

• Add matrix multiplication support
• Implement transpose operation
• Create addition and subtraction operators

💡 Solution

# 🎯 Our 2D Matrix container!
class Matrix:
    def __init__(self, data):
        # 📊 Initialize with 2D list
        if not data or not all(len(row) == len(data[0]) for row in data):
            raise ValueError("🚫 Invalid matrix data!")
        self.data = data
        self.rows = len(data)
        self.cols = len(data[0]) if data else 0
    
    def __len__(self):
        # 📏 Total number of elements
        return self.rows * self.cols
    
    def __getitem__(self, key):
        # 🎯 Support various indexing styles
        if isinstance(key, tuple):
            # 📍 2D indexing: matrix[row, col]
            row, col = key
            if 0 <= row < self.rows and 0 <= col < self.cols:
                return self.data[row][col]
            raise IndexError(f"🚫 Index {key} out of bounds!")
        
        elif isinstance(key, int):
            # 🔄 Get entire row
            if 0 <= key < self.rows:
                return self.data[key]
            raise IndexError(f"🚫 Row {key} out of bounds!")
        
        elif isinstance(key, slice):
            # 🎨 Return submatrix
            return Matrix(self.data[key])
        
        raise TypeError(f"🚫 Invalid index type: {type(key)}")
    
    def __setitem__(self, key, value):
        # ✏️ Allow modification
        if isinstance(key, tuple):
            row, col = key
            if 0 <= row < self.rows and 0 <= col < self.cols:
                self.data[row][col] = value
                return
        raise IndexError(f"🚫 Cannot set at {key}")
    
    def __str__(self):
        # 🎨 Pretty print
        result = "Matrix(\n"
        for row in self.data:
            result += f"  {row}\n"
        result += ")"
        return result
    
    def transpose(self):
        # 🔄 Return transposed matrix
        transposed = [[self.data[i][j] for i in range(self.rows)] 
                      for j in range(self.cols)]
        return Matrix(transposed)
    
    def __add__(self, other):
        # ➕ Matrix addition
        if not isinstance(other, Matrix):
            raise TypeError("🚫 Can only add matrices!")
        if self.rows != other.rows or self.cols != other.cols:
            raise ValueError("🚫 Matrix dimensions must match!")
        
        result = [[self.data[i][j] + other.data[i][j] 
                   for j in range(self.cols)] 
                  for i in range(self.rows)]
        return Matrix(result)
    
    def shape(self):
        # 📐 Return matrix dimensions
        return (self.rows, self.cols)

# 🎮 Test it out!
# Create a 3x3 matrix
matrix = Matrix([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
])

print(f"📊 Matrix has {len(matrix)} elements")
print(f"📐 Shape: {matrix.shape()}")
print(f"\n🎯 Element at [1, 2]: {matrix[1, 2]}")
print(f"🔄 First row: {matrix[0]}")

# Modify element
matrix[0, 0] = 99
print(f"\n✏️ After modification:")
print(matrix)

# Create another matrix and add
matrix2 = Matrix([
    [9, 8, 7],
    [6, 5, 4],
    [3, 2, 1]
])

result = matrix + matrix2
print(f"\n➕ Addition result:")
print(result)

# Transpose
transposed = matrix.transpose()
print(f"\n🔄 Transposed:")
print(transposed)

🎓 Key Takeaways

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

• ✅ Implement __len__ and __getitem__ to create container objects 💪
• ✅ Support advanced indexing including negative indices and slicing 🛡️
• ✅ Build custom collections that integrate with Python’s built-ins 🎯
• ✅ Handle edge cases and validate inputs properly 🐛
• ✅ Create powerful data structures that feel natural to use! 🚀

Remember: The container protocol makes your objects feel like native Python containers. It’s a powerful way to create intuitive, Pythonic interfaces! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered the container protocol with __len__ and __getitem__!

Here’s what to do next:

1. 💻 Practice with the matrix exercise above
2. 🏗️ Add __setitem__ and __delitem__ to your containers
3. 📚 Explore the iterator protocol with __iter__ and __next__
4. 🌟 Build a custom collection for your next project!

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

Happy coding! 🎉🚀✨