Overrides Library

7.7.0 · active · verified Sat Mar 28

The `overrides` library (v7.7.0) provides a Python decorator `@override` to ensure that a method in a subclass correctly overrides a method from its superclass. It also includes `EnforceOverrides` for metaclass-level checks and `@final` to prevent methods from being overridden. The library focuses on improving the safety and experience of creating class hierarchies by catching common errors at class creation time, such as signature mismatches or accidental non-overrides. It has a regular release cadence, with several minor and patch releases in the past year.

Warnings

breaking In version 7.0.0, the library changed how it handles `final` magic methods and assertion failures. Magic methods (e.g., `__eq__`, `__init__`) marked as `@final` that are accidentally overridden now raise `TypeError` instead of `AssertionError`. Similarly, assertion errors originating from the `EnforceOverrides` metaclass have been changed to `TypeErrors`. This may break existing tests or error handling code that specifically caught `AssertionError`.
Fix: Update exception handling to catch `TypeError` instead of `AssertionError` for issues related to `EnforceOverrides` or `final` magic method overrides.
gotcha Versions prior to 7.6.0 might experience issues with Python 3.12 due to changes in bytecode handling. This could lead to unexpected behavior or runtime errors on Python 3.12 environments.
Fix: Upgrade to `overrides` version 7.6.0 or newer to ensure compatibility and correct bytecode handling with Python 3.12.
gotcha When combining `@override` with other method decorators like `@classmethod` or `@staticmethod`, the `@classmethod` or `@staticmethod` decorator must always be applied *before* `@override`. Incorrect order will lead to unexpected behavior or errors.
Fix: Ensure `@classmethod` or `@staticmethod` is the outermost decorator, followed by `@override`. Example: `@classmethod @override def my_method(cls, ...):`
deprecated The original decorator name `@overrides` (plural) is still functional, but `@override` (singular) was introduced in version 7.3.0 as an alias and is now the officially recommended decorator name, aligning with common usage and `typing.override`.
Fix: Prefer using `from overrides import override` and the `@override` decorator for new code. Update existing code to use `@override` for consistency.
gotcha If a base class inherits from `EnforceOverrides`, any method in a subclass that is intended to override a superclass method *must* be explicitly decorated with `@override` (or `@overrides`). Failing to do so will result in a `TypeError` at class definition time, preventing subtle bugs caused by method signature changes in parent classes.
Fix: Always decorate methods in subclasses with `@override` if they are meant to override a method from a base class that uses `EnforceOverrides`.
gotcha Python 3.12 introduced a standard `typing.override` decorator (PEP 698) for static type checkers. The `overrides` library's `@override` provides *runtime* validation and docstring inheritance, which is distinct from `typing.override`'s static analysis purpose. Using both might be confusing but they serve different roles.
Fix: Understand the difference: `overrides.override` provides runtime checks and features, while `typing.override` is purely for static analysis. Choose based on whether you need runtime enforcement or only static type checking.

Install

pip install overrides Install latest version

Imports

override
```
from overrides import override
```
This is the recommended alias for the decorator since version 7.3.0.
overrides
```
from overrides import overrides
```
The original name of the decorator, still functional but `@override` is preferred.
EnforceOverrides
```
from overrides import EnforceOverrides
```
This is a metaclass, not a decorator, used to enforce `@override` usage.
final
```
from overrides import final
```
Use `typing.final` directly for Python 3.11+; `overrides.final` provides a backport for older versions.

Quickstart

This quickstart demonstrates how to use the `@override` decorator with the `EnforceOverrides` metaclass. The `Animal` class defines methods, and `Dog` subclasses it, using `@override` to explicitly mark overridden methods. If `EnforceOverrides` is used, methods intended to override a superclass method *must* use the `@override` decorator, otherwise a `TypeError` will be raised at class creation time. The library also automatically copies docstrings from the overridden method.

from overrides import override, EnforceOverrides

class Animal(EnforceOverrides):
    def make_sound(self) -> str:
        raise NotImplementedError

    def eat(self) -> str:
        return "Eating generic food"

class Dog(Animal):
    @override
    def make_sound(self) -> str:
        return "Woof!"
    
    # No @override needed if not overriding a method, or if EnforceOverrides is not used.
    def fetch(self) -> str:
        return "Fetching the ball"

# Example of usage
dog = Dog()
print(dog.make_sound())
print(dog.eat())

# This would raise TypeError if @override was missing on make_sound and EnforceOverrides was used.
# class Cat(Animal):
#     def make_sound(self) -> str: # Missing @override, would fail with EnforceOverrides
#         return "Meow!"

view raw JSON →