296 lines
8.9 KiB
ReStructuredText
296 lines
8.9 KiB
ReStructuredText
PEP: 591
|
||
Title: Adding a final qualifier to typing
|
||
Author: Michael J. Sullivan <sully@msully.net>, Ivan Levkivskyi <levkivskyi@gmail.com>
|
||
BDFL-Delegate: Guido van Rossum <guido@python.org>
|
||
Discussions-To: typing-sig@python.org
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 15-Mar-2019
|
||
Post-History:
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP proposes a "final" qualifier to be added to the ``typing``
|
||
module---in the form of a ``final`` decorator and a ``Final`` type
|
||
annotation---to serve three related purposes:
|
||
|
||
* Declaring that a method should not be overridden
|
||
* Declaring that a class should not be subclassed
|
||
* Declaring that a variable or attribute should not be reassigned
|
||
|
||
|
||
Motivation
|
||
==========
|
||
|
||
The ``final`` decorator
|
||
-----------------------
|
||
The current ``typing`` module lacks a way to restrict the use of
|
||
inheritance or overriding at a typechecker level. This is a common
|
||
feature in other object-oriented languages (such as Java), and is
|
||
useful for reducing the potential space of behaviors of a class,
|
||
easing reasoning.
|
||
|
||
Some situations where a final class or method may be useful include:
|
||
|
||
* A class wasn’t designed to be subclassed or a method wasn't designed
|
||
to be overridden. Perhaps it would not work as expected, or be
|
||
error-prone.
|
||
* Subclassing or overriding would make code harder to understand or
|
||
maintain. For example, you may want to prevent unnecessarily tight
|
||
coupling between base classes and subclasses.
|
||
* You want to retain the freedom to arbitrarily change the class
|
||
implementation in the future, and these changes might break
|
||
subclasses.
|
||
|
||
The ``Final`` annotation
|
||
------------------------
|
||
|
||
The current ``typing`` module lacks a way to indicate that a variable
|
||
will not be assigned to. This is a useful feature in several
|
||
situations:
|
||
|
||
* Preventing unintended modification of module and class level
|
||
constants and documenting them as constants in a checkable way.
|
||
* Creating a read-only attribute that may not be overridden by
|
||
subclasses. (``@property`` can make an attribute read-only but
|
||
does not prevent overriding)
|
||
* Allowing a name to be used in situations where ordinarily a literal
|
||
is expected (for example as a field name for ``NamedTuple``, a tuple
|
||
of types passed to ``isinstance``, or an argument to a function
|
||
with arguments of ``Literal`` type [#PEP-586]_).
|
||
|
||
Specification
|
||
=============
|
||
|
||
The ``final`` decorator
|
||
-----------------------
|
||
|
||
The ``typing.final`` decorator is used to restrict the use of
|
||
inheritance and overriding.
|
||
|
||
A type checker should prohibit any class decorated with ``@final``
|
||
from being subclassed and any method decorated with ``@final`` from
|
||
being overridden in a subclass. The method decorator version may be
|
||
used with all of instance methods, class methods, static methods, and properties.
|
||
|
||
For example::
|
||
|
||
from typing import final
|
||
|
||
@final
|
||
class Base:
|
||
...
|
||
|
||
class Derived(Base): # Error: Cannot inherit from final class "Base"
|
||
...
|
||
|
||
and::
|
||
|
||
from typing import final
|
||
|
||
class Base:
|
||
@final
|
||
def foo(self) -> None:
|
||
...
|
||
|
||
class Derived(Base):
|
||
def foo(self) -> None: # Error: Cannot override final attribute "foo"
|
||
# (previously declared in base class "Base")
|
||
...
|
||
|
||
|
||
For overloaded methods, ``@final`` should be placed on the
|
||
implementation (or on the first overload, for stubs)::
|
||
|
||
from typing import Any, overload
|
||
|
||
class Base:
|
||
@overload
|
||
def method(self) -> None: ...
|
||
@overload
|
||
def method(self, arg: int) -> int: ...
|
||
@final
|
||
def method(self, x=None):
|
||
...
|
||
|
||
It is an error to use ``@final`` on a non-method function.
|
||
|
||
The ``Final`` annotation
|
||
------------------------
|
||
|
||
The ``typing.Final`` type qualifier is used to indicate that a
|
||
variable or attribute should not be reassigned, redefined, or overridden.
|
||
|
||
Syntax
|
||
~~~~~~
|
||
|
||
``Final`` may be used in in one of several forms:
|
||
|
||
* With an explicit type, using the syntax ``Final[<type>]``. Example::
|
||
|
||
ID: Final[float] = 1
|
||
|
||
* With no type annotation. Example::
|
||
|
||
ID: Final = 1
|
||
|
||
The typechecker should apply its usual type inference mechanisms to
|
||
determine the type of ``ID`` (here, likely, ``int``). Note that unlike for
|
||
generic classes this is *not* the same as ``Final[Any]``.
|
||
|
||
* In class bodies and stub files you can omit the right hand side and just write
|
||
``ID: Final[float]``. If the right hand side is omitted, there must
|
||
be an explicit type argument to ``Final``.
|
||
|
||
* Finally, as ``self.id: Final = 1`` (also optionally with a type in
|
||
square brackets). This is allowed *only* in ``__init__`` methods, so
|
||
that the final instance attribute is assigned only once when an
|
||
instance is created.
|
||
|
||
|
||
Semantics and examples
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The two main rules for defining a final name are:
|
||
|
||
* There can be *at most one* final declaration per module or class for
|
||
a given attribute. There can't be separate class-level and instance-level
|
||
constants with the same name.
|
||
|
||
* There must be *exactly one* assignment to a final name.
|
||
|
||
This means a type checker should prevent further assignments to final
|
||
names in type-checked code::
|
||
|
||
from typing import Final
|
||
|
||
RATE: Final = 3000
|
||
|
||
class Base:
|
||
DEFAULT_ID: Final = 0
|
||
|
||
RATE = 300 # Error: can't assign to final attribute
|
||
Base.DEFAULT_ID = 1 # Error: can't override a final attribute
|
||
|
||
Note that a type checker need not allow ``Final`` declarations inside loops
|
||
since the runtime will see multiple assignments to the same variable in
|
||
subsequent iterations.
|
||
|
||
Additionally, a type checker should prevent final attributes from
|
||
being overridden in a subclass::
|
||
|
||
from typing import Final
|
||
|
||
class Window:
|
||
BORDER_WIDTH: Final = 2.5
|
||
...
|
||
|
||
class ListView(Window):
|
||
BORDER_WIDTH = 3 # Error: can't override a final attribute
|
||
|
||
A final attribute declared in a class body without an initializer must
|
||
be initialized in the ``__init__`` method (except in stub files)::
|
||
|
||
class ImmutablePoint:
|
||
x: Final[int]
|
||
y: Final[int] # Error: final attribute without an initializer
|
||
|
||
def __init__(self) -> None:
|
||
self.x = 1 # Good
|
||
|
||
Type checkers should infer a final attribute that is initialized in
|
||
a class body as being a class variable. Variables should not be annotated
|
||
with both ``ClassVar`` and ``Final``.
|
||
|
||
``Final`` may only be used as the outermost type in assignments or variable
|
||
annotations. Using it in any other position is an error. In particular,
|
||
``Final`` can't be used in annotations for function arguments::
|
||
|
||
x: List[Final[int]] = [] # Error!
|
||
|
||
def fun(x: Final[List[int]]) -> None: # Error!
|
||
...
|
||
|
||
Note that declaring a name as final only guarantees that the name will
|
||
not be re-bound to another value, but does not make the value
|
||
immutable. Immutable ABCs and containers may be used in combination
|
||
with ``Final`` to prevent mutating such values::
|
||
|
||
x: Final = ['a', 'b']
|
||
x.append('c') # OK
|
||
|
||
y: Final[Sequence[str]] = ['a', 'b']
|
||
y.append('x') # Error: "Sequence[str]" has no attribute "append"
|
||
z: Final = ('a', 'b') # Also works
|
||
|
||
|
||
Type checkers should treat uses of a final name that was initialized
|
||
with a literal as if it was replaced by the literal. For example, the
|
||
following should be allowed::
|
||
|
||
from typing import NamedTuple, Final
|
||
|
||
X: Final = "x"
|
||
Y: Final = "y"
|
||
N = NamedTuple("N", [(X, int), (Y, int)])
|
||
|
||
|
||
Reference Implementation
|
||
========================
|
||
|
||
The mypy [#mypy]_ type checker supports `Final` and `final`. A
|
||
reference implementation of the runtime component is provided in the
|
||
``typing_extensions`` [#typing_extensions]_ module.
|
||
|
||
|
||
Rejected/deferred Ideas
|
||
=======================
|
||
|
||
The name ``Const`` was also considered as the name for the ``Final``
|
||
type annotation. The name ``Final`` was chosen instead because the
|
||
concepts are related and it seemed best to be consistent between them.
|
||
|
||
We considered using a single name ``Final`` instead of introducing
|
||
``final`` as well, but ``@Final`` just looked too weird to us.
|
||
|
||
A related feature to final classes would be Scala-style sealed
|
||
classes, where a class is allowed to be inherited only by classes
|
||
defined in the same module. Sealed classes seem most useful in
|
||
combination with pattern matching, so it does not seem to justify the
|
||
complexity in our case. This could be revisisted in the future.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
.. [#PEP-484] PEP 484, Type Hints, van Rossum, Lehtosalo, Langa
|
||
(http://www.python.org/dev/peps/pep-0484)
|
||
|
||
.. [#PEP-526] PEP 526, Syntax for Variable Annotations, Gonzalez,
|
||
House, Levkivskyi, Roach, van Rossum
|
||
(http://www.python.org/dev/peps/pep-0526)
|
||
|
||
.. [#PEP-586] PEP 486, Literal Types, Lee, Levkivskyi, Lehtosalo
|
||
(http://www.python.org/dev/peps/pep-0586)
|
||
|
||
.. [#mypy] http://www.mypy-lang.org/
|
||
|
||
.. [#typing_extensions] https://github.com/python/typing/typing_extensions
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
coding: utf-8
|
||
End:
|