PEP 483, 484, 585: Use parameterized instead of parametrized (#1318)
Google prefers "parameterize" and PEP 484 uses it in a majority of cases. So does the stdlib. So PEP 585 has to follow.
This commit is contained in:
parent
96d6d4beaa
commit
73b35bb7ff
|
@ -271,7 +271,7 @@ between classes and types the following general rules apply:
|
|||
- No types defined below can be subclassed, except for ``Generic`` and
|
||||
classes derived from it.
|
||||
- All of these will raise ``TypeError`` if they appear
|
||||
in ``isinstance`` or ``issubclass`` (except for unparametrized generics).
|
||||
in ``isinstance`` or ``issubclass`` (except for unparameterized generics).
|
||||
|
||||
|
||||
Fundamental building blocks
|
||||
|
|
|
@ -307,7 +307,7 @@ argument to ``TypeVar()`` must be a string equal to the variable name
|
|||
to which it is assigned. Type variables must not be redefined.
|
||||
|
||||
``TypeVar`` supports constraining parametric types to a fixed set of possible
|
||||
types (note: those types cannot be parametrized by type variables). For
|
||||
types (note: those types cannot be parameterized by type variables). For
|
||||
example, we can define a type variable that ranges over just ``str`` and
|
||||
``bytes``. By default, a type variable ranges over all possible types.
|
||||
Example of constraining a type variable::
|
||||
|
@ -720,7 +720,7 @@ Type variables with an upper bound
|
|||
----------------------------------
|
||||
|
||||
A type variable may specify an upper bound using ``bound=<type>`` (note:
|
||||
<type> itself cannot be parametrized by type variables). This means that an
|
||||
<type> itself cannot be parameterized by type variables). This means that an
|
||||
actual type substituted (explicitly or implicitly) for the type variable must
|
||||
be a subtype of the boundary type. A common example is the definition of a
|
||||
``Comparable`` type that works well enough to catch the most common errors::
|
||||
|
|
46
pep-0585.rst
46
pep-0585.rst
|
@ -34,13 +34,13 @@ and easier for teachers to teach Python.
|
|||
Terminology
|
||||
===========
|
||||
|
||||
Generic (n.) -- a type that can be parametrized, typically a container.
|
||||
Generic (n.) -- a type that can be parameterized, typically a container.
|
||||
Also known as a *parametric type* or a *generic type*. For example:
|
||||
``dict``.
|
||||
|
||||
Parametrized generic -- a specific instance of a generic with the
|
||||
parameterized generic -- a specific instance of a generic with the
|
||||
expected types for container elements provided. Also known as
|
||||
a *parametrized type*. For example: ``dict[str, int]``.
|
||||
a *parameterized type*. For example: ``dict[str, int]``.
|
||||
|
||||
|
||||
Backwards compatibility
|
||||
|
@ -134,7 +134,7 @@ Preserving the generic type at runtime enables introspection of the type
|
|||
which can be used for API generation or runtime type checking. Such
|
||||
usage is already present in the wild.
|
||||
|
||||
Just like with the ``typing`` module today, the parametrized generic
|
||||
Just like with the ``typing`` module today, the parameterized generic
|
||||
types listed in the previous section all preserve their type parameters
|
||||
at runtime::
|
||||
|
||||
|
@ -149,8 +149,8 @@ This is implemented using a thin proxy type that forwards all method
|
|||
calls and attribute accesses to the bare origin type with the following
|
||||
exceptions:
|
||||
|
||||
* the ``__repr__`` shows the parametrized type;
|
||||
* the ``__origin__`` attribute points at the non-parametrized
|
||||
* the ``__repr__`` shows the parameterized type;
|
||||
* the ``__origin__`` attribute points at the non-parameterized
|
||||
generic class;
|
||||
* the ``__args__`` attribute is a tuple (possibly of length
|
||||
1) of generic types passed to the original ``__class_getitem__``;
|
||||
|
@ -161,7 +161,7 @@ exceptions:
|
|||
and in that case returns ``dict[str, int]``.
|
||||
|
||||
This design means that it is possible to create instances of
|
||||
parametrized collections, like::
|
||||
parameterized collections, like::
|
||||
|
||||
>>> l = list[str]()
|
||||
[]
|
||||
|
@ -174,20 +174,20 @@ parametrized collections, like::
|
|||
>>> list[str] == list[int]
|
||||
False
|
||||
>>> isinstance([1, 2, 3], list[str])
|
||||
TypeError: isinstance() arg 2 cannot be a parametrized generic
|
||||
TypeError: isinstance() arg 2 cannot be a parameterized generic
|
||||
>>> issubclass(list, list[str])
|
||||
TypeError: issubclass() arg 2 cannot be a parametrized generic
|
||||
TypeError: issubclass() arg 2 cannot be a parameterized generic
|
||||
>>> isinstance(list[str], types.GenericAlias)
|
||||
True
|
||||
|
||||
Objects created with bare types and parametrized types are exactly the
|
||||
Objects created with bare types and parameterized types are exactly the
|
||||
same. The generic parameters are not preserved in instances created
|
||||
with parametrized types, in other words generic types erase type
|
||||
with parameterized types, in other words generic types erase type
|
||||
parameters during object creation.
|
||||
|
||||
One important consequence of this is that the interpreter does **not**
|
||||
attempt to type check operations on the collection created with
|
||||
a parametrized type. This provides symmetry between::
|
||||
a parameterized type. This provides symmetry between::
|
||||
|
||||
l: list[str] = []
|
||||
|
||||
|
@ -283,16 +283,16 @@ With ``__class_getitem__`` as an identity function::
|
|||
The indexing being successful here would likely end up raising an
|
||||
exception at a distance, confusing the user.
|
||||
|
||||
Disallowing instantiation of parametrized types
|
||||
-----------------------------------------------
|
||||
Disallowing instantiation of parameterized types
|
||||
------------------------------------------------
|
||||
|
||||
Given that the proxy type which preserves ``__origin__`` and
|
||||
``__args__`` is mostly useful for runtime introspection purposes,
|
||||
we might have disallowed instantiation of parametrized types.
|
||||
we might have disallowed instantiation of parameterized types.
|
||||
|
||||
In fact, forbidding instantiation of parametrized types is what the
|
||||
In fact, forbidding instantiation of parameterized types is what the
|
||||
``typing`` module does today for types which parallel builtin
|
||||
collections (instantiation of other parametrized types is allowed).
|
||||
collections (instantiation of other parameterized types is allowed).
|
||||
|
||||
The original reason for this decision was to discourage spurious
|
||||
parametrization which made object creation up to two orders of magnitude
|
||||
|
@ -300,7 +300,7 @@ slower compared to the special syntax available for those builtin
|
|||
collections.
|
||||
|
||||
This rationale is not strong enough to allow the exceptional treatment
|
||||
of builtins. All other parametrized types can be instantiated,
|
||||
of builtins. All other parameterized types can be instantiated,
|
||||
including parallels of collections in the standard library. Moreover,
|
||||
Python allows for instantiation of lists using ``list()`` and some
|
||||
builtin collections don't provide special syntax for instantiation.
|
||||
|
@ -308,13 +308,13 @@ builtin collections don't provide special syntax for instantiation.
|
|||
Making ``isinstance(obj, list[str])`` perform a check ignoring generics
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
An earlier version of this PEP suggested treating parametrized generics
|
||||
like ``list[str]`` as equivalent to their non-parametrized variants
|
||||
An earlier version of this PEP suggested treating parameterized generics
|
||||
like ``list[str]`` as equivalent to their non-parameterized variants
|
||||
like ``list`` for purposes of ``isinstance()`` and ``issubclass()``.
|
||||
This would be symmetrical to how ``list[str]()`` creates a regular list.
|
||||
|
||||
This design was rejected because ``isinstance()`` and ``issubclass()``
|
||||
checks with parametrized generics would read like element-by-element
|
||||
checks with parameterized generics would read like element-by-element
|
||||
runtime type checks. The result of those checks would be surprising,
|
||||
for example::
|
||||
|
||||
|
@ -325,9 +325,9 @@ Note the object doesn't match the provided generic type but
|
|||
``isinstance()`` still returns ``True`` because it only checks whether
|
||||
the object is a list.
|
||||
|
||||
If a library is faced with a parametrized generic and would like to
|
||||
If a library is faced with a parameterized generic and would like to
|
||||
perform an ``isinstance()`` check using the base type, that type can
|
||||
be retrieved using the ``__origin__`` attribute on the parametrized
|
||||
be retrieved using the ``__origin__`` attribute on the parameterized
|
||||
generic.
|
||||
|
||||
Making ``isinstance(obj, list[str])`` perform a runtime type check
|
||||
|
|
Loading…
Reference in New Issue