`NamedTuple` vs. `@dataclass`: Choosing the Right Data Structure

What is typing.NamedTuple?

Before we compare, let's establish what a NamedTuple is. It's a data structure that combines the memory efficiency and immutability of a tuple with the readability of a class. It allows you to access elements by name (like point.x) instead of only by index (point[0]), without the overhead of a full class object.

The modern way to define one is by using typing.NamedTuple.

from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float




# Instantiation is like a class
p1 = Point(10.0, 20.5)




# Access attributes by name
print(f"Coordinates: ({p1.x}, {p1.y})")




# It's still a tuple, so you can unpack it
x_coord, y_coord = p1
print(f"Unpacked: x={x_coord}, y={y_coord}")




# And access by index
print(f"Access by index: p1[0] = {p1[0]}")




# It's immutable
try:
    p1.x = 15.0
except AttributeError as e:
    print(f"Error on modification: {e}")

Notice the key characteristics: it's created like a class, provides named access, but fundamentally behaves like an immutable tuple.

NamedTuple vs. @dataclass: The Core Trade-offs

The choice between NamedTuple and @dataclass is a classic Python design decision. It's not about which is "better" overall, but which is optimal for a specific task. Let's break down the comparison.

The article you just read provides a detailed analysis. Let's synthesize its findings and add more context in a direct comparison table.

To see a visual breakdown of the performance and memory differences, the following video provides clear benchmarks.

A Clear Decision Framework

Based on these trade-offs, we can establish a straightforward decision-making process.

When to use typing.NamedTuple

Choose NamedTuple when your primary goal is to create a simple, immutable record type. It's the perfect choice if all of the following are true:

• The object will never be modified after creation.
• The object will not have any custom behavior (i.e., no methods).
• Memory efficiency and creation speed are important (e.g., creating millions of instances to parse a large file).
• You want the object to behave like a tuple (e.g., for easy unpacking).

A classic use case is returning multiple, well-defined values from a function, where a plain tuple would be ambiguous.

# Good: NamedTuple for a simple, immutable return value
class ParseResult(NamedTuple):
    record_id: int
    status: str
    data: dict

def parse_log_line(line: str) -> ParseResult:



    # ... parsing logic ...
    return ParseResult(record_id=123, status="OK", data={"user": "admin"})

When to use @dataclass

Choose @dataclass when you need more than just a simple data record. It's the right tool if any of the following apply:

• The object's state might need to change after creation (mutability is required).
• The object needs to have custom methods or logic associated with its data.
• You need advanced features like default values for mutable fields (default_factory) or post-creation validation (__post_init__).
• You plan to use inheritance to build more complex objects.

The Special Case: @dataclass(frozen=True)

What if you need an object that is immutable but also needs custom methods? This is where NamedTuple falls short, and @dataclass(frozen=True) shines.

Consider a Coordinate object. We want it to be immutable, but we also want a handy method to calculate its distance to another point.

from dataclasses import dataclass
import math




# Use @dataclass(frozen=True) for an immutable object with methods.
@dataclass(frozen=True)
class Coordinate:
    lat: float
    lon: float

    def distance_to(self, other: 'Coordinate') -> float:



        # Simplified distance calculation for example purposes
        return math.sqrt((self.lat - other.lat)**2 + (self.lon - other.lon)**2)




# Now we have the best of both worlds:
# 1. Immutability
# 2. Custom behavior
p1 = Coordinate(34.05, -118.24) # Los Angeles
p2 = Coordinate(40.71, -74.00)  # New York

print(f"Distance: {p1.distance_to(p2):.2f} degrees")



# Output: Distance: 44.31 degrees




# It's immutable
try:
    p1.lat = 0
except Exception as e:
    print(f"Error: {e.__class__.__name__}")



    # Output: Error: FrozenInstanceError

This makes @dataclass(frozen=True) the go-to choice for creating value objects that encapsulate both data and related logic in an immutable package.

Exercise: Refactor a Data Structure

Your task is to apply this decision framework. You'll start with one implementation and refactor it as requirements change.

Part 1: Simple, Immutable Log Entries

You are processing firewall logs. Each entry is a simple record of an event that will never change once parsed. You will be holding millions of these in memory for analysis, so memory efficiency is critical.

Task: Implement a LogEntry structure for this purpose. It should contain:

• timestamp: str
• source_ip: str
• event: str

Choose the most appropriate tool (NamedTuple or @dataclass) and implement it.

Part 2: Adding Behavior

New requirements have come in. You now need to add a method to the LogEntry structure called is_suspicious(). This method will return True if the event is 'Port scan detected'. The log entries must remain immutable.

Task: Refactor your LogEntry implementation to accommodate this new requirement. Choose the most appropriate tool for this new scenario.

Provide your code for both parts.

from typing import NamedTuple




# Part 1: Using NamedTuple for a lightweight, immutable record
class LogEntry(NamedTuple):
    timestamp: str
    source_ip: str
    event: str




# Verification
entry1 = LogEntry(
    timestamp="2023-10-27T10:00:00Z",
    source_ip="192.168.1.101",
    event="Login success"
)
print(f"Part 1 - Log Entry: {entry1}")
print(f"Part 1 - Is tuple? {isinstance(entry1, tuple)}")




# It is immutable
try:
    entry1.source_ip = "1.1.1.1"
except AttributeError as e:
    print(f"Part 1 - Caught expected error: {e}")

from dataclasses import dataclass




# Part 2: Refactoring to @dataclass(frozen=True) to add methods
@dataclass(frozen=True)
class LogEntry:
    timestamp: str
    source_ip: str
    event: str

    def is_suspicious(self) -> bool:
        """Returns True if the event indicates a potential threat."""
        return self.event == 'Port scan detected'




# Verification
entry2 = LogEntry(
    timestamp="2023-10-27T10:05:00Z",
    source_ip="10.0.0.5",
    event="Login failed"
)
entry3 = LogEntry(
    timestamp="2023-10-27T10:06:00Z",
    source_ip="203.0.113.12",
    event="Port scan detected"
)

print(f"\nPart 2 - Log Entry 2: {entry2}")
print(f"Part 2 - Is entry 2 suspicious? {entry2.is_suspicious()}") # False

print(f"Part 2 - Log Entry 3: {entry3}")
print(f"Part 2 - Is entry 3 suspicious? {entry3.is_suspicious()}") # True




# It remains immutable
try:
    entry3.event = "Something else"
except Exception as e:
    print(f"Part 2 - Caught expected error: {e.__class__.__name__}")

Conclusion

You have now analyzed the key differences between typing.NamedTuple and @dataclass and have a clear framework for choosing between them. This is a fundamental skill for designing clean and efficient Python applications.

Key Takeaways:

• typing.NamedTuple is for simple, immutable data records. Choose it for its low memory footprint and speed when you don't need custom methods. It's perfect for public APIs that return structured, tuple-like data.
• @dataclass is for flexible objects that may have state and behavior. Choose it when you need mutability, custom methods, inheritance, or advanced features like __post_init__.
• @dataclass(frozen=True) fills the gap for immutable objects that require behavior. It provides the data integrity of NamedTuple with the flexibility of a full class.

In the next lesson, we will explore another way to handle structured data: modern dictionary idioms. While NamedTuple and @dataclass provide formal structure, dictionaries offer a more dynamic and flexible approach. You will learn idiomatic patterns for accessing, manipulating, and merging dictionaries safely and efficiently.