Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Final Type Hint vs final Decorator: Static Checks for Variables and Overrides

Python's Final type hint and final decorator both guide static type checkers, but in different contexts: Final marks variables that should not be rebound, while final marks methods and classes that should not be overridden or subclassed.

~4 min readPython
#typing#type hints#final decorator#type checkers
Comparison of Python Final type hint and final decorator with type checker and runtime enforcement symbols.

Does x: Final = 5 prevent reassignment in Python? The short answer is no. The Final annotation is a type hint for static checkers, not a runtime constraint. This article explains the practical difference between Python's Final type hint and the final decorator, and shows when each is appropriate.

What Final Type Hint Actually Does

When you write MAX_RETRIES: Final = 3, you are telling type checkers like mypy or pyright that MAX_RETRIES should never be reassigned. If you later write MAX_RETRIES = 4, the type checker will report an error. At runtime, however, Final is only an annotation. The variable behaves like any other Python variable; nothing prevents reassignment. This is the core distinction: Final is a static-analysis tool, not a runtime guard.

What the final Decorator Does

The final decorator from typing (or typing_extensions for older Python versions) is also a type-checking tool. It is applied to methods and classes to tell type checkers that a method must not be overridden or a class must not be subclassed. Unlike a common assumption, typing.final does not itself raise TypeError at runtime when those rules are broken. It marks the method or class for static checkers; enforcing the rule at runtime would require custom behavior.

The Difference Between a Final Variable and a Final Method

The phrase "final variable" often refers to the concept of a constant—a name that should not be rebound. Python has no built-in constant keyword, so developers rely on Final type hints to communicate intent to static checkers. A "final method" (or class) is a different concept: it restricts overriding and subclassing. The two are often confused because they share the word "final" but are used in different contexts. Final affects variable binding; final affects method overriding and class inheritance.

Using Final for Constants in Type-Checked Code

To define a constant that type checkers will enforce as non-reassignable, use Final in the annotation. For example:

python
from typing import Final MAX_CONNECTIONS: Final = 100 DEFAULT_TIMEOUT: Final = 30

If you later try to assign a new value, mypy will flag it:

python
MAX_CONNECTIONS = 200 # error: Cannot assign to final name "MAX_CONNECTIONS"

This works for module-level variables, class attributes, and even local variables. It is a common pattern for configuration constants that should remain stable. However, note that Final does not make the object itself immutable. If the variable points to a list, you can still mutate the list; only the binding is protected.

Using final to Mark Methods and Classes as Final

When you want static type checkers to reject an overriding method, decorate the base method with @final. Here is a minimal example:

python
from typing import final class Service: @final def connect(self) -> None: print("Connecting") class MockService(Service): def connect(self) -> None: # type checker reports an error print("Mock connect")

A type checker will report that MockService.connect cannot override the final method. At runtime, however, MockService can still be instantiated and the override will work unless you add your own enforcement. Similarly, a class decorated with @final is treated as non-subclassable by type checkers:

python
from typing import final @final class Config: pass class ExtendedConfig(Config): # type checker reports an error pass

The type checker will report that ExtendedConfig cannot subclass the final class Config. The standard-library decorator does not prevent this at runtime; it communicates the contract to tools and to developers reading the code.

Common Misconceptions and Runtime Behavior

A frequent mistake is assuming that Final prevents reassignment at runtime. It does not. The annotation is not enforced by the Python interpreter; only type checkers enforce it. If you need runtime protection against reassignment, you would have to implement a custom descriptor or use a library like dataclasses with frozen=True (for instance attributes). But for simple module-level constants, Final is usually sufficient when the codebase is type-checked.

Another misconception is that final provides runtime enforcement. It does not. final is a marker for type checkers, just as Final is; the difference is in what they mark, not in runtime behavior. Final is a type hint for variable bindings; final is a decorator for methods and classes. Applying the wrong identifier will not produce the intended type-checking effect.

Choosing Between Final and final

Use Final when you want to declare that a variable should not be rebound, and you rely on static type checking to catch violations. This is typical for constants, configuration values, and named numeric literals.

Use final when you want type checkers to reject method overrides or class subclassing. This is particularly useful for library authors who want to communicate that certain methods are not meant to be overridden or classes are not meant to be extended.

In practice, you can combine both: define a constant with Final and mark a method with @final if it must not be overridden. They address different concerns and are not interchangeable.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.