What does typing.ClassVar mean in a class body, and how does @dataclass treat it?

## Class attribute versus instance attribute Python has always distinguished the two: a name assigned in a class body lives on the class object and is found through every instance by attribute lookup, while a name assigned to `self` lives in that instance's own namespace. Nothing in the syntax distinguishes the *intent*, though — `registry = {}` in a class body might be a genuine class-level table or an accidentally shared default someone meant to be per-instance. `typing.ClassVar` makes the intent explicit and machine-checkable: ```python from typing import ClassVar class ContigRecord: seen: ClassVar[dict[str, int]] = {} # one dict for the whole class name: str # one per instance ``` A checker then enforces two things: the attribute may not be assigned through an instance (`record.seen = {}` and `self.seen = {}` are both errors), and it may not be overridden as an instance attribute in a subclass. Reading it through an instance stays perfectly fine, because ordinary attribute lookup falls back to the class. `ClassVar` is only meaningful in a class body. It is not allowed as a parameter annotation, a return annotation, or nested inside another type such as `list[ClassVar[int]]`, and the typing spec says it should not be combined with `Final`. As always, the interpreter does not police any of this — it builds the annotation object regardless, and only the checker objects. ## What `@dataclass` does with it This is where `ClassVar` stops being purely advisory and starts changing behaviour. The `dataclasses` decorator walks the class body's annotations to decide what counts as a *field*. Any name annotated `ClassVar[...]` is skipped: ```python from dataclasses import dataclass, field, fields from typing import ClassVar @dataclass class ContigRecord: name: str bases: int = 0 seen: ClassVar[dict[str, int]] = {} tags: list[str] = field(default_factory=list) [f.name for f in fields(ContigRecord)] # ['name', 'bases', 'tags'] ``` `seen` takes no `__init__` parameter, appears in no generated `__repr__`, is not compared by the generated `__eq__`, and is missing from `fields()`. It stays exactly what it was: a plain class attribute you set once in the class body and read through the class or any instance. The same skipping rule applies to `dataclasses.InitVar`, which is the mirror-image case — a value passed to `__init__` that becomes no attribute at all. Because a ClassVar name is not a field, it is also exempt from the guard that makes dataclasses refuse a mutable default. Writing `tags: list[str] = []` raises `ValueError: mutable default ... use default_factory`, but `seen: ClassVar[dict[str, int]] = {}` is accepted without complaint. That asymmetry is correct — a class attribute is *supposed* to be one shared object — but it is easy to read the acceptance as approval and reach for `ClassVar` just to silence the error. ## The shared-state trap Consider a genome-annotation pipeline where each `ContigRecord` is scored by a worker and a class-level `seen` dictionary accumulates per-contig counts so a later stage can compute the 92nd-percentile budget for the run. `ClassVar` is the honest annotation for that dictionary — it truly is one table for the whole class — but naming it correctly does not make it safe. Every instance, every module that imports the class, and every worker thread in the process mutates the same object; two workers updating the same key are a race on shared state, and a checker will not say a word. The annotation documents the sharing; it does not manage it. If a value should be per-instance, make it a real field with a `default_factory`. If it is genuinely global mutable state, give it a lock, or push it out of the class into something built for concurrent accumulation. A second, milder trap: a class-level mutable default survives for the process's lifetime, which in a long-running service means unbounded growth. The same annotation that documents the sharing should prompt the question "who empties this?" ## Reading it back `typing.get_type_hints()` and, on 3.14, `annotationlib.get_annotations()` return the annotation object, so `ClassVar[dict[str, int]]` is recoverable at runtime — which is exactly how `dataclasses` and the frameworks that build on annotations detect it. The declaration is therefore one of the few typing constructs that has an observable effect on ordinary Python code, and that is the reason it is worth knowing beyond checker-pleasing.