Repository navigation
Proposal: add @typing.format_specifiers #2321
Description
This decorator factory would tell type checkers what format codes are supported by instances of that type. It would take variable positional arguments, each a string corresponding to a valid specification, and type checkers will know the class its returned decorator is applied to will only take those format specifications, so that it can flag mistyped format specifications and make subtle bugs clear. It, however, requires special-casing string formatting and the format builtin.
Currently it is possible to restrict the type of format_spec in __format__ to Literal[...], but that will cause Liskov substitution principle violations and type checkers may not consider it.
I am opening an issue here in hopes of getting more feedback because my DPO thread has gained little traction.
Activity
Viicos commentedon Jul 31, 2026
I recall there was some discussion about special casing
__replace__()from the LSP (maybe some type checkers even do so). Maybe it would make sense to exempt__format__()too?jonathandung commentedon Aug 5, 2026
astral-sh/ty#4046 was rejected. I am unlikely to try it on other type checkers, because
tyis the most experimental, meaning it is more likely to accept novel ideas (with some precedents).