Add typing.override decorator

[stroxler]

Feature or enhancement

See PEP 698 for details.

The typing.override decorator should, at runtime, attempt to set the __override__ attribute on its argument to True and then return the argument. If it cannot set the __override__ flag it should return its argument unchanged.

Pitch

The purpose of typing.override is to inform static type checkers that we expect this method to override some attribute of an ancestor class. By having this decorator in place, a developer can ensure that static type checkers will warn them if a base class method name changes.

To quote the PEP consider a code change where we rename a parent class method.

The original code looks like this:

class Parent:
    def foo(self, x: int) -> int:
        return x

class Child(Parent):
    def foo(self, x: int) -> int:
        return x + 1

def parent_callsite(parent: Parent) -> None:
    parent.foo(1)

def child_callsite(child: Child) -> None:
    child.foo(1)

And after our rename it looks like this:

class Parent:
    # Rename this method
    def new_foo(self, x: int) -> int:
        return x

class Child(Parent):
    # This (unchanged) method used to override `foo` but is unrelated to `new_foo`
    def foo(self, x: int) -> int:
        return x + 1

def parent_callsite(parent: Parent) -> None:
    # If we pass a Child instance we’ll now run Parent.new_foo - likely a bug
    parent.new_foo(1)

def child_callsite(child: Child) -> None:
    # We probably wanted to invoke new_foo here. Instead, we forked the method
    child.foo(1)

In the code snippet above, renaming foo to new_foo in Parent invalidated the override foo of Child. But type checkers have no way of knowing this, because they only see a snapshot of the code.

If we mark Child.foo as an override, then static type checkers will catch the mistake when we rename only Parent.foo:

from typing import override

class Parent:
    def new_foo(self) -> int:
        return 1

    def bar(self, x: str) -> str:
        return x

class Child(Parent):
    @override
    def foo(self) -> int:   # Type Error: foo does not override an attribute of any ancestor
        return 2

Previous discussion

PEP 698 has details about the proposal itself.

Discussion on this proposal has happened on typing-sig and on [discuss.python.org)[https://discuss.python.org/t/pep-698-a-typing-override-decorator/20839].

Linked PRs

• gh-101561: Add typing.override decorator #101564

[JelleZijlstra]

Merged, thanks @stroxler!