Why does a serializer built on vars(obj) drop fields that dir(obj) lists?

## Three things that look like the same question `obj.__dict__`, `vars(obj)` and `dir(obj)` are routinely treated as three ways to ask "what attributes does this object have". They answer three different questions, and a serializer that picks the wrong one loses data quietly. **`obj.__dict__`** is the instance's own attribute mapping — the names this particular object stored, mapping to their values. It is a real `dict`: mutable, insertion-ordered (a language guarantee since 3.7), and *live*, so writing into it writes to the object. **`vars(obj)`** is the builtin spelling of exactly that; it returns the same object, not a copy. Called with no argument it returns `locals()` instead. Called on a class it returns a `mappingproxy` — read-only, and containing only that class's own namespace, not anything inherited. **`dir(obj)`** is a *name* query, not a value query. It gathers the instance's own names plus every name reachable through the type's method resolution order, deduplicates, **sorts alphabetically**, and returns a `list[str]`. A type may define its own name list, in which case `dir()` returns whatever that says, sorted — which is why the documentation describes the result as an interactive convenience rather than an authoritative inventory. ## What a vars()-driven serializer misses Walk `vars(obj)` and every one of these vanishes from the output: - **class attributes** — a default such as `kind = "message"` that no instance ever assigned; - **computed attributes** — anything backed by a `property` or another descriptor, since the value is produced on access and was never stored in the instance; - **slot fields** — a class with `__slots__` has no instance `__dict__`, so `vars()` raises `TypeError: vars() argument must have __dict__ attribute` rather than returning an empty mapping; - **inherited stored state** written by a base class only when some branch ran. And it *gains* things you may not want: private bookkeeping, caches, and any attribute a library set on the instance behind your back. ## The ordering trap Here is the failure that is easy to reproduce and easy to miss. A chat-transcript archiver walks each message object and emits one record per message; the run takes about six hours nightly and its output is checksummed downstream to detect re-emitted days. ```python class Row: kind = "message" def __init__(self): self.ts = 1 self.user = "al" self.body = "hi" @property def day(self): return self.ts // 86400 r = Row() list(vars(r)) # ['ts', 'user', 'body'] -> assignment order [n for n in dir(r) if not n.startswith("_")] # ['body', 'day', 'kind', 'ts', 'user'] -> alphabetical, plus class attr and property ``` Swapping one builtin for the other to "also capture the computed fields" changes the key order of every record in the archive. Nothing raises. The nightly run completes, and the downstream checksum declares six hours of correctly-archived transcripts to be different from the previous run's. The lesson generalises: **`vars()` order is the object's assignment history and `dir()` order is the alphabet**, and neither is a contract you should be encoding into an output format at all. ## Doing it deliberately The reliable pattern is to stop asking the object what it has and start telling it what to emit. - If the class is a dataclass, `dataclasses.fields` gives the declared field order, and `dataclasses.asdict` produces a record from it. - If it is not, an explicit tuple of field names on the class — the same list you would have written into `__slots__` — is both the schema and the order, and it fails loudly when a field is renamed. - Where reflection genuinely is the point (a generic debugging dump, an object browser), `inspect.getmembers` walks names and *values* together and takes a predicate, which is closer to what a dump wants than `dir()` plus a loop of `getattr` calls. - To include computed attributes you must actually evaluate them, which means running user code per field, which means deciding what happens when one of them raises. That decision is the real work; choosing between `vars()` and `dir()` is not. ## Two mechanical details worth having ready First, `vars(obj)` hands back the object's live mapping, so mutating the returned dict mutates the object — convenient, and a genuine hazard if you pass it to code that normalises in place. On CPython 3.11 and later instance attributes are stored inline and the `__dict__` object is materialised on demand, so touching `vars(obj)` in a hot loop is not the free read it looks like. Second, `dir()` deliberately omits nothing on grounds of privacy — dunder and underscore-prefixed names come back too, which is why every real use filters them, and why filtering by a leading underscore is a convention rather than a guarantee that the remainder is your public surface.