How do you write a `__repr__` that stays useful in production logs and debuggers?

Take a concrete setting: a video-metadata extractor maintained by a four-person team, running as a long-lived worker. Every object it handles ends up in a log line or in a debugger session eventually, and the only thing standing between an engineer and the truth about that object is its `__repr__`. Designing that method is a production concern, not a formatting nicety. ## Rule one: it must be honest about what it hides The failure that teaches this is a silent truncation. Someone writes a repr that shows the first six decoded frames because the full list is enormous, and it reads `Extracted(frames=[0, 1, 2, 3, 4, 5, ...])`. Months later a batch produces short clips, an engineer sees a similar-looking line, and concludes the extractor is dropping frames — the truncation and the real defect are indistinguishable in the log. - The fix is one field: print the true count next to the sample, `frame_count=4800, sample=[0, 1, 2, 3, 4, 5, ...]`. - `reprlib.repr` gives you the bounded rendering with sensible limits, and `reprlib.Repr` lets you configure them, but the count is yours to add. A repr that abbreviates must say that it abbreviated and by how much. ## Rule two: it must be cheap A debugger evaluates the repr of every object in scope, on every step. A watch expression does it repeatedly. Logging does it once per record, sometimes at a high rate. So a `__repr__` that opens a file, queries a database, triggers a lazy load or computes a hash over a large buffer converts debugging from a diagnostic activity into a source of load — and worse, changes the behaviour of the program you are inspecting. If a value is expensive, show a cheap proxy: a length, an id, a state flag. ## Rule three: it must not raise Reprs are called on objects in states you never designed for: - a half-constructed instance whose `__init__` blew up mid-way, - an object being reported inside an exception handler, - an object resurrected from a pickle with fields missing. If `__repr__` raises, the error message you needed is replaced by a second, unrelated traceback, and the original context is lost. Read anything uncertain with `getattr(self, 'field', '<unset>')`. For self-referential structures, decorate with `reprlib.recursive_repr()`, which substitutes `...` when the same object is re-entered — the same trick the built-in containers use on themselves. ## Rule four: it must not leak Whatever the repr contains goes into logs, crash reports, and any error-tracking pipeline you have. Tokens, passwords, connection strings with embedded credentials and personal data all belong behind an explicit `<redacted>` placeholder. Putting the redaction in `__repr__` is stronger than a logging filter, because it protects every path that renders the object, including ones added later by someone who never read the filter config. ## Rule five: it should carry identity plus a few stable fields - The useful content is the class name — use `type(self).__name__` so subclasses do not lie about themselves — then the fields that let you tell this instance apart from its neighbours: the input path, an id, a status, a size. - Render each with `!r` so strings are quoted. - Keep the whole thing on one line; a repr that wraps is unreadable in a grepped log. Anything larger belongs in an explicit diagnostic method the caller opts into, not in the repr that fires automatically. ## Rule six: treat it as a shared convention With four people on a service, the value of reprs comes from their consistency: same shape, same field ordering, same redaction marker, same abbreviation style. That is worth a short written rule and a review habit, because the payoff is collective — one person's incident is read using everyone else's reprs. - Choose the reconstructible `Class(field=value)` form for value objects, - and the `<Class state>` angle-bracket form for objects holding live resources, so the shape itself tells a reader whether the text could be evaluated. Finally, keep the repr stable over time: people learn to scan for a familiar shape, and changing the field order or names quietly invalidates saved log queries and every incident runbook that quotes one.