Python Standard Library: collections for Advanced Data Structures

Best Practices and Common Patterns

To get the most out of the collections module, keep these best practices in mind:

General Best Practices

• Choose the right collection for the job - Each specialized collection is optimized for specific use cases. Matching your needs to the right tool will lead to cleaner, more efficient code.
• Import only what you need - Use from collections import X to import only the specific collections you're using, rather than the entire module.
• Consider readability - Sometimes using a more specialized collection can make your code more self-documenting.
• Be aware of performance characteristics - Different collections have different performance profiles; choose accordingly.

Common Patterns by Collection Type

namedtuple

• Data transfer objects - Use namedtuples to pass grouped data between functions.
• Lightweight data classes - For simple cases that don't need mutability, use namedtuples instead of full classes.
• CSV or database rows - Represent records with meaningful field names.
• Multiple return values - Return a namedtuple instead of a plain tuple for clarity.

def get_stats(numbers):
    """Return statistics about a sequence of numbers."""
    from collections import namedtuple
    
    Stats = namedtuple('Stats', ['min', 'max', 'mean', 'median', 'count'])
    
    count = len(numbers)
    if count == 0:
        return Stats(None, None, None, None, 0)
    
    # Calculate statistics
    min_val = min(numbers)
    max_val = max(numbers)
    mean = sum(numbers) / count
    
    # Sort numbers to find median
    sorted_nums = sorted(numbers)
    mid = count // 2
    if count % 2 == 0:
        median = (sorted_nums[mid-1] + sorted_nums[mid]) / 2
    else:
        median = sorted_nums[mid]
    
    return Stats(min_val, max_val, mean, median, count)

# Usage
data = [5, 10, 3, 8, 15, 7]
stats = get_stats(data)

# Access by name
print(f"Mean: {stats.mean}, Median: {stats.median}")

# Unpack
min_val, max_val, mean, median, count = stats
print(f"Range: {min_val} to {max_val}")
            

deque

• Sliding window analysis - Use a deque with maxlen for a fixed-size sliding window.
• Buffer management - Implement circular buffers.
• Breadth-first search - Use a deque as an efficient queue.
• History tracking - Track the last n events or log entries.

def breadth_first_search(graph, start):
    """Perform breadth-first search on a graph."""
    from collections import deque
    
    # Initialize queue and visited set
    queue = deque([start])
    visited = {start}
    
    # Track the order of nodes visited
    bfs_order = []
    
    while queue:
        # Dequeue a vertex from the queue
        vertex = queue.popleft()
        bfs_order.append(vertex)
        
        # Process neighbors
        for neighbor in graph[vertex]:
            if neighbor not in visited:
                visited.add(neighbor)
                queue.append(neighbor)
    
    return bfs_order

# Example graph (adjacency list)
graph = {
    'A': ['B', 'C'],
    'B': ['A', 'D', 'E'],
    'C': ['A', 'F'],
    'D': ['B'],
    'E': ['B', 'F'],
    'F': ['C', 'E']
}

print(breadth_first_search(graph, 'A'))  # ['A', 'B', 'C', 'D', 'E', 'F']
            

Counter

• Frequency analysis - Count occurrences of elements.
• Finding most common elements - Use most_common() for rank-ordered results.
• Set-like operations - Use Counter's arithmetic operations for multisets.
• Data normalization - Convert raw counts to frequency distributions.

def analyze_text(text):
    """Analyze word frequencies in text."""
    from collections import Counter
    import re
    
    # Normalize text and split into words
    words = re.findall(r'\b\w+\b', text.lower())
    
    # Count word frequencies
    word_counts = Counter(words)
    
    # Get total word count
    total_words = sum(word_counts.values())
    
    # Calculate word frequency distribution (as percentage)
    frequency = {word: (count / total_words) * 100 
                for word, count in word_counts.items()}
    
    return {
        'total_words': total_words,
        'unique_words': len(word_counts),
        'most_common': word_counts.most_common(5),
        'frequency': {w: f for w, f in sorted(
            frequency.items(), key=lambda x: x[1], reverse=True)[:5]}
    }

# Example text
sample_text = """
To be, or not to be, that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles
"""

analysis = analyze_text(sample_text)
print(f"Total words: {analysis['total_words']}")
print(f"Unique words: {analysis['unique_words']}")
print("\nMost common words:")
for word, count in analysis['most_common']:
    print(f"  {word}: {count}")
print("\nFrequency distribution:")
for word, freq in analysis['frequency'].items():
    print(f"  {word}: {freq:.2f}%")
            

defaultdict

• Multi-level grouping - Create nested defaultdicts for hierarchical data.
• Sparse data structures - Handle missing values elegantly.
• Building adjacency lists - Represent graphs without explicit key checking.
• Counting with defaults - Combine with int factory for simple counting.

def build_index(documents):
    """Build an inverted index from documents."""
    from collections import defaultdict
    
    # Create a defaultdict of sets
    index = defaultdict(set)
    
    for doc_id, document in enumerate(documents):
        # Normalize and split into words
        words = document.lower().split()
        
        # Add document ID to the set for each word
        for word in words:
            index[word].add(doc_id)
    
    return index

def search(index, query):
    """Search the index for documents matching all query terms."""
    # Normalize and split query
    terms = query.lower().split()
    
    if not terms:
        return set()
    
    # Start with all documents containing the first term
    result = index.get(terms[0], set())
    
    # Intersect with documents containing each additional term
    for term in terms[1:]:
        result &= index.get(term, set())
    
    return result

# Example documents
docs = [
    "the quick brown fox jumps over the lazy dog",
    "the five boxing wizards jump quickly",
    "pack my box with five dozen liquor jugs",
    "how vexingly quick daft zebras jump"
]

# Build the index
inverted_index = build_index(docs)

# Search for documents containing terms
query = "quick jump"
matching_docs = search(inverted_index, query)

print(f"Documents matching '{query}':")
for doc_id in matching_docs:
    print(f"  {doc_id}: {docs[doc_id]}")
            

ChainMap

• Configuration systems - Layer multiple configuration sources.
• Scope management - Simulate nested scopes in interpreters or template engines.
• Override systems - Provide default values with ability to override.
• Template contexts - Build context hierarchies for template rendering.

def render_template(template, **kwargs):
    """
    Simple template renderer that supports variable substitution.
    
    Variables are enclosed in double curly braces: {{variable_name}}
    """
    from collections import ChainMap
    import re
    
    # Create a context with built-ins and user-provided variables
    builtins = {
        'current_year': 2025,
        'app_name': 'MyApp',
        'version': '1.0',
    }
    
    context = ChainMap(kwargs, builtins)
    
    # Find all variables in the template
    def replace_var(match):
        var_name = match.group(1).strip()
        return str(context.get(var_name, f"{{{{ {var_name} }}}}"))
    
    # Replace all variables with their values
    return re.sub(r'{{\s*(.+?)\s*}}', replace_var, template)

# Example usage
template = """
Welcome to {{app_name}} v{{version}}!

Hello, {{user_name}}!

Today is {{current_day}}, {{current_year}}.
"""

rendered = render_template(
    template,
    user_name="Alice",
    current_day="Saturday"
)

print(rendered)