What does annotating a dataclass attribute with dataclasses.InitVar do?

## Pseudo-field, not field A dataclass field is an annotated class-level name that the decorator turns into a constructor parameter *and* an instance attribute. `dataclasses.InitVar[T]` breaks that pairing: the name still becomes a constructor parameter, but no attribute is ever assigned for it. `@dataclass` detects the annotation while it walks the class, records the name as a pseudo-field, and treats it specially everywhere else — it is absent from `dataclasses.fields()`, from the generated `__repr__` and `__eq__`, and from `dataclasses.asdict()`. The only place its value surfaces is `__post_init__`, which receives one positional parameter for each `InitVar`, in the order the annotations appear. ```python from dataclasses import InitVar, dataclass, field, fields @dataclass class Job: doc_id: str raw_pages: InitVar[str] pages: tuple[int, ...] = field(init=False) def __post_init__(self, raw_pages: str) -> None: self.pages = tuple(int(p) for p in raw_pages.split(",")) ``` `Job("doc-27", "1,2,3")` reprs as `Job(doc_id='doc-27', pages=(1, 2, 3))`, and `[f.name for f in fields(job)]` is `['doc_id', 'pages']`. The raw string was an input, not part of the value. ## What it is for Three recurring shapes: 1. **Raw input that is parsed into a real field.** The caller has a string, a path or a blob; the object wants the parsed form. The `InitVar` carries the raw thing in, `__post_init__` parses it into a `field(init=False)`, and the unparsed version never pollutes equality or serialization. 2. **A construction-time flag.** `strict: InitVar[bool] = False` changes how the object validates or derives itself, without becoming state that later code can read and misinterpret. Two objects built with different flags but identical resulting values compare equal — usually exactly what you want. 3. **A collaborator needed only to build.** A clock, a loader or a lookup table passed in so `__post_init__` can resolve something, then dropped instead of being pinned into the instance where the repr would print it and equality would compare it. If you find yourself storing the `InitVar` value on `self` anyway, you did not want an `InitVar`; you wanted an ordinary field. ## Ordering, defaults and typing An `InitVar` occupies a position in the constructor signature exactly where it is declared, so it participates in the usual rule that a parameter without a default cannot follow one with a default. It may carry a default of its own (`verbose: InitVar[bool] = False`), and that default is what `__post_init__` receives when the caller omits it. The subscript is documentation for readers and type checkers — `InitVar[str]` says the parameter is a `str` — and it is not enforced at runtime. The matching parameter in `__post_init__` should be annotated with the *inner* type, `str`, not with `InitVar[str]`. Detection is by annotation, and it is shallower than it looks: the decorator recognizes the `InitVar` marker on the annotation, and when annotations are strings it falls back to matching the written text. Rebinding it under another name and annotating with the alias can therefore leave the decorator treating the name as an ordinary field, which shows up as a surprise attribute and an extra entry in the repr. Write `InitVar[...]` literally. ## Consequences downstream Because an `InitVar` is a constructor parameter with no stored value, anything that rebuilds an instance through `__init__` has to be told what to pass. `dataclasses.replace()` cannot reconstruct one from the existing object — there is nothing to read — so an `InitVar` without a default must be supplied in the call, and omitting it raises `TypeError: InitVar 'raw_pages' must be specified with replace()`. In the other direction, `copy.deepcopy` and `pickle` restore instance state directly instead of calling the constructor, so they never need the `InitVar` at all, and never re-run the parsing that consumed it. Also note the ordinary `typing.ClassVar` annotation for contrast: `ClassVar` excludes a name from the fields *and* from the constructor, marking it as shared class state; `InitVar` excludes it from the fields but keeps it in the constructor. They are the two ways an annotated name in a dataclass body can fail to become a field, and interviewers like the pairing. ## Several InitVars, and inheritance The `__post_init__` signature must match the pseudo-fields exactly: one parameter per `InitVar`, in declaration order, and no more. Get it wrong and the failure is at construction time, not class-creation time — `TypeError: Job.__post_init__() takes 1 positional argument but 2 were given`, raised from inside the generated constructor. That is a mismatch worth checking whenever you add an `InitVar` to a class that already has the hook. Inheritance compounds it. Pseudo-fields are inherited like fields, and the constructor forwards *all* of them, base-declared ones included, to whichever `__post_init__` attribute lookup finds. A subclass that overrides the hook must therefore accept the base's `InitVar` parameters even if it does nothing with them, and pass them along if it calls `super().__post_init__(...)`. This is the practical argument for keeping `InitVar` use shallow: in a hierarchy the constructor-only arguments accumulate into every override's signature.