Python typing gotchas: destructuring generic dataclasses in comprehensions, type checker-friendly alternatives

Discover why tuple-like destructuring of generic dataclasses in Python comprehensions confuses type checkers, plus practical, type-safe alternatives today.

Destructuring custom dataclasses in comprehensions feels natural when you want concise code, but it can clash with what Python’s type system can express and what type checkers can infer. Below is a practical walkthrough of why unpacking a generic dataclass like a tuple doesn’t propagate types in comprehensions, what actually works, and what to use instead.

Problem setup

Suppose you model a pair of values as a generic dataclass: a filesystem path and a config object. You’d like to iterate a list of such pairs and destructure each item directly in a list comprehension.

import pathlib
from typing import TypeVar, Generic
from dataclasses import dataclass, astuple
class BaseCfg:
    pass
U = TypeVar("U", bound=BaseCfg)
@dataclass
class PathWithCfg(Generic[U]):
    location: pathlib.Path
    payload: U
items: list[PathWithCfg[MyConfig]] = ...
labels = [p.name for p, conf in items]

The comprehension above aims to unpack each object into a path and a config. To enable iteration-based unpacking, you might try making the dataclass iterable:

from dataclasses import dataclass, astuple
@dataclass
class PathWithCfg(Generic[U]):
    location: pathlib.Path
    payload: U
    def __iter__(self):
        return iter(astuple(self))

At runtime this works. The stumbling block is static typing: a type checker like Pyright won’t know that the first unpacked value is pathlib.Path and the second is MyConfig. With NamedTuple, destructuring is well understood by type checkers, but NamedTuple doesn’t mix with multiple inheritance and doesn’t support the generic pattern you want here.

Why type inference doesn’t follow unpacking here

Tuple-like destructuring in type checkers is special-cased for actual tuples (and NamedTuple). The Python type system doesn’t have a way to express that an arbitrary user-defined class’s __iter__ yields a fixed, positionally-typed pair bound to the class’s generic parameter in a way that comprehensions can unpack and type-check like tuples. In other words, the typing rules aren’t rich enough to infer that p is a pathlib.Path and conf is a MyConfig when you unpack a custom class in a comprehension. That’s why the example above leaves p and conf as unknowns from the type checker’s point of view.

An explicit tuple helper: works, but verbose

One approach is to return a real typed tuple explicitly. That gives type checkers exactly what they expect, at the expense of verbosity and an extra pass in the comprehension:

from typing import Tuple
@dataclass
class PathWithCfg(Generic[U]):
    location: pathlib.Path
    payload: U
    def as_pair(self) -> Tuple[pathlib.Path, U]:
        return self.location, self.payload
labels2 = [p.name for p, conf in [obj.as_pair() for obj in items]]

This propagates types correctly, but it’s clunky and iterates twice.

A pattern type checkers understand: match on attributes

Dataclasses can be structurally matched by attributes using a match block (Python 3.10+). Type checkers understand this pattern and bind names with precise types. For illustration (using a generic dataclass and mypy’s reveal_type):

from dataclasses import dataclass
from typing import Generic, TypeVar
V = TypeVar("V")
@dataclass
class Bar(Generic[V]):
    a: int
    b: V
bar = Bar[float](1, 2.0)
match bar:
    case object(a=a, b=b):
        reveal_type(a)  # Revealed type is "builtins.int"
        reveal_type(b)  # Revealed type is "builtins.float"
        assert a + b == 3
    case _:
        raise RuntimeError("unreachable")

The key idea is that matching object(a=..., b=...) assigns a and b with the known field types. This achieves the desired type propagation for dataclasses. The catch is that match is a statement, not an expression, so it can’t live inside a list comprehension.

Practical workarounds

If you want types to flow cleanly without extra ceremony, the simplest option is to avoid destructuring and access attributes directly in the comprehension. This keeps one pass, reads well, and is friendly to type checkers:

labels = [entry.location.name for entry in items]

When you do want names bound to individual components with precise types, use a match block to pull out attributes, do the typed work inside that block, and collect results in a subsequent step. If you absolutely need tuple semantics, returning a real tuple via a helper like as_pair provides explicit typing at the cost of verbosity.

Why this matters

Mixing Python’s flexible destructuring with static typing can be subtle. Relying on custom __iter__ to “feel tuple-like” doesn’t help a type checker, while tuples and NamedTuple are special. Understanding the boundary keeps code readable without fighting the toolchain: use attribute access in expressions and pattern matching in statements to get predictable, accurate types.

Takeaways

Don’t expect comprehension-time destructuring of custom classes to carry types the way tuples do; the typing rules don’t model that. Use attribute access in comprehensions for clarity and performance. When you need names bound with proper types, reach for a match block over your dataclass. If you prefer tuple-style APIs, return an actual typed tuple from a helper method, knowing it’s more verbose.