mirror of
https://github.com/python/cpython
synced 2024-09-16 01:45:23 +00:00
Issue #26141: Update docs for typing.py. Ivan Levkivskyi. (Backport from the 3.6 version)
This commit is contained in:
parent
1816dfe65f
commit
56ff5f7298
|
@ -62,10 +62,12 @@ Type aliases are useful for simplifying complex type signatures. For example::
|
|||
Note that ``None`` as a type hint is a special case and is replaced by
|
||||
``type(None)``.
|
||||
|
||||
.. _distinct:
|
||||
|
||||
NewType
|
||||
-------
|
||||
|
||||
Use the ``NewType`` helper function to create distinct types::
|
||||
Use the :func:`NewType` helper function to create distinct types::
|
||||
|
||||
from typing import NewType
|
||||
|
||||
|
@ -103,7 +105,7 @@ true at runtime.
|
|||
|
||||
This also means that it is not possible to create a subtype of ``Derived``
|
||||
since it is an identity function at runtime, not an actual type. Similarly, it
|
||||
is not possible to create another ``NewType`` based on a ``Derived`` type::
|
||||
is not possible to create another :func:`NewType` based on a ``Derived`` type::
|
||||
|
||||
from typing import NewType
|
||||
|
||||
|
@ -206,7 +208,7 @@ A user-defined class can be defined as a generic class.
|
|||
return self.value
|
||||
|
||||
def log(self, message: str) -> None:
|
||||
self.logger.info('{}: {}'.format(self.name, message))
|
||||
self.logger.info('%s: %s', self.name, message)
|
||||
|
||||
``Generic[T]`` as a base class defines that the class ``LoggedVar`` takes a
|
||||
single type parameter ``T`` . This also makes ``T`` valid as a type within the
|
||||
|
@ -533,10 +535,10 @@ The module defines the following classes, functions and decorators:
|
|||
but should also allow constructor calls in subclasses that match the
|
||||
constructor calls in the indicated base class. How the type checker is
|
||||
required to handle this particular case may change in future revisions of
|
||||
PEP 484.
|
||||
:pep:`484`.
|
||||
|
||||
The only legal parameters for ``Type`` are classes, unions of classes, and
|
||||
``Any``. For example::
|
||||
The only legal parameters for :class:`Type` are classes, unions of classes, and
|
||||
:class:`Any`. For example::
|
||||
|
||||
def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
|
||||
|
||||
|
@ -545,11 +547,15 @@ The module defines the following classes, functions and decorators:
|
|||
|
||||
.. class:: Iterable(Generic[T_co])
|
||||
|
||||
A generic version of the :class:`collections.abc.Iterable`.
|
||||
A generic version of :class:`collections.abc.Iterable`.
|
||||
|
||||
.. class:: Iterator(Iterable[T_co])
|
||||
|
||||
A generic version of the :class:`collections.abc.Iterator`.
|
||||
A generic version of :class:`collections.abc.Iterator`.
|
||||
|
||||
.. class:: Reversible(Iterable[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.Reversible`.
|
||||
|
||||
.. class:: SupportsInt
|
||||
|
||||
|
@ -569,15 +575,18 @@ The module defines the following classes, functions and decorators:
|
|||
An ABC with one abstract method ``__round__``
|
||||
that is covariant in its return type.
|
||||
|
||||
.. class:: Reversible
|
||||
|
||||
An ABC with one abstract method ``__reversed__`` returning
|
||||
an ``Iterator[T_co]``.
|
||||
|
||||
.. class:: Container(Generic[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.Container`.
|
||||
|
||||
.. class:: Hashable
|
||||
|
||||
An alias to :class:`collections.abc.Hashable`
|
||||
|
||||
.. class:: Sized
|
||||
|
||||
An alias to :class:`collections.abc.Sized`
|
||||
|
||||
.. class:: AbstractSet(Sized, Iterable[T_co], Container[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.Set`.
|
||||
|
@ -649,6 +658,18 @@ The module defines the following classes, functions and decorators:
|
|||
|
||||
A generic version of :class:`collections.abc.ValuesView`.
|
||||
|
||||
.. class:: Awaitable(Generic[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.Awaitable`.
|
||||
|
||||
.. class:: AsyncIterable(Generic[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.AsyncIterable`.
|
||||
|
||||
.. class:: AsyncIterator(AsyncIterable[T_co])
|
||||
|
||||
A generic version of :class:`collections.abc.AsyncIterator`.
|
||||
|
||||
.. class:: Dict(dict, MutableMapping[KT, VT])
|
||||
|
||||
A generic version of :class:`dict`.
|
||||
|
@ -657,6 +678,10 @@ The module defines the following classes, functions and decorators:
|
|||
def get_position_in_index(word_list: Dict[str, int], word: str) -> int:
|
||||
return word_list[word]
|
||||
|
||||
.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
|
||||
|
||||
A generic version of :class:`collections.defaultdict`
|
||||
|
||||
.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
|
||||
|
||||
A generator can be annotated by the generic type
|
||||
|
@ -681,7 +706,7 @@ The module defines the following classes, functions and decorators:
|
|||
start += 1
|
||||
|
||||
Alternatively, annotate your generator as having a return type of
|
||||
``Iterator[YieldType]``::
|
||||
either ``Iterable[YieldType]`` or ``Iterator[YieldType]``::
|
||||
|
||||
def infinite_stream(start: int) -> Iterator[int]:
|
||||
while True:
|
||||
|
@ -752,6 +777,15 @@ The module defines the following classes, functions and decorators:
|
|||
are in the _fields attribute, which is part of the namedtuple
|
||||
API.)
|
||||
|
||||
.. function:: NewType(typ)
|
||||
|
||||
A helper function to indicate a distinct types to a typechecker,
|
||||
see :ref:`distinct`. At runtime it returns a function that returns
|
||||
its argument. Usage::
|
||||
|
||||
UserId = NewType('UserId', int)
|
||||
first_user = UserId(1)
|
||||
|
||||
.. function:: cast(typ, val)
|
||||
|
||||
Cast a value to a type.
|
||||
|
@ -769,6 +803,34 @@ The module defines the following classes, functions and decorators:
|
|||
forward references encoded as string literals, and if necessary
|
||||
adds ``Optional[t]`` if a default value equal to None is set.
|
||||
|
||||
.. decorator:: overload
|
||||
|
||||
The ``@overload`` decorator allows describing functions and methods
|
||||
that support multiple different combinations of argument types. A series
|
||||
of ``@overload``-decorated definitions must be followed by exactly one
|
||||
non-``@overload``-decorated definition (for the same function/method).
|
||||
The ``@overload``-decorated definitions are for the benefit of the
|
||||
type checker only, since they will be overwritten by the
|
||||
non-``@overload``-decorated definition, while the latter is used at
|
||||
runtime but should be ignored by a type checker. At runtime, calling
|
||||
a ``@overload``-decorated function directly will raise
|
||||
``NotImplementedError``. An example of overload that gives a more
|
||||
precise type than can be expressed using a union or a type variable::
|
||||
|
||||
@overload
|
||||
def process(response: None) -> None:
|
||||
...
|
||||
@overload
|
||||
def process(response: int) -> Tuple[int, str]:
|
||||
...
|
||||
@overload
|
||||
def process(response: bytes) -> str:
|
||||
...
|
||||
def process(response):
|
||||
<actual implementation>
|
||||
|
||||
See :pep:`484` for details and comparison with other typing semantics.
|
||||
|
||||
.. decorator:: no_type_check(arg)
|
||||
|
||||
Decorator to indicate that annotations are not type hints.
|
||||
|
@ -785,3 +847,40 @@ The module defines the following classes, functions and decorators:
|
|||
|
||||
This wraps the decorator with something that wraps the decorated
|
||||
function in :func:`no_type_check`.
|
||||
|
||||
.. data:: ClassVar
|
||||
|
||||
Special type construct to mark class variables.
|
||||
|
||||
As introduced in :pep:`526`, a variable annotation wrapped in ClassVar
|
||||
indicates that a given attribute is intended to be used as a class variable
|
||||
and should not be set on instances of that class. Usage::
|
||||
|
||||
class Starship:
|
||||
stats: ClassVar[Dict[str, int]] = {} # class variable
|
||||
damage: int = 10 # instance variable
|
||||
|
||||
ClassVar accepts only types and cannot be further subscribed.
|
||||
|
||||
ClassVar is not a class itself, and should not
|
||||
be used with isinstance() or issubclass(). Note that ClassVar
|
||||
does not change Python runtime behavior, it can be used by
|
||||
3rd party type checkers, so that the following code will
|
||||
flagged as an error by those::
|
||||
|
||||
enterprise_d = Starship(3000)
|
||||
enterprise_d.stats = {} # Error, setting class variable on instance
|
||||
Starship.stats = {} # This is OK
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. data:: TYPE_CHECKING
|
||||
|
||||
A special constant that is assumed to be ``True`` by 3rd party static
|
||||
type checkers. It is ``False`` at runtime. Usage::
|
||||
|
||||
if TYPE_CHECKING:
|
||||
import expensive_mod
|
||||
|
||||
def fun():
|
||||
local_var: expensive_mod.some_type = other_fun()
|
||||
|
|
Loading…
Reference in a new issue