A payroll CSV importer dispatches on typing.get_origin; why do Annotated columns fall through?

### What Annotated does to the object graph `typing.Annotated[X, *metadata]` exists so a declaration can carry information that the type checker ignores and your runtime code reads: a column name, a unit, a validation bound. Crucially it does not replace `X` — it wraps it. The resulting alias is a wrapper whose payload is `X` plus the metadata objects, and it sits *outside* whatever `X` was. So a payroll importer that declares a column as `Annotated[list[Decimal], 'column=gross_pay']` has a two-layer annotation: an `Annotated` wrapper on the outside, a `list[Decimal]` alias inside. Introspection reports the outermost layer, which is exactly why the dispatcher misses: ```python from typing import Annotated, get_args, get_origin GrossPay = Annotated[list[Decimal], 'column=gross_pay'] get_origin(GrossPay) # typing.Annotated -- not list get_args(GrossPay) # (list[Decimal], 'column=gross_pay') ``` Two branches break at once. The container branch (`origin is list`) never fires, because the origin is the wrapper. And the scalar branch, if it is written as `origin is None`, never fires for `Annotated[Decimal, 'net_pay']` either — that also reports `Annotated`, even though the thing being annotated is a plain class. So annotated columns fall past every case and land in whatever the function does with unknown shapes, which is usually a raise or, worse, a silent skip that leaves the field unset. ### The strip step The repair is small and belongs at the top of the dispatch function: ```python def strip_metadata(ann): while get_origin(ann) is Annotated: ann = get_args(ann)[0] return ann ``` The wrapped type is always argument zero; everything after it is metadata, in the order written. A `while` rather than an `if` costs nothing and is honest about the fact that you did not build the annotation and cannot promise how it was nested. ### Why the strip must happen at every level The subtle failure is stripping once, at the entry point, and assuming the rest of the tree is clean. Metadata can be attached anywhere: `list[Annotated[Decimal, 'gross_pay']]` reports origin `list` — no wrapper at the top at all — and only when the converter recurses into the element type does it meet the `Annotated`. If your recursion calls the strip on entry to each level, both shapes work; if it strips only at the top, the inner one raises when it tries to call an alias as a constructor. Test both nestings; a real declaration file will contain both within a week of anyone else using it. ### Nesting and flattening Direct nesting flattens: `Annotated[Annotated[int, 'a'], 'b']` normalizes at construction to a single wrapper carrying both metadata objects, so `get_args` returns `(int, 'a', 'b')`. That is convenient — one strip clears direct nesting — but it does not save you from the element-level case above, which is not direct nesting. Two other details matter in real code: `Annotated` requires at least one metadata argument, so there is no zero-metadata edge case to handle; and metadata objects are arbitrary values compared by equality, so two annotations with equal metadata are equal annotations, which is what lets you use them as registry keys. ### Reading the metadata you stripped Stripping throws the metadata away, and usually you want it — that is why the column was annotated. Take both in one pass: call `get_args` once, keep index 0 as the type and the remaining elements as the metadata, and hand the metadata to whatever decides the CSV header name or the rounding rule. Filter the metadata by `isinstance` against your own marker classes rather than by position; other libraries and other teams add their own objects to the same annotation, and positional assumptions break the moment a second consumer appears. ### Where this bites in an importer specifically A CSV importer takes strings and must decide what to construct: `Decimal` for money, `int` for hours, a list for a semicolon-joined multi-value column. All of that decision-making is origin dispatch, so every declaration style your team uses has to survive it. Annotated columns are the ones people add later — when someone needs a header alias or a currency tag — which is why the failure shows up in production against a file that used to import fine, rather than in the test that was written with plain annotations. ### Versions `typing.Annotated` is 3.9 and later (PEP 593); on 3.8 it lived in a third-party backport. `get_origin` reporting `Annotated` for a wrapped alias has been the behaviour since it was introduced and is unchanged on 3.14.