__repr__ vs __str__

Python gives an object two textual faces because two different audiences read it, and conflating them is what makes objects hard to debug. ## `__repr__` — the developer's view `repr(obj)` calls `type(obj).__repr__`. Its job is to be *unambiguous*: someone reading a log line, a debugger pane or a failing assertion should be able to tell exactly which object this is and what state it holds. The convention has two accepted shapes. - For a value-like object, return something that looks like the constructor call that would rebuild it — `Video(title='intro', seconds=94)` — so that in the simple case `eval(repr(x))` reproduces an equal object. - For an object that cannot be reconstructed from text (an open socket, a thread, a live connection), return the angle-bracket form instead: `<Extractor path='clip.mp4' frames=4800>`. The angle brackets are the standard signal for "this is a description, not an expression". Nothing in the language enforces either shape; they are conventions the whole ecosystem reads. ## `__str__` — the reader's view `str(obj)` calls `type(obj).__str__`, and `print(obj)` calls `str()` on its argument. Its job is *readability* for whoever consumes the program's output: `intro (94s)`, `3.5 MB`, `2026-09-04`. It may drop detail, round numbers, or localise. It has no obligation to be reversible. ## The one-way fallback `object.__str__` — the implementation every class inherits unless it defines its own — simply calls `__repr__`. So a class with only `__repr__` gets a sensible `str()` and prints well. The reverse does not hold: a class with only `__str__` still inherits `object.__repr__`, which produces `<__main__.Bare object at 0x1092f5e80>` — the module-qualified class name plus the memory address. That text distinguishes two instances but tells you nothing about either. This asymmetry is why the advice is always "write `__repr__` first". ## Where each one actually surfaces `__repr__` shows up in more places than beginners expect: - echoing an expression at the interactive prompt, - every element inside a printed list, tuple, set or dict, - the arguments in many library error messages, - a debugger's variables view, - and the `!r` conversion in an f-string. `__str__` shows up in `print()`, in `str()`, and — indirectly — in an f-string with no conversion and no format spec, because the inherited `object.__format__` returns `str(self)` for an empty spec. So `print(v)` and `f"{v}"` agree, while `print([v])` and `f"{v!r}"` show the repr. ## Rules that are actually enforced - Both methods must return a `str`; returning anything else raises `TypeError` at call time, not at class-definition time. - Both are looked up on the type, not on the instance. - Neither should have side effects: they are called by tooling you do not control, at moments you did not choose, sometimes many times per second while someone steps through a debugger. ## Choosing what to put in a repr - Include the class name, then the handful of fields that identify the instance — usually the ones passed to `__init__`. - Use `!r` on each field inside your f-string so that strings come out quoted and `'1'` is visibly different from `1`; that single habit removes a whole class of confusion. - Keep it to one line: a repr that wraps is unreadable in a log. - Leave out anything expensive, unbounded or secret. ## When to add `__str__` at all Only when the friendly form differs from the diagnostic form in a way that matters — a money amount rendered as `$12.50` rather than `Money(cents=1250)`, a duration as `01:34` rather than `Duration(94)`. If the two would say the same thing, one `__repr__` is enough, and you get the readable form for free through the fallback. Adding a `__str__` that merely drops the class name usually makes the object harder to debug for no gain, because it is the repr — not the str — that shows up when things go wrong. ## Two details that catch people out 1. First, the interactive prompt shows `repr()`, not `str()`: type `v` at the REPL and you get `Video(title='intro', seconds=94)`, while `print(v)` on the next line gives `intro (94s)`. The prompt renders the value of each statement through `sys.displayhook`, which uses `repr()` precisely because an interactive session is a developer context. 2. Second, a repr that hard-codes its class name lies in a subclass: if `Video.__repr__` returns the literal text `"Video(...)"`, then a `TrimmedVideo` subclass prints as a `Video` and sends the next reader looking at the wrong class. Building the name with `type(self).__name__` costs nothing and keeps the repr truthful under inheritance. Both details reinforce the same idea: the repr is a diagnostic instrument, and an instrument that misreports is worse than none.