cpython: 192c654a7c93 (original) (raw)

--- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -20,8 +20,9 @@ The function below takes and returns a s def greeting(name: str) -> str: return 'Hello ' + name -In the function greeting, the argument name is expected to by of type str -and the return type str. Subtypes are accepted as arguments. +In the function greeting, the argument name is expected to by of type +:class:str and the return type :class:str. Subtypes are accepted as +arguments. Type aliases ------------ @@ -49,8 +50,8 @@ For example:: It is possible to declare the return type of a callable without specifying the call signature by substituting a literal ellipsis -for the list of arguments in the type hint: Callable[..., ReturnType]. -None as a type hint is a special case and is replaced by type(None). +for the list of arguments in the type hint: Callable[..., ReturnType]. +None as a type hint is a special case and is replaced by type(None). Generics -------- @@ -108,11 +109,12 @@ A user-defined class can be defined as a def log(self, message: str) -> None: self.logger.info('{}: {}'.format(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 class body. +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 +class body. -The Generic base class uses a metaclass that defines __getitem__ so that -LoggedVar[t] is valid as a type:: +The :class:Generic base class uses a metaclass that defines +:meth:__getitem__ so that LoggedVar[t] is valid as a type:: from typing import Iterable @@ -132,7 +134,7 @@ be constrained:: class StrangePair(Generic[T, S]): ... -Each type variable argument to Generic must be distinct. +Each type variable argument to :class:Generic must be distinct. This is thus invalid:: from typing import TypeVar, Generic @@ -152,9 +154,9 @@ You can use multiple inheritance with G[](#l1.52) class LinkedList(Sized, Generic[T]):[](#l1.53) ...[](#l1.54) [](#l1.55) -Subclassing a generic class without specifying type parameters assumes Any[](#l1.56) -for each position. In the following example, MyIterableis not generic but[](#l1.57) -implicitly inherits fromIterable[Any]::[](#l1.58) +Subclassing a generic class without specifying type parameters assumes[](#l1.59) +:class:Anyfor each position. In the following example, ``MyIterable`` is[](#l1.60) +not generic but implicitly inherits from ``Iterable[Any]``::[](#l1.61) [](#l1.62) from typing import Iterable[](#l1.63) [](#l1.64) @@ -162,24 +164,24 @@ implicitly inherits fromIterable[Any][](#l1.65) [](#l1.66) Generic metaclasses are not supported.[](#l1.67) [](#l1.68) -The Any type[](#l1.69) ---------------[](#l1.70) +The :class:Anytype[](#l1.71) +---------------------[](#l1.72) [](#l1.73) -A special kind of type isAny. Every type is a subtype of Any.[](#l1.74) -This is also true for the builtin type object. However, to the static type[](#l1.75) -checker these are completely different.[](#l1.76) +A special kind of type is :class:Any. Every type is a subtype of[](#l1.77) +:class:Any. This is also true for the builtin type object. However, to the[](#l1.78) +static type checker these are completely different.[](#l1.79) [](#l1.80) -When the type of a value is object, the type checker will reject almost all[](#l1.81) -operations on it, and assigning it to a variable (or using it as a return value)[](#l1.82) -of a more specialized type is a type error. On the other hand, when a value has[](#l1.83) -type Any, the type checker will allow all operations on it, and a value of[](#l1.84) -type Any can be assigned to a variable (or used as a return value) of a more[](#l1.85) -constrained type.[](#l1.86) +When the type of a value is :class:object, the type checker will reject[](#l1.87) +almost all operations on it, and assigning it to a variable (or using it as a[](#l1.88) +return value) of a more specialized type is a type error. On the other hand,[](#l1.89) +when a value has type :class:Any, the type checker will allow all operations[](#l1.90) +on it, and a value of type :class:Anycan be assigned to a variable (or used[](#l1.91) +as a return value) of a more constrained type.[](#l1.92) [](#l1.93) Default argument values[](#l1.94) -----------------------[](#l1.95) [](#l1.96) -Use a literal ellipsis...` to declare an argument as having a default value:: +Use a literal ellipsis ... to declare an argument as having a default value:: from typing import AnyStr @@ -195,9 +197,10 @@ The module defines the following classes Special type indicating an unconstrained type.

• • Any object is an instance of Any.
• • Any class is a subclass of Any.
• • As a special case, Any and object are subclasses of each other.

• • Any object is an instance of :class:Any.
• • Any class is a subclass of :class:Any.
• • As a special case, :class:Any and :class:object are subclasses of

• each other.[](#l1.112)

.. class:: TypeVar @@ -224,22 +227,22 @@ The module defines the following classes return x if len(x) >= len(y) else y The latter example's signature is essentially the overloading

• of (str, str) -> str and (bytes, bytes) -> bytes. Also note
• that if the arguments are instances of some subclass of str,
• the return type is still plain str.

• of (str, str) -> str and (bytes, bytes) -> bytes. Also note
• that if the arguments are instances of some subclass of :class:str,
• the return type is still plain :class:str.

• At runtime, isinstance(x, T) will raise TypeError. In general,
• isinstance and issublass should not be used with types.

• At runtime, isinstance(x, T) will raise :exc:TypeError. In general,
• :func:isinstance and :func:issublass should not be used with types.

Type variables may be marked covariant or contravariant by passing

• covariant=True or contravariant=True. See :pep:484 for more

• covariant=True or contravariant=True. See :pep:484 for more details. By default type variables are invariant. .. class:: Union

• Union type; Union[X, Y] means either X or Y.

• Union type; Union[X, Y] means either X or Y.

• To define a union, use e.g. Union[int, str]. Details:

• To define a union, use e.g. Union[int, str]. Details:
  • The arguments must be types and there must be at least one.

@@ -259,37 +262,37 @@ The module defines the following classes Union[int, str] == Union[str, int]

• • If Any is present it is the sole survivor, e.g.::

• • If :class:Any is present it is the sole survivor, e.g.:: Union[int, Any] == Any

* You cannot subclass or instantiate a union.

• • You cannot write Union[X][Y]

• • You cannot write Union[X][Y]

• • You can use Optional[X] as a shorthand for Union[X, None].

• • You can use Optional[X] as a shorthand for Union[X, None].

.. class:: Optional Optional type.

• Optional[X] is equivalent to Union[X, type(None)].

• Optional[X] is equivalent to Union[X, type(None)].

.. class:: Tuple

• Tuple type; Tuple[X, Y] is the is the type of a tuple of two items

• Tuple type; Tuple[X, Y] is the is the type of a tuple of two items with the first item of type X and the second of type Y.

• Example: Tuple[T1, T2] is a tuple of two elements corresponding
• to type variables T1 and T2. Tuple[int, float, str] is a tuple

• Example: Tuple[T1, T2] is a tuple of two elements corresponding
• to type variables T1 and T2. Tuple[int, float, str] is a tuple of an int, a float and a string. To specify a variable-length tuple of homogeneous type,

• use literal ellipsis, e.g. Tuple[int, ...].

• use literal ellipsis, e.g. Tuple[int, ...]. .. class:: Callable

• Callable type; Callable[[int], str] is a function of (int) -> str.

• Callable type; Callable[[int], str] is a function of (int) -> str. The subscription syntax must always be used with exactly two values: the argument list and the return type. The argument list @@ -297,9 +300,9 @@ The module defines the following classes There is no syntax to indicate optional or keyword arguments, such function types are rarely used as callback types.

• Callable[..., ReturnType] could be used to type hint a callable
• taking any number of arguments and returning ReturnType.
• A plain Callable is equivalent to Callable[..., Any].

• Callable[..., ReturnType] could be used to type hint a callable
• taking any number of arguments and returning ReturnType.
• A plain :class:Callable is equivalent to Callable[..., Any].

.. class:: Generic