2022-07-02 22:20:44 -04:00
|
|
|
PEP: 695
|
|
|
|
Title: Type Parameter Syntax
|
|
|
|
Author: Eric Traut <erictr at microsoft.com>
|
|
|
|
Sponsor: Guido van Rossum <guido@python.org>
|
2022-09-14 00:26:28 -04:00
|
|
|
Discussions-To: https://mail.python.org/archives/list/typing-sig@python.org/thread/BB2BGYJY2YG5IWESKGTAPUQL3N27ZKVW/
|
2022-07-02 22:20:44 -04:00
|
|
|
Status: Draft
|
|
|
|
Type: Standards Track
|
2022-10-06 20:36:39 -04:00
|
|
|
Topic: Typing
|
2022-07-02 22:20:44 -04:00
|
|
|
Content-Type: text/x-rst
|
|
|
|
Created: 15-Jun-2022
|
|
|
|
Python-Version: 3.12
|
2022-09-14 00:26:28 -04:00
|
|
|
Post-History: `20-Jun-2022 <https://mail.python.org/archives/list/typing-sig@python.org/thread/BB2BGYJY2YG5IWESKGTAPUQL3N27ZKVW/>`__
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Abstract
|
|
|
|
========
|
|
|
|
|
|
|
|
This PEP specifies an improved syntax for specifying type parameters within
|
|
|
|
a generic class, function, or type alias. It also introduces a new statement
|
|
|
|
for declaring type aliases.
|
|
|
|
|
|
|
|
|
|
|
|
Motivation
|
|
|
|
==========
|
|
|
|
|
|
|
|
:pep:`484` introduced type variables into the language. :pep:`612` built
|
|
|
|
upon this concept by introducing parameter specifications, and
|
|
|
|
:pep:`646` added variadic type variables.
|
|
|
|
|
|
|
|
While generic types and type parameters have grown in popularity, the
|
|
|
|
syntax for specifying type parameters still feels "bolted on" to Python.
|
|
|
|
This is a source of confusion among Python developers.
|
|
|
|
|
|
|
|
There is consensus within the Python static typing community that it is time
|
2022-09-14 00:26:28 -04:00
|
|
|
to provide a formal syntax that is similar to other modern programming
|
|
|
|
languages that support generic types.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
An analysis of 25 popular typed Python libraries revealed that type
|
|
|
|
variables (in particular, the ``typing.TypeVar`` symbol) were used in
|
2022-09-14 00:26:28 -04:00
|
|
|
14% of modules.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Points of Confusion
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
While the use of type variables has become widespread, the manner in which
|
|
|
|
they are specified within code is the source of confusion among many
|
|
|
|
Python developers. There are a couple of factors that contribute to this
|
|
|
|
confusion.
|
|
|
|
|
|
|
|
The scoping rules for type variables are difficult to understand. Type
|
|
|
|
variables are typically allocated within the global scope, but their semantic
|
|
|
|
meaning is valid only when used within the context of a generic class,
|
2022-09-14 00:26:28 -04:00
|
|
|
function, or type alias. A single runtime instance of a type variable may be
|
2022-07-02 22:20:44 -04:00
|
|
|
reused in multiple generic contexts, and it has a different semantic meaning
|
|
|
|
in each of these contexts. This PEP proposes to eliminate this source of
|
|
|
|
confusion by declaring type parameters at a natural place within a class,
|
2022-09-14 00:26:28 -04:00
|
|
|
function, or type alias declaration statement.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Generic type aliases are often misused because it is not clear to developers
|
|
|
|
that a type argument must be supplied when the type alias is used. This leads
|
|
|
|
to an implied type argument of ``Any``, which is rarely the intent. This PEP
|
|
|
|
proposes to add new syntax that makes generic type alias declarations
|
|
|
|
clear.
|
|
|
|
|
|
|
|
:pep:`483` and :pep:`484` introduced the concept of "variance" for a type
|
|
|
|
variable used within a generic class. Type variables can be invariant,
|
|
|
|
covariant, or contravariant. The concept of variance is an advanced detail
|
|
|
|
of type theory that is not well understood by most Python developers, yet
|
2022-09-14 00:26:28 -04:00
|
|
|
they must confront this concept today when defining their first generic
|
|
|
|
class. This PEP largely eliminates the need for most developers
|
2022-07-02 22:20:44 -04:00
|
|
|
to understand the concept of variance when defining generic classes.
|
|
|
|
|
|
|
|
When more than one type parameter is used with a generic class or type alias,
|
|
|
|
the rules for type parameter ordering can be confusing. It is normally based on
|
|
|
|
the order in which they first appear within a class or type alias declaration
|
|
|
|
statement. However, this can be overridden in a class definition by
|
|
|
|
including a "Generic" or "Protocol" base class. For example, in the class
|
|
|
|
declaration ``class ClassA(Mapping[K, V])``, the type parameters are
|
|
|
|
ordered as ``K`` and then ``V``. However, in the class declaration
|
|
|
|
``class ClassB(Mapping[K, V], Generic[V, K])``, the type parameters are
|
|
|
|
ordered as ``V`` and then ``K``. This PEP proposes to make type parameter
|
|
|
|
ordering explicit in all cases.
|
|
|
|
|
|
|
|
The practice of sharing a type variable across multiple generic contexts
|
|
|
|
creates other problems today. Modern editors provide features like "find
|
|
|
|
all references" and "rename all references" that operate on symbols at the
|
|
|
|
semantic level. When a type parameter is shared among multiple generic
|
|
|
|
classes, functions, and type aliases, all references are semantically
|
|
|
|
equivalent.
|
|
|
|
|
|
|
|
Type variables defined within the global scope also need to be given a name
|
|
|
|
that starts with an underscore to indicate that the variable is private to
|
|
|
|
the module. Globally-defined type variables are also often given names to
|
2022-07-12 00:04:34 -04:00
|
|
|
indicate their variance, leading to cumbersome names like "_T_contra" and
|
2022-07-02 22:20:44 -04:00
|
|
|
"_KT_co". The current mechanisms for allocating type variables also requires
|
|
|
|
the developer to supply a redundant name in quotes (e.g. ``T = TypeVar("T")``).
|
2022-07-12 00:04:34 -04:00
|
|
|
This PEP eliminates the need for the redundant name and cumbersome
|
2022-07-02 22:20:44 -04:00
|
|
|
variable names.
|
|
|
|
|
|
|
|
Defining type parameters today requires importing the ``TypeVar`` and
|
|
|
|
``Generic`` symbols from the ``typing`` module. Over the past several releases
|
|
|
|
of Python, efforts have been made to eliminate the need to import ``typing``
|
|
|
|
symbols for common use cases, and the PEP furthers this goal.
|
|
|
|
|
|
|
|
|
|
|
|
Summary Examples
|
|
|
|
================
|
|
|
|
|
|
|
|
Defining a generic class prior to this PEP looks something like this.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
from typing import Generic, TypeVar
|
|
|
|
|
|
|
|
_T_co = TypeVar("_T_co", covariant=True, bound=str)
|
|
|
|
|
|
|
|
class ClassA(Generic[_T_co]):
|
2022-09-14 00:26:28 -04:00
|
|
|
def method1(self) -> _T_co:
|
|
|
|
...
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
With the new syntax, it looks like this.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T: str]:
|
2022-09-14 00:26:28 -04:00
|
|
|
def method1(self) -> T:
|
|
|
|
...
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Here is an example of a generic function today.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
from typing import TypeVar
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
_T = TypeVar("_T")
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
def func(a: _T, b: _T) -> _T:
|
2022-07-02 22:20:44 -04:00
|
|
|
...
|
|
|
|
|
|
|
|
And the new syntax.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
def func[T](a: T, b: T) -> T:
|
2022-07-02 22:20:44 -04:00
|
|
|
...
|
|
|
|
|
|
|
|
|
|
|
|
Here is an example of a generic type alias today.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
from typing import TypeAlias
|
|
|
|
|
|
|
|
_T = TypeVar("_T")
|
|
|
|
|
|
|
|
ListOrSet: TypeAlias = list[_T] | set[_T]
|
|
|
|
|
|
|
|
|
|
|
|
And with the new syntax.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
type ListOrSet[T] = list[T] | set[T]
|
|
|
|
|
|
|
|
|
|
|
|
Specification
|
|
|
|
=============
|
|
|
|
|
|
|
|
Type Parameter Declarations
|
|
|
|
---------------------------
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
Here is a new syntax for declaring type parameters for generic
|
2022-07-02 22:20:44 -04:00
|
|
|
classes, functions, and type aliases. The syntax adds support for
|
|
|
|
a comma-delimited list of type parameters in square brackets after
|
|
|
|
the name of the class, function, or type alias.
|
|
|
|
|
|
|
|
Simple (non-variadic) type variables are declared with an unadorned name.
|
2022-09-14 00:26:28 -04:00
|
|
|
Variadic type variables are preceded by ``*`` (see :pep:`646` for details).
|
|
|
|
Parameter specifications are preceded by ``**`` (see :pep:`612` for details).
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
# This generic class is parameterized by a TypeVar T, a
|
|
|
|
# TypeVarTuple Ts, and a ParamSpec P.
|
|
|
|
class ChildClass[T, *Ts, **P]: ...
|
|
|
|
|
|
|
|
There is no need to include ``Generic`` as a base class. Its inclusion as
|
|
|
|
a base class is implied by the presence of type parameters, and it will
|
2022-09-14 00:26:28 -04:00
|
|
|
automatically be included in the ``__mro__`` and ``__orig_bases__`` attributes
|
2022-07-02 22:20:44 -04:00
|
|
|
for the class. The explicit use of a ``Generic`` base class will result in a
|
|
|
|
runtime error.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T](Generic[T]): ... # Runtime error
|
|
|
|
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
A ``Protocol`` base class with type arguments may generate a runtime
|
|
|
|
error. Type checkers should generate an error in this case because
|
2022-07-02 22:20:44 -04:00
|
|
|
the use of type arguments is not needed, and the order of type parameters
|
|
|
|
for the class are no longer dictated by their order in the ``Protocol``
|
|
|
|
base class.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[S, T](Protocol): ... # OK
|
|
|
|
|
|
|
|
class ClassB[S, T](Protocol[S, T]): ... # Recommended type checker error
|
|
|
|
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
Type parameter names within a generic class, function, or type alias must be
|
|
|
|
unique within that same class, function, or type alias. A duplicate name
|
|
|
|
generates a syntax error at compile time. This is consistent with the
|
|
|
|
requirement that parameter names within a function signature must be unique.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T, *T]: ... # Syntax Error
|
|
|
|
|
|
|
|
def func1[T, **T](): ... # Syntax Error
|
|
|
|
|
|
|
|
|
2022-07-12 00:04:34 -04:00
|
|
|
Class type parameter names are not mangled if they begin with a double
|
|
|
|
underscore. Mangling would not make sense because type parameters, unlike other
|
|
|
|
class-scoped variables, cannot be accessed through the class dictionary, and
|
2022-09-14 00:26:28 -04:00
|
|
|
the notion of a "private" type parameter doesn't make sense.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Upper Bound Specification
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
For a non-variadic type parameter, an "upper bound" type can be specified
|
|
|
|
through the use of a type annotation expression. If an upper bound is
|
|
|
|
not specified, the upper bound is assumed to be ``object``.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T: str]: ...
|
|
|
|
|
|
|
|
The specified upper bound type must use an expression form that is allowed in
|
|
|
|
type annotations. More complex expression forms should be flagged
|
2022-09-14 00:26:28 -04:00
|
|
|
as an error by a type checker. Quoted forward references are allowed.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
The specified upper bound type must be concrete. An attempt to use a generic
|
2022-09-14 00:26:28 -04:00
|
|
|
type should be flagged as an error by a type checker. This is consistent with
|
|
|
|
the existing rules enforced by type checkers for a ``TypeVar`` constructor call.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T: dict[str, int]]: ... # OK
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
class ClassB[T: "ForwardReference"]: ... # OK
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
class ClassC[V]:
|
|
|
|
class ClassD[T: dict[str, V]]: ... # Type checker error: generic type
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
class ClassE[T: [str, int]]: ... # Type checker error: illegal expression form
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Constrained Type Specification
|
|
|
|
------------------------------
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
:pep:`484` introduced the concept of a "constrained type variable" which is
|
|
|
|
constrained to a set of two or more types. The new syntax supports this type
|
|
|
|
of constraint through the use of a literal tuple expression that contains
|
2022-07-02 22:20:44 -04:00
|
|
|
two or more types.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[AnyStr: (str, bytes)]: ... # OK
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
class ClassB[T: ("ForwardReference", bytes)]: ... # OK
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
class ClassC[T: ()]: ... # Type checker error: two or more types required
|
|
|
|
|
|
|
|
class ClassD[T: (str, )]: ... # Type checker error: two or more types required
|
|
|
|
|
|
|
|
t1 = (bytes, str)
|
|
|
|
class ClassE[T: t1]: ... # Type checker error: literal tuple expression required
|
|
|
|
|
|
|
|
|
|
|
|
If the specified type is not a tuple expression or the tuple expression includes
|
|
|
|
complex expression forms that are not allowed in a type annotation, a type
|
2022-09-14 00:26:28 -04:00
|
|
|
checker should generate an error. Quoted forward references are allowed.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassF[T: (3, bytes)]: ... # Type checker error: invalid expression form
|
|
|
|
|
|
|
|
|
|
|
|
The specified constrained types must be concrete. An attempt to use a generic
|
|
|
|
type should be flagged as an error by a type checker. This is consistent with
|
|
|
|
the existing rules enforced by type checkers for a ``TypeVar`` constructor call.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassG[T: (list[S], str)]: ... # Type checker error: generic type
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Generic Type Alias
|
|
|
|
------------------
|
|
|
|
|
|
|
|
We propose to introduce a new statement for declaring type aliases. Similar
|
|
|
|
to ``class`` and ``def`` statements, a ``type`` statement defines a scope
|
|
|
|
for type parameters.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
# A non-generic type alias
|
|
|
|
type IntOrStr = int | str
|
|
|
|
|
|
|
|
# A generic type alias
|
|
|
|
type ListOrSet[T] = list[T] | set[T]
|
|
|
|
|
|
|
|
|
|
|
|
Type aliases can refer to themselves without the use of quotes.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
# A type alias that includes a forward reference
|
2022-07-02 22:20:44 -04:00
|
|
|
type AnimalOrVegetable = Animal | "Vegetable"
|
|
|
|
|
|
|
|
# A generic self-referential type alias
|
|
|
|
type RecursiveList[T] = T | list[RecursiveList[T]]
|
|
|
|
|
|
|
|
|
|
|
|
The ``type`` keyword is a new soft keyword. It is interpreted as a keyword
|
|
|
|
only in this part of the grammar. In all other locations, it is assumed to
|
|
|
|
be an identifier name.
|
|
|
|
|
|
|
|
Type parameters declared as part of a generic type alias are valid only
|
|
|
|
when evaluating the right-hand side of the type alias.
|
|
|
|
|
|
|
|
As with ``typing.TypeAlias``, type checkers should restrict the right-hand
|
|
|
|
expression to expression forms that are allowed within type annotations.
|
|
|
|
The use of more complex expression forms (call expressions, ternary operators,
|
|
|
|
arithmetic operators, comparison operators, etc.) should be flagged as an
|
|
|
|
error.
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
Type alias expressions are not allowed to use traditional type variables (i.e.
|
|
|
|
those allocated with an explicit ``TypeVar`` constructor call). Type checkers
|
|
|
|
should generate an error in this case.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
T = TypeVar("T")
|
|
|
|
type MyList = list[T] # Type checker error: traditional type variable usage
|
|
|
|
|
|
|
|
|
|
|
|
We propose to deprecate the existing ``typing.TypeAlias`` introduced in
|
|
|
|
:pep:`613`. The new syntax eliminates its need entirely.
|
|
|
|
|
|
|
|
|
|
|
|
Runtime Type Alias Class
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
At runtime, a ``type`` statement will generate an instance of
|
|
|
|
``typing.TypeAliasType``. This class represents the type. Its attributes
|
|
|
|
include:
|
|
|
|
|
|
|
|
* ``__name__`` is a str representing the name of the type alias
|
2022-07-12 00:04:34 -04:00
|
|
|
* ``__parameters__`` is a tuple of ``TypeVar``, ``TypeVarTuple``, or
|
2022-09-14 00:26:28 -04:00
|
|
|
``ParamSpec`` objects that parameterize the type alias if it is generic
|
2022-07-02 22:20:44 -04:00
|
|
|
* ``__value__`` is the evaluated value of the type alias
|
|
|
|
|
|
|
|
The ``__value__`` attribute initially has a value of ``None`` while the type
|
|
|
|
alias expression is evaluated. It is then updated after a successful evaluation.
|
|
|
|
This allows for self-referential type aliases.
|
|
|
|
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
Type Parameter Scopes
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
When the new syntax is used, a new lexical scope is introduced, and this scope
|
|
|
|
includes the type parameters. Type parameters can be accessed by name
|
|
|
|
within inner scopes. As with other symbols in Python, an inner scope can
|
|
|
|
define its own symbol that overrides an outer-scope symbol of the same name.
|
|
|
|
|
|
|
|
Type parameters declared earlier in a type parameter list are visible to
|
|
|
|
type parameters declared later in the list. This allows later type parameters
|
|
|
|
to use earlier type parameters within their definition. While there is currently
|
|
|
|
no use for this capability, it preserves the ability in the future to support
|
|
|
|
upper bound expressions or type argument defaults that depend on earlier
|
|
|
|
type parameters.
|
|
|
|
|
|
|
|
A compiler error or runtime exception is generated if the definition of an
|
|
|
|
earlier type parameter references a later type parameter even if the name is
|
|
|
|
defined in an outer scope.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
# The following generates no compiler error, but a type checker
|
|
|
|
# should generate an error because an upper bound type must be concrete,
|
|
|
|
# and ``Sequence[S]`` is generic. Future extensions to the type system may
|
|
|
|
# eliminate this limitation.
|
|
|
|
class ClassA[S, T: Sequence[S]]: ...
|
|
|
|
|
|
|
|
# The following generates a compiler error or runtime exception because T
|
|
|
|
# is referenced before it is defined. This occurs even though T is defined
|
|
|
|
# in the outer scope.
|
|
|
|
T = 0
|
|
|
|
class ClassB[S: Sequence[T], T]: ... # Compiler error: T is not defined
|
|
|
|
|
|
|
|
|
|
|
|
A type parameter declared as part of a generic class is valid within the
|
|
|
|
class body and inner scopes contained therein. Type parameters are also
|
|
|
|
accessible when evaluating the argument list (base classes and any keyword
|
|
|
|
arguments) that comprise the class definition. This allows base classes
|
|
|
|
to be parameterized by these type parameters. Type parameters are not
|
|
|
|
accessible outside of the class body, including class decorators.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T](BaseClass[T], param = Foo[T]): ... # OK
|
|
|
|
|
|
|
|
print(T) # Runtime error: 'T' is not defined
|
|
|
|
|
|
|
|
@dec(Foo[T]) # Runtime error: 'T' is not defined
|
|
|
|
class ClassA[T]: ...
|
|
|
|
|
|
|
|
|
|
|
|
A type parameter declared as part of a generic function is valid within
|
|
|
|
the function body and any scopes contained therein. It is also valid within
|
|
|
|
parameter and return type annotations. Default argument values for function
|
|
|
|
parameters are evaluated outside of this scope, so type parameters are
|
|
|
|
not accessible in default value expressions. Likewise, type parameters are not
|
|
|
|
in scope for function decorators.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
def func1[T](a: T) -> T: ... # OK
|
|
|
|
|
|
|
|
print(T) # Runtime error: 'T' is not defined
|
|
|
|
|
|
|
|
def func2[T](a = list[T]): ... # Runtime error: 'T' is not defined
|
|
|
|
|
|
|
|
@dec(list[T]) # Runtime error: 'T' is not defined
|
|
|
|
def func3[T](): ...
|
|
|
|
|
|
|
|
A type parameter declared as part of a generic type alias is valid within
|
|
|
|
the type alias expression.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
type Alias1[K, V] = Mapping[K, V] | Sequence[K]
|
|
|
|
|
|
|
|
|
|
|
|
Type parameter symbols defined in outer scopes cannot be bound with
|
|
|
|
``nonlocal`` statements in inner scopes.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
S = 0
|
|
|
|
|
|
|
|
def outer1[S]():
|
|
|
|
S = 1
|
|
|
|
T = 1
|
|
|
|
|
|
|
|
def outer2[T]():
|
|
|
|
|
|
|
|
def inner1():
|
|
|
|
nonlocal S # OK because it binds variable S from outer1
|
|
|
|
nonlocal T # Syntax error: nonlocal binding not allowed for type parameter
|
|
|
|
|
|
|
|
def inner2():
|
|
|
|
global S # OK because it binds variable S from global scope
|
|
|
|
|
|
|
|
|
|
|
|
The lexical scope introduced by the new type parameter syntax is unlike
|
|
|
|
traditional scopes introduced by a ``def`` or ``class`` statement. A type
|
|
|
|
parameter scope acts more like a temporary "overlay" to the containing scope.
|
|
|
|
It does not capture variables from outer scopes, and the only symbols contained
|
|
|
|
within its symbol table are the type parameters defined using the new syntax.
|
|
|
|
References to all other symbols are treated as though they were found within
|
|
|
|
the containing scope. This allows base class lists (in class definitions) and
|
|
|
|
type annotation expressions (in function definitions) to reference symbols
|
|
|
|
defined in the containing scope.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class Outer:
|
|
|
|
class Private:
|
|
|
|
pass
|
|
|
|
|
|
|
|
# If the type parameter scope was like a traditional scope,
|
|
|
|
# the base class 'Private' would not be accessible here.
|
|
|
|
class Inner[T](Private, Sequence[T]):
|
|
|
|
pass
|
|
|
|
|
|
|
|
# Likewise, 'Inner' would not be available in these type annotations.
|
|
|
|
def method1[T](self, a: Inner[T]) -> Inner[T]:
|
|
|
|
return a
|
|
|
|
|
|
|
|
|
|
|
|
The compiler allows inner scopes to define a local symbol that overrides an
|
|
|
|
outer-scoped type parameter.
|
|
|
|
|
|
|
|
Consistent with the scoping rules defined in :pep:`484`, type checkers should
|
|
|
|
generate an error if inner-scoped generic classes, functions, or type aliases
|
|
|
|
reuse the same type parameter name as an outer scope.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
T = 0
|
|
|
|
|
|
|
|
@decorator(T) # Argument expression `T` evaluates to 0
|
|
|
|
class ClassA[T](Sequence[T]):
|
|
|
|
T = 1
|
|
|
|
|
|
|
|
# All methods below should result in a type checker error
|
|
|
|
# "type parameter 'T' already in use" because they are using the
|
|
|
|
# type parameter 'T', which is already in use by the outer scope
|
|
|
|
# 'ClassA'.
|
|
|
|
def method1[T](self):
|
|
|
|
...
|
|
|
|
|
|
|
|
def method2[T](self, x = T): # Parameter 'x' gets default value of 1
|
|
|
|
...
|
|
|
|
|
|
|
|
def method3[T](self, x: T): # Parameter 'x' has type T (scoped to method3)
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
|
|
Symbols referenced in inner scopes are resolved using existing rules except
|
|
|
|
that type parameter scopes are also considered during name resolution.
|
|
|
|
|
|
|
|
::
|
2022-11-06 10:54:48 -05:00
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
T = 0
|
|
|
|
|
|
|
|
# T refers to the global variable
|
|
|
|
print(T) # Prints 0
|
|
|
|
|
|
|
|
class Outer[T]:
|
|
|
|
T = 1
|
|
|
|
|
|
|
|
# T refers to the local variable scoped to class 'Outer'
|
|
|
|
print(T) # Prints 1
|
|
|
|
|
|
|
|
class Inner1:
|
|
|
|
T = 2
|
|
|
|
|
|
|
|
# T refers to the local type variable within 'Inner1'
|
|
|
|
print(T) # Prints 2
|
|
|
|
|
|
|
|
def inner_method(self):
|
|
|
|
# T refers to the type parameter scoped to class 'Outer';
|
|
|
|
# If 'Outer' did not use the new type parameter syntax,
|
|
|
|
# this would instead refer to the global variable 'T'
|
|
|
|
print(T) # Prints 'T'
|
|
|
|
|
|
|
|
def outer_method(self):
|
|
|
|
T = 3
|
|
|
|
|
|
|
|
# T refers to the local variable within 'outer_method'
|
|
|
|
print(T) # Prints 3
|
|
|
|
|
|
|
|
def inner_func():
|
|
|
|
# T refers to the variable captured from 'outer_method'
|
|
|
|
print(T) # Prints 3
|
|
|
|
|
|
|
|
|
|
|
|
When the new type parameter syntax is used for a generic class, assignment
|
|
|
|
expressions are not allowed within the argument list for the class definition.
|
|
|
|
Likewise, with functions that use the new type parameter syntax, assignment
|
|
|
|
expressions are not allowed within parameter or return type annotations, nor
|
|
|
|
are they allowed within the expression that defines a type alias.
|
|
|
|
|
|
|
|
This restriction is necessary because expressions evaluated within the
|
|
|
|
new lexical scope should not introduce symbols within that scope other than
|
|
|
|
the defined type parameters.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T]((x := Sequence[T])): ... # Syntax error: assignment expression not allowed
|
|
|
|
|
|
|
|
def func1[T](val: (x := int)): ... # Syntax error: assignment expression not allowed
|
|
|
|
|
|
|
|
def func2[T]() -> (x := Sequence[T]): ... # Syntax error: assignment expression not allowed
|
|
|
|
|
|
|
|
type Alias1[T] = (x := list[T]) # Syntax error: assignment expression not allowed
|
|
|
|
|
|
|
|
|
|
|
|
Accessing Type Parameters at Runtime
|
|
|
|
------------------------------------
|
|
|
|
|
|
|
|
A new read-only attribute called ``__type_variables__`` is available on class,
|
|
|
|
function, and type alias objects. This attribute is a tuple of the active
|
|
|
|
type variables that are visible within the scope of that class, function,
|
|
|
|
or type alias. This attribute is needed for runtime evaluation of stringified
|
|
|
|
(forward referenced) type annotations that include references to type
|
|
|
|
parameters. Functions like ``typing.get_type_hints`` can use this attribute
|
|
|
|
to populate the ``locals`` dictionary with values for type parameters that
|
|
|
|
are in scope when calling ``eval`` to evaluate the stringified expression.
|
|
|
|
The tuple contains ``TypeVar`` instances.
|
|
|
|
|
|
|
|
Type parameters declared using the new syntax will not appear within the
|
|
|
|
dictionary returned by ``globals()`` or ``locals()``.
|
|
|
|
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
Variance Inference
|
|
|
|
------------------
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
This PEP eliminates the need for variance to be specified for type
|
2022-07-02 22:20:44 -04:00
|
|
|
parameters. Instead, type checkers will infer the variance of type parameters
|
2022-09-14 00:26:28 -04:00
|
|
|
based on their usage within a class. Type parameters are inferred to be
|
|
|
|
invariant, covariant, or contravariant depending on how they are used.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Python type checkers already include the ability to determine the variance of
|
|
|
|
type parameters for the purpose of validating variance within a generic
|
|
|
|
protocol class. This capability can be used for all classes (whether or not
|
2022-09-14 00:26:28 -04:00
|
|
|
they are protocols) to calculate the variance of each type parameter.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
The algorithm for computing the variance of a type parameter is as follows.
|
|
|
|
|
|
|
|
For each type parameter in a generic class:
|
|
|
|
|
|
|
|
1. If the type parameter is variadic (``TypeVarTuple``) or a parameter
|
|
|
|
specification (``ParamSpec``), it is always considered invariant. No further
|
|
|
|
inference is needed.
|
|
|
|
|
|
|
|
2. If the type parameter comes from a traditional ``TypeVar`` declaration and
|
2022-09-14 00:26:28 -04:00
|
|
|
is not specified as ``infer_variance`` (see below), its variance is specified
|
2022-07-02 22:20:44 -04:00
|
|
|
by the ``TypeVar`` constructor call. No further inference is needed.
|
|
|
|
|
|
|
|
3. Create two specialized versions of the class. We'll refer to these as
|
|
|
|
``upper`` and ``lower`` specializations. In both of these specializations,
|
|
|
|
replace all type parameters other than the one being inferred by a dummy type
|
2022-09-14 00:26:28 -04:00
|
|
|
instance (a concrete anonymous class that is type compatible with itself and
|
|
|
|
assumed to meet the bounds or constraints of the type parameter). In
|
|
|
|
the ``upper`` specialized class, specialize the target type parameter with
|
|
|
|
an ``object`` instance. This specialization ignores the type parameter's
|
|
|
|
upper bound or constraints. In the ``lower`` specialized class, specialize
|
|
|
|
the target type parameter with itself (i.e. the corresponding type argument
|
|
|
|
is the type parameter itself).
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
4. Determine whether ``lower`` can be assigned to ``upper`` using normal type
|
|
|
|
compatibility rules. If so, the target type parameter is covariant. If not,
|
|
|
|
determine whether ``upper`` can be assigned to ``lower``. If so, the target
|
|
|
|
type parameter is contravariant. If neither of these combinations are
|
|
|
|
assignable, the target type parameter is invariant.
|
|
|
|
|
|
|
|
Here is an example.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
class ClassA[T1, T2, T3](list[T1]):
|
|
|
|
def method1(self, a: T2) -> None:
|
|
|
|
...
|
|
|
|
|
|
|
|
def method2(self) -> T3:
|
|
|
|
...
|
|
|
|
|
|
|
|
To determine the variance of ``T1``, we specialize ``ClassA`` as follows:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
upper = ClassA[object, Dummy, Dummy]
|
|
|
|
lower = ClassA[T1, Dummy, Dummy]
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
We find that ``upper`` is not assignable to ``lower`` using normal type
|
|
|
|
compatibility rules defined in :pep:`484`. Likewise, ``lower`` is not assignable
|
|
|
|
to ``upper``, so we conclude that ``T1`` is invariant.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
To determine the variance of ``T2``, we specialize ``ClassA`` as follows:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
upper = ClassA[Dummy, object, Dummy]
|
|
|
|
lower = ClassA[Dummy, T2, Dummy]
|
|
|
|
|
|
|
|
Since ``upper`` is assignable to ``lower``, ``T2`` is contravariant.
|
|
|
|
|
|
|
|
To determine the variance of ``T3``, we specialize ``ClassA`` as follows:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
upper = ClassA[Dummy, Dummy, object]
|
|
|
|
lower = ClassA[Dummy, Dummy, T3]
|
|
|
|
|
|
|
|
Since ``lower`` is assignable to ``upper``, ``T3`` is covariant.
|
|
|
|
|
|
|
|
|
|
|
|
Auto Variance For TypeVar
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
The existing ``TypeVar`` class constructor accepts keyword parameters named
|
|
|
|
``covariant`` and ``contravariant``. If both of these are ``False``, the
|
|
|
|
type variable is assumed to be invariant. We propose to add another keyword
|
2022-09-14 00:26:28 -04:00
|
|
|
parameter named ``infer_variance`` indicating that a type checker should use
|
|
|
|
inference to determine whether the type variable is invariant, covariant or
|
|
|
|
contravariant. A corresponding instance variable ``__infer_variance__`` can be
|
|
|
|
accessed at runtime to determine whether the variance is inferred. Type
|
|
|
|
variables that are implicitly allocated using the new syntax will always
|
|
|
|
have ``__infer_variance__`` set to ``True``.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
A generic class that uses the traditional syntax may include combinations of
|
|
|
|
type variables with explicit and inferred variance.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
T1 = TypeVar("T1", infer_variance=True) # Inferred variance
|
2022-07-02 22:20:44 -04:00
|
|
|
T2 = TypeVar("T2") # Invariant
|
|
|
|
T3 = TypeVar("T3", covariant=True) # Covariant
|
|
|
|
|
|
|
|
# A type checker should infer the variance for T1 but use the
|
|
|
|
# specified variance for T2 and T3.
|
|
|
|
class ClassA(Generic[T1, T2, T3]): ...
|
|
|
|
|
|
|
|
|
|
|
|
Compatibility with Traditional TypeVars
|
|
|
|
---------------------------------------
|
|
|
|
|
|
|
|
The existing mechanism for allocating ``TypeVar``, ``TypeVarTuple``, and
|
|
|
|
``ParamSpec`` is retained for backward compatibility. However, these
|
|
|
|
"traditional" type variables should not be combined with type parameters
|
|
|
|
allocated using the new syntax. Such a combination should be flagged as
|
|
|
|
an error by type checkers. This is necessary because the type parameter
|
|
|
|
order is ambiguous.
|
|
|
|
|
|
|
|
It is OK to combine traditional type variables with new-style type parameters
|
|
|
|
if the class, function, or type alias does not use the new syntax. The
|
|
|
|
new-style type parameters must come from an outer scope in this case.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
K = TypeVar("K")
|
|
|
|
|
|
|
|
class ClassA[V](dict[K, V]): ... # Type checker error
|
|
|
|
|
|
|
|
class ClassB[K, V](dict[K, V]): ... # OK
|
|
|
|
|
|
|
|
class ClassC[V]:
|
|
|
|
# The use of K and V for "method1" is OK because it uses the
|
|
|
|
# "traditional" generic function mechanism where type parameters
|
|
|
|
# are implicit. In this case V comes from an outer scope (ClassC)
|
|
|
|
# and K is introduced implicitly as a type parameter for "method1".
|
|
|
|
def method1(self, a: V, b: K) -> V | K: ...
|
|
|
|
|
|
|
|
# The use of M and K are not allowed for "method2". A type checker
|
|
|
|
# should generate an error in this case because this method uses the
|
|
|
|
# new syntax for type parameters, and all type parameters associated
|
|
|
|
# with the method must be explicitly declared. In this case, ``K``
|
2022-09-14 00:26:28 -04:00
|
|
|
# is not declared by "method2", nor is it supplied by a new-style
|
|
|
|
# type parameter defined in an outer scope.
|
2022-07-02 22:20:44 -04:00
|
|
|
def method2[M](self, a: M, b: K) -> M | K: ...
|
|
|
|
|
|
|
|
|
|
|
|
Runtime Implementation
|
|
|
|
======================
|
|
|
|
|
|
|
|
Grammar Changes
|
|
|
|
---------------
|
|
|
|
|
|
|
|
This PEP introduces a new soft keyword ``type``. It modifies the grammar
|
|
|
|
in the following ways:
|
|
|
|
|
|
|
|
1. Addition of optional type parameter clause in ``class`` and ``def`` statements.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
type_params: '[' t=type_param_seq ']'
|
|
|
|
|
|
|
|
type_param_seq: a[asdl_typeparam_seq*]=','.type_param+ [',']
|
|
|
|
|
|
|
|
type_param:
|
|
|
|
| a=NAME b=[type_param_bound]
|
|
|
|
| '*' a=NAME
|
|
|
|
| '**' a=NAME
|
|
|
|
|
|
|
|
type_param_bound: ":" e=expression
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
# Grammar definitions for class_def_raw and function_def_raw are modified
|
|
|
|
# to reference type_params as an optional syntax element. The definitions
|
|
|
|
# of class_def_raw and function_def_raw are simplified here for brevity.
|
|
|
|
|
|
|
|
class_def_raw: 'class' n=NAME t=[type_params] ...
|
|
|
|
|
|
|
|
function_def_raw: a=[ASYNC] 'def' n=NAME t=[type_params] ...
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
2. Addition of new ``type`` statement for defining type aliases.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
type_alias: "type" n=NAME t=[type_params] '=' b=expression
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
AST Changes
|
|
|
|
-----------
|
|
|
|
|
|
|
|
This PEP introduces a new AST node type called ``TypeAlias``.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
TypeAlias(identifier name, typeparam* typeparams, expr value)
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
It also adds an AST node type that represents a type parameter.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
typeparam = TypeVar(identifier name, expr? bound)
|
|
|
|
| ParamSpec(identifier name)
|
|
|
|
| TypeVarTuple(identifier name)
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
It also modifies existing AST node types ``FunctionDef``, ``AsyncFunctionDef``
|
|
|
|
and ``ClassDef`` to include an additional optional attribute called
|
|
|
|
``typeparam*`` that includes a list of type parameters associated with the
|
|
|
|
function or class.
|
2022-07-12 00:04:34 -04:00
|
|
|
|
|
|
|
|
|
|
|
Library Changes
|
|
|
|
---------------
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-07-12 00:04:34 -04:00
|
|
|
Several classes in the ``typing`` module that are currently implemented in
|
|
|
|
Python must be reimplemented in C. This includes: ``TypeVar``,
|
2022-09-14 00:26:28 -04:00
|
|
|
``TypeVarTuple``, ``ParamSpec``, ``Generic``, and ``Union``. The new class
|
|
|
|
``TypeAliasType`` (described above) also must be implemented in C. The
|
|
|
|
documented behaviors of these classes should not change.
|
2022-07-12 00:04:34 -04:00
|
|
|
|
|
|
|
The ``typing.get_type_hints`` must be updated to use the new
|
|
|
|
``__type_variables__`` attribute.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Reference Implementation
|
|
|
|
========================
|
|
|
|
|
2022-09-14 00:26:28 -04:00
|
|
|
This proposal is partially prototyped in the CPython code base in
|
2022-07-12 00:04:34 -04:00
|
|
|
`this fork <https://github.com/erictraut/cpython/tree/type_param_syntax2>`_.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
The Pyright type checker supports the behavior described in this PEP.
|
|
|
|
|
|
|
|
|
|
|
|
Rejected Ideas
|
|
|
|
==============
|
|
|
|
|
|
|
|
Prefix Clause
|
|
|
|
-------------
|
|
|
|
We explored various syntactic options for specifying type parameters that
|
|
|
|
preceded ``def`` and ``class`` statements. One such variant we considered
|
|
|
|
used a ``using`` clause as follows:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
using S, T
|
|
|
|
class ClassA: ...
|
|
|
|
|
|
|
|
This option was rejected because the scoping rules for the type parameters
|
|
|
|
were less clear. Also, this syntax did not interact well with class and
|
|
|
|
function decorators, which are common in Python. Only one other popular
|
|
|
|
programming language, C++, uses this approach.
|
|
|
|
|
2022-07-14 19:58:30 -04:00
|
|
|
We likewise considered prefix forms that looked like decorators (e.g.,
|
|
|
|
``@using(S, T)``). This idea was rejected because such forms would be confused
|
|
|
|
with regular decorators, and they would not compose well with existing
|
|
|
|
decorators. Furthermore, decorators are logically executed after the statement
|
|
|
|
they are decorating, so it would be confusing for them to introduce symbols
|
|
|
|
(type parameters) that are visible within the "decorated" statement, which is
|
|
|
|
logically executed before the decorator itself.
|
|
|
|
|
|
|
|
|
|
|
|
Angle Brackets
|
|
|
|
--------------
|
|
|
|
Many languages that support generics make use of angle brackets. (Refer to
|
|
|
|
the table at the end of Appendix A for a summary.) We explored the use of
|
|
|
|
angle brackets for type parameter declarations in Python, but we ultimately
|
|
|
|
rejected it for two reasons. First, angle brackets are not considered
|
|
|
|
"paired" by the Python scanner, so end-of-line characters between a ``<``
|
|
|
|
and ``>`` token are retained. That means any line breaks within a list of
|
|
|
|
type parameters would require the use of unsightly and cumbersome ``\`` escape
|
|
|
|
sequences. Second, Python has already established the use of square brackets
|
|
|
|
for explicit specialization of a generic type (e.g., ``list[int]``). We
|
|
|
|
concluded that it would be inconsistent and confusing to use angle brackets
|
|
|
|
for generic declarations but square brackets for explicit specialization. All
|
|
|
|
other languages that we surveyed were consistent in this regard.
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-07-12 00:04:34 -04:00
|
|
|
Bounds Syntax
|
|
|
|
-------------
|
|
|
|
We explored various syntactic options for specifying the bounds and constraints
|
|
|
|
for a type variable. We considered, but ultimately rejected, the use
|
|
|
|
of a ``<:`` token like in Scala, the use of an ``extends`` or ``with``
|
|
|
|
keyword like in various other languages, and the use of a function call
|
|
|
|
syntax similar to today's ``typing.TypeVar`` constructor. The simple colon
|
|
|
|
syntax is consistent with many other programming languages (see Appendix A),
|
|
|
|
and it was heavily preferred by a cross section of Python developers who
|
|
|
|
were surveyed.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Explicit Variance
|
|
|
|
-----------------
|
|
|
|
We considered adding syntax for specifying whether a type parameter is intended
|
|
|
|
to be invariant, covariant, or contravariant. The ``typing.TypeVar`` mechanism
|
|
|
|
in Python requires this. A few other languages including Scala and C#
|
|
|
|
also require developers to specify the variance. We rejected this idea because
|
|
|
|
variance can generally be inferred, and most modern programming languages
|
|
|
|
do infer variance based on usage. Variance is an advanced topic that
|
|
|
|
many developers find confusing, so we want to eliminate the need to
|
|
|
|
understand this concept for most Python developers.
|
|
|
|
|
|
|
|
|
|
|
|
Name Mangling
|
|
|
|
-------------
|
|
|
|
When considering implementation options, we considered a "name mangling"
|
|
|
|
approach where each type parameter was given a unique "mangled" name by the
|
|
|
|
compiler. This mangled name would be based on the qualified name of the
|
|
|
|
generic class, function or type alias it was associated with. This approach
|
|
|
|
was rejected because qualified names are not necessarily unique, which means
|
|
|
|
the mangled name would need to be based on some other randomized value.
|
2022-07-12 00:04:34 -04:00
|
|
|
Furthermore, this approach is not compatible with techniques used for
|
|
|
|
evaluating quoted (forward referenced) type annotations.
|
|
|
|
|
|
|
|
|
|
|
|
Lambda Lifting
|
|
|
|
--------------
|
|
|
|
When considering implementation options, we considered introducing a new
|
|
|
|
scope and executing the ``class``, ``def``, or ``type`` statement within
|
|
|
|
a lambda -- a technique that is sometimes referred to as "lambda lifting".
|
|
|
|
We ultimately rejected this idea because it did not work well for statements
|
|
|
|
within a class body (because class-scoped symbols cannot be accessed by
|
|
|
|
inner scopes). It also introduced many odd behaviors for scopes that were
|
|
|
|
further nested within the lambda.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Appendix A: Survey of Type Parameter Syntax
|
|
|
|
===========================================
|
|
|
|
|
|
|
|
Support for generic types is found in many programming languages. In this
|
|
|
|
section, we provide a survey of the options used by other popular programming
|
|
|
|
languages. This is relevant because familiarity with other languages will
|
2022-07-12 00:04:34 -04:00
|
|
|
make it easier for Python developers to understand this concept. We provide
|
|
|
|
additional details here (for example, default type argument support) that
|
|
|
|
may be useful when considering future extensions to the Python type system.
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
C++
|
|
|
|
---
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
C++ uses angle brackets in combination with keywords ``template`` and
|
|
|
|
``typename`` to declare type parameters. It uses angle brackets for
|
2022-07-02 22:20:44 -04:00
|
|
|
specialization.
|
|
|
|
|
|
|
|
C++20 introduced the notion of generalized constraints, which can act
|
|
|
|
like protocols in Python. A collection of constraints can be defined in
|
2022-08-28 13:00:56 -04:00
|
|
|
a named entity called a ``concept``.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Variance is not explicitly specified, but constraints can enforce variance.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
A default type argument can be specified using the ``=`` operator.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: c++
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic class
|
|
|
|
template <typename>
|
|
|
|
class ClassA
|
|
|
|
{
|
|
|
|
// Constraints are supported through compile-time assertions.
|
|
|
|
static_assert(std::is_base_of<BaseClass, T>::value);
|
|
|
|
|
|
|
|
public:
|
|
|
|
Container<T> t;
|
|
|
|
};
|
|
|
|
|
|
|
|
// Generic function with default type argument
|
|
|
|
template <typename S = int>
|
|
|
|
S func1(ClassA<S> a, S b) {};
|
|
|
|
|
|
|
|
// C++20 introduced a more generalized notion of "constraints"
|
|
|
|
// and "concepts", which are named constraints.
|
|
|
|
|
|
|
|
// A sample concept
|
|
|
|
template<typename T>
|
|
|
|
concept Hashable = requires(T a)
|
|
|
|
{
|
|
|
|
{ std::hash<T>{}(a) } -> std::convertible_to<std::size_t>;
|
|
|
|
};
|
|
|
|
|
|
|
|
// Use of a concept in a template
|
|
|
|
template<Hashable T>
|
|
|
|
void func2(T value) {}
|
|
|
|
|
|
|
|
// Alternative use of concept
|
|
|
|
template<typename T> requires Hashable<T>
|
|
|
|
void func3(T value) {}
|
|
|
|
|
|
|
|
// Alternative use of concept
|
|
|
|
template<typename T>
|
|
|
|
void func3(T value) requires Hashable<T> {}
|
|
|
|
|
|
|
|
|
|
|
|
Java
|
|
|
|
----
|
|
|
|
|
|
|
|
Java uses angle brackets to declare type parameters and for specialization.
|
2022-08-28 13:00:56 -04:00
|
|
|
By default, type parameters are invariant.
|
|
|
|
The ``extends`` keyword is used to specify an upper bound. The ``super`` keyword
|
|
|
|
is used to specify a contravariant bound.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Java uses use-site variance. The compiler places limits on which methods and
|
|
|
|
members can be accessed based on the use of a generic type. Variance is
|
|
|
|
not specified explicitly.
|
|
|
|
|
|
|
|
Java provides no way to specify a default type argument.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: java
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic class
|
|
|
|
public class ClassA<T> {
|
|
|
|
public Container<T> t;
|
|
|
|
|
|
|
|
// Generic method
|
|
|
|
public <S extends Number> void method1(S value) { }
|
2022-08-28 13:00:56 -04:00
|
|
|
|
|
|
|
// Use site variance
|
|
|
|
public void method1(ClassA<? super Integer> value) { }
|
2022-07-02 22:20:44 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
C#
|
|
|
|
--
|
|
|
|
|
|
|
|
C# uses angle brackets to declare type parameters and for specialization.
|
2022-08-28 13:00:56 -04:00
|
|
|
The ``where`` keyword and a colon is used to specify the bound for a type
|
2022-07-02 22:20:44 -04:00
|
|
|
parameter.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
C# uses declaration-site variance using the keywords ``in`` and ``out`` for
|
2022-07-02 22:20:44 -04:00
|
|
|
contravariance and covariance, respectively. By default, type parameters are
|
|
|
|
invariant.
|
|
|
|
|
|
|
|
C# provides no way to specify a default type argument.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: c#
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic class with bounds on type parameters
|
|
|
|
public class ClassA<S, T>
|
|
|
|
where T : SomeClass1
|
|
|
|
where S : SomeClass2
|
|
|
|
{
|
|
|
|
// Generic method
|
|
|
|
public void MyMethod<U>(U value) where U : SomeClass3 { }
|
|
|
|
}
|
|
|
|
|
|
|
|
// Contravariant and covariant type parameters
|
|
|
|
public class ClassB<in S, out T>
|
|
|
|
{
|
|
|
|
public T MyMethod(S value) { }
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TypeScript
|
|
|
|
----------
|
|
|
|
|
|
|
|
TypeScript uses angle brackets to declare type parameters and for
|
2022-08-28 13:00:56 -04:00
|
|
|
specialization. The ``extends`` keyword is used to specify a bound. It can be
|
|
|
|
combined with other type operators such as ``keyof``.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
TypeScript uses declaration-site variance. Variance is inferred from
|
2022-08-28 13:00:56 -04:00
|
|
|
usage, not specified explicitly. TypeScript 4.7 introduced the ability
|
|
|
|
to specify variance using ``in`` and ``out`` keywords. This was added to handle
|
2022-09-14 00:26:28 -04:00
|
|
|
extremely complex types where inference of variance was expensive.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
A default type argument can be specified using the ``=`` operator.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
TypeScript supports the ``type`` keyword to declare a type alias, and this
|
2022-07-02 22:20:44 -04:00
|
|
|
syntax supports generics.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: typescript
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic interface
|
|
|
|
interface InterfaceA<S, T extends SomeInterface1> {
|
|
|
|
val1: S;
|
|
|
|
val2: T;
|
|
|
|
|
2022-07-24 19:59:02 -04:00
|
|
|
method1<U extends SomeInterface2>(val: U): S
|
2022-07-02 22:20:44 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
// Generic function
|
|
|
|
function func1<T, K extends keyof T>(ojb: T, key: K) { }
|
|
|
|
|
|
|
|
// Contravariant and covariant type parameters (TypeScript 4.7)
|
|
|
|
interface InterfaceB<in S, out T> { }
|
|
|
|
|
|
|
|
// Type parameter with default
|
|
|
|
interface InterfaceC<T = SomeInterface3> { }
|
|
|
|
|
|
|
|
// Generic type alias
|
2022-07-24 19:59:02 -04:00
|
|
|
type MyType<T extends SomeInterface4> = Array<T>
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Scala
|
|
|
|
-----
|
|
|
|
|
|
|
|
In Scala, square brackets are used to declare type parameters. Square
|
2022-08-28 13:00:56 -04:00
|
|
|
brackets are also used for specialization. The ``<:`` and ``>:`` operators
|
2022-07-02 22:20:44 -04:00
|
|
|
are used to specify upper and lower bounds, respectively.
|
|
|
|
|
|
|
|
Scala uses use-site variance but also allows declaration-site variance
|
2022-08-28 13:00:56 -04:00
|
|
|
specification. It uses a ``+`` or ``-`` prefix operator for covariance and
|
2022-07-02 22:20:44 -04:00
|
|
|
contravariance, respectively.
|
|
|
|
|
|
|
|
Scala provides no way to specify a default type argument.
|
|
|
|
|
|
|
|
It does support higher-kinded types (type parameters that accept type
|
|
|
|
type parameters).
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: scala
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
// Generic class; type parameter has upper bound
|
|
|
|
class ClassA[A <: SomeClass1]
|
|
|
|
{
|
|
|
|
// Generic method; type parameter has lower bound
|
|
|
|
def method1[B >: A](val: B) ...
|
|
|
|
}
|
|
|
|
|
|
|
|
// Use of an upper and lower bound with the same type parameter
|
|
|
|
class ClassB[A >: SomeClass1 <: SomeClass2] { }
|
|
|
|
|
|
|
|
// Contravariant and covariant type parameters
|
|
|
|
class ClassC[+A, -B] { }
|
|
|
|
|
|
|
|
// Higher-kinded type
|
|
|
|
trait Collection[T[_]]
|
|
|
|
{
|
|
|
|
def method1[A](a: A): T[A]
|
|
|
|
def method2[B](b: T[B]): B
|
|
|
|
}
|
|
|
|
|
|
|
|
// Generic type alias
|
|
|
|
type MyType[T <: Int] = Container[T]
|
|
|
|
|
|
|
|
|
|
|
|
Swift
|
|
|
|
-----
|
|
|
|
|
|
|
|
Swift uses angle brackets to declare type parameters and for specialization.
|
|
|
|
The upper bound of a type parameter is specified using a colon.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
Swift doesn't support generic variance; all type parameters are invariant.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Swift provides no way to specify a default type argument.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: swift
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic class
|
|
|
|
class ClassA<T> {
|
|
|
|
// Generic method
|
2022-08-28 13:00:56 -04:00
|
|
|
func method1<X>(val: T) -> X { }
|
2022-07-02 22:20:44 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
// Type parameter with upper bound constraint
|
|
|
|
class ClassB<T: SomeClass1> {}
|
|
|
|
|
|
|
|
// Generic type alias
|
|
|
|
typealias MyType<A> = Container<A>
|
|
|
|
|
|
|
|
|
|
|
|
Rust
|
|
|
|
----
|
|
|
|
|
|
|
|
Rust uses angle brackets to declare type parameters and for specialization.
|
|
|
|
The upper bound of a type parameter is specified using a colon. Alternatively
|
2022-08-28 13:00:56 -04:00
|
|
|
a ``where`` clause can specify various constraints.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
Rust does not have traditional object oriented inheritance or variance.
|
|
|
|
Subtyping in Rust is very restricted and occurs only due to variance with
|
|
|
|
respect to lifetimes.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
A default type argument can be specified using the ``=`` operator.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: rust
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic class
|
2022-08-28 13:00:56 -04:00
|
|
|
struct StructA<T> { // T's lifetime is inferred as covariant
|
2022-07-02 22:20:44 -04:00
|
|
|
x: T
|
|
|
|
}
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
fn f<'a>(
|
|
|
|
mut short_lifetime: StructA<&'a i32>,
|
|
|
|
mut long_lifetime: StructA<&'static i32>,
|
|
|
|
) {
|
|
|
|
long_lifetime = short_lifetime;
|
|
|
|
// error: StructA<&'a i32> is not a subtype of StructA<&'static i32>
|
|
|
|
short_lifetime = long_lifetime;
|
|
|
|
// valid: StructA<&'static i32> is a subtype of StructA<&'a i32>
|
|
|
|
}
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
// Type parameter with bound
|
2022-08-28 13:00:56 -04:00
|
|
|
struct StructB<T: SomeTrait> {}
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Type parameter with additional constraints
|
|
|
|
struct StructC<T>
|
|
|
|
where
|
|
|
|
T: Iterator,
|
|
|
|
T::Item: Copy
|
|
|
|
{}
|
|
|
|
|
|
|
|
// Generic function
|
|
|
|
fn func1<T>(val: &[T]) -> T { }
|
|
|
|
|
|
|
|
// Generic type alias
|
2022-08-28 13:00:56 -04:00
|
|
|
type MyType<T> = StructC<T>;
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Kotlin
|
|
|
|
------
|
|
|
|
|
|
|
|
Kotlin uses angle brackets to declare type parameters and for specialization.
|
2022-08-28 13:00:56 -04:00
|
|
|
By default, type parameters are invariant. The upper bound of a type is
|
|
|
|
specified using a colon.
|
|
|
|
Alternatively, a ``where`` clause can specify various constraints.
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Kotlin supports declaration-site variance where variance of type parameters is
|
2022-08-28 13:00:56 -04:00
|
|
|
explicitly declared using ``in`` and ``out`` keywords. It also supports use-site
|
2022-07-02 22:20:44 -04:00
|
|
|
variance which limits which methods and members can be used.
|
|
|
|
|
|
|
|
Kotlin provides no way to specify a default type argument.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: kotlin
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic class
|
2022-08-28 13:00:56 -04:00
|
|
|
class ClassA<T>
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Type parameter with upper bound
|
2022-08-28 13:00:56 -04:00
|
|
|
class ClassB<T : SomeClass1>
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Contravariant and covariant type parameters
|
2022-08-28 13:00:56 -04:00
|
|
|
class ClassC<in S, out T>
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic function
|
2022-08-28 13:00:56 -04:00
|
|
|
fun <T> func1(): T {
|
|
|
|
|
|
|
|
// Use site variance
|
|
|
|
val covariantA: ClassA<out Number>
|
|
|
|
val contravariantA: ClassA<in Number>
|
|
|
|
}
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic type alias
|
2022-08-28 13:00:56 -04:00
|
|
|
typealias TypeAliasFoo<T> = ClassA<T>
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
|
|
|
|
Julia
|
|
|
|
-----
|
|
|
|
|
|
|
|
Julia uses curly braces to declare type parameters and for specialization.
|
2022-08-28 13:00:56 -04:00
|
|
|
The ``<:`` operator can be used within a ``where`` clause to declare
|
2022-07-02 22:20:44 -04:00
|
|
|
upper and lower bounds on a type.
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
.. code-block:: julia
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
// Generic struct; type parameter with upper and lower bounds
|
|
|
|
struct StructA{T} where Int <: T <: Number
|
|
|
|
x::T
|
|
|
|
end
|
|
|
|
|
|
|
|
// Generic function
|
|
|
|
function func1{T <: Real}(v::Container{T})
|
|
|
|
|
|
|
|
// Alternate form of generic function
|
|
|
|
function func2(v::Container{T} where T <: Real)
|
|
|
|
|
2022-08-28 13:00:56 -04:00
|
|
|
Dart
|
|
|
|
----
|
|
|
|
|
|
|
|
Dart uses angle brackets to declare type parameters and for specialization.
|
|
|
|
The upper bound of a type is specified using the ``extends`` keyword.
|
|
|
|
By default, type parameters are covariant.
|
|
|
|
|
|
|
|
Dart supports declaration-site variance, where variance of type parameters is
|
|
|
|
explicitly declared using ``in``, ``out`` and ``inout`` keywords.
|
|
|
|
It does not support use-site variance.
|
|
|
|
|
|
|
|
Dart provides no way to specify a default type argument.
|
|
|
|
|
|
|
|
.. code-block:: dart
|
|
|
|
|
|
|
|
// Generic class
|
|
|
|
class ClassA<T> { }
|
|
|
|
|
|
|
|
// Type parameter with upper bound
|
|
|
|
class ClassB<T extends SomeClass1> { }
|
|
|
|
|
|
|
|
// Contravariant and covariant type parameters
|
|
|
|
class ClassC<in S, out T> { }
|
|
|
|
|
|
|
|
// Generic function
|
|
|
|
T func1<T>() { }
|
|
|
|
|
|
|
|
// Generic type alias
|
|
|
|
typedef TypeDefFoo<T> = ClassA<T>;
|
|
|
|
|
|
|
|
Go
|
|
|
|
--
|
|
|
|
|
|
|
|
Go uses square brackets to declare type parameters and for specialization.
|
|
|
|
The upper bound of a type is specified after the name of the parameter, and
|
|
|
|
must always be specified. The keyword ``any`` is used for an unbound type parameter.
|
|
|
|
|
|
|
|
Go doesn't support variance; all type parameters are invariant.
|
|
|
|
|
|
|
|
Go provides no way to specify a default type argument.
|
|
|
|
|
|
|
|
Go does not support generic type aliases.
|
|
|
|
|
|
|
|
.. code-block:: go
|
|
|
|
|
|
|
|
// Generic type without a bound
|
|
|
|
type TypeA[T any] struct {
|
|
|
|
t T
|
|
|
|
}
|
|
|
|
|
|
|
|
// Type parameter with upper bound
|
|
|
|
type TypeB[T SomeType1] struct { }
|
|
|
|
|
|
|
|
// Generic function
|
|
|
|
func func1[T any]() { }
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
|
|
|
|
Summary
|
|
|
|
-------
|
|
|
|
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
| | Decl | Upper | Lower | Default | Variance | Variance |
|
|
|
|
| | Syntax | Bound | Bound | Value | Site | |
|
|
|
|
+============+==========+=========+========+==========+===========+===========+
|
|
|
|
| C++ | template | n/a | n/a | = | n/a | n/a |
|
|
|
|
| | <> | | | | | |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
2022-08-28 13:00:56 -04:00
|
|
|
| Java | <> | extends | | | use | super, |
|
|
|
|
| | | | | | | extends |
|
2022-07-02 22:20:44 -04:00
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
| C# | <> | where | | | decl | in, out |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
| TypeScript | <> | extends | | = | decl | inferred, |
|
|
|
|
| | | | | | | in, out |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
| Scala | [] | T <: X | T >: X | | use, decl | +, - |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
2022-08-28 13:00:56 -04:00
|
|
|
| Swift | <> | T: X | | | n/a | n/a |
|
2022-07-02 22:20:44 -04:00
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
2022-08-28 13:00:56 -04:00
|
|
|
| Rust | <> | T: X, | | = | n/a | n/a |
|
|
|
|
| | | where | | | | |
|
2022-07-02 22:20:44 -04:00
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
2022-08-28 13:00:56 -04:00
|
|
|
| Kotlin | <> | T: X, | | | use, decl | in, out |
|
|
|
|
| | | where | | | | |
|
2022-07-02 22:20:44 -04:00
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
| Julia | {} | T <: X | X <: T | | n/a | n/a |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
2022-08-28 13:00:56 -04:00
|
|
|
| Dart | <> | extends | | | decl | in, out, |
|
|
|
|
| | | | | | | inout |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
| Go | [] | T X | | | n/a | n/a |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
2022-07-02 22:20:44 -04:00
|
|
|
| Python | [] | T: X | | | decl | inferred |
|
|
|
|
| (proposed) | | | | | | |
|
|
|
|
+------------+----------+---------+--------+----------+-----------+-----------+
|
|
|
|
|
|
|
|
|
2022-07-12 00:04:34 -04:00
|
|
|
Acknowledgements
|
|
|
|
================
|
|
|
|
|
|
|
|
Thanks to Sebastian Rittau for kick-starting the discussions that led to this
|
|
|
|
proposal, to Jukka Lehtosalo for proposing the syntax for type alias
|
|
|
|
statements and to Jelle Zijlstra, Daniel Moisset, and Guido van Rossum
|
|
|
|
for their valuable feedback and suggested improvements to the specification
|
|
|
|
and implementation.
|
|
|
|
|
|
|
|
|
2022-07-02 22:20:44 -04:00
|
|
|
Copyright
|
|
|
|
=========
|
|
|
|
|
|
|
|
This document is placed in the public domain or under the CC0-1.0-Universal
|
|
|
|
license, whichever is more permissive.
|