What do type hints and a checker like mypy actually buy you?

Type hints are annotations that Python does not enforce at runtime; a static checker such as mypy or pyright reads them and reports inconsistencies before the code runs. The payoff is catching whole classes of errors like None flowing where a value is required, plus far better editor completion and refactoring. They also document intent more reliably than a docstring, which drifts.

At runtime they are basically comments, since Python stores them and moves on. The value comes from a checker reading them. Mypy catches the boring bugs that cause most incidents, mainly optional values flowing into code that assumes a real object, and signature drift after a refactor where one caller was missed. On a codebase I inherited with roughly sixty thousand lines and no annotations, we turned mypy on with almost everything disabled, added it to CI so the error count could not grow, and then typed module by module starting at the boundaries where data enters. Strict mode came later, per package, using per module overrides in pyproject. Six months in it caught a None dereference in a payment path during review rather than at two in the morning. The other benefit people undersell is editor support, because with real types, rename and go to definition actually work, which changes how willing the team is to refactor anything.