类型分类¶
到目前为止，我们主要局限于内置类型。 本节介绍几种其他类型。 您可能至少需要其中一些来对任何重要的程序进行类型检查。
Kinds of types
We've mostly restricted ourselves to built-in types until now. This section introduces several additional kinds of types. You are likely to need at least some of them to type check any non-trivial programs.
Class的类型¶
每个类都是有效的类型。 子类的任何实例也与所有超类兼容 - 因此每个值都与 object 类型兼容(顺便说一句，还有 Any 类型，如下所述)。 Mypy 分析类的主体以确定实例中可用的方法和属性。 此示例使用子类化：
class A:
def f(self) -> int: # Type of self inferred (A)
return 2
class B(A):
def f(self) -> int:
return 3
def g(self) -> int:
return 4
def foo(a: A) -> None:
print(a.f()) # 3
a.g() # Error: "A" has no attribute "g"
foo(B()) # OK (B is a subclass of A)
Class types
Every class is also a valid type. Any instance of a subclass is also compatible with all superclasses -- it follows that every value is compatible with the object type (and incidentally also the Any type, discussed below). Mypy analyzes the bodies of classes to determine which methods and attributes are available in instances. This example uses subclassing:
class A:
def f(self) -> int: # Type of self inferred (A)
return 2
class B(A):
def f(self) -> int:
return 3
def g(self) -> int:
return 4
def foo(a: A) -> None:
print(a.f()) # 3
a.g() # Error: "A" has no attribute "g"
foo(B()) # OK (B is a subclass of A)
Any 类型¶
A value with the Any type is dynamically typed. Mypy doesn't know anything about the possible runtime types of such value. Any operations are permitted on the value, and the operations are only checked at runtime. You can use Any as an "escape hatch" when you can't use a more precise type for some reason.
Any is compatible with every other type, and vice versa. You can freely assign a value of type Any to a variable with a more precise type:
a: Any = None
s: str = ''
a = 2 # OK (assign "int" to "Any")
s = a # OK (assign "Any" to "str")
Declared (and inferred) types are ignored (or erased) at runtime. They are basically treated as comments, and thus the above code does not generate a runtime error, even though s gets an int value when the program is run, while the declared type of s is actually str! You need to be careful with Any types, since they let you lie to mypy, and this could easily hide bugs.
If you do not define a function return value or argument types, these default to Any:
def show_heading(s) -> None:
print('=== ' + s + ' ===') # No static type checking, as s has type Any
show_heading(1) # OK (runtime error only; mypy won't generate an error)
You should give a statically typed function an explicit None return type even if it doesn't return a value, as this lets mypy catch additional type errors:
def wait(t: float): # Implicit Any return value
print('Waiting...')
time.sleep(t)
if wait(2) > 1: # Mypy doesn't catch this error!
...
If we had used an explicit None return type, mypy would have caught the error:
def wait(t: float) -> None:
print('Waiting...')
time.sleep(t)
if wait(2) > 1: # Error: can't compare None and int
...
The Any type is discussed in more detail in section dynamic-typing.
Note
A function without any types in the signature is dynamically typed. The body of a dynamically typed function is not checked statically, and local variables have implicit Any types.
This makes it easier to migrate legacy Python code to mypy, as mypy won't complain about dynamically typed functions.
The Any type
A value with the Any type is dynamically typed. Mypy doesn't know anything about the possible runtime types of such value. Any operations are permitted on the value, and the operations are only checked at runtime. You can use Any as an "escape hatch" when you can't use a more precise type for some reason.
Any is compatible with every other type, and vice versa. You can freely assign a value of type Any to a variable with a more precise type:
a: Any = None
s: str = ''
a = 2 # OK (assign "int" to "Any")
s = a # OK (assign "Any" to "str")
Declared (and inferred) types are ignored (or erased) at runtime. They are basically treated as comments, and thus the above code does not generate a runtime error, even though s gets an int value when the program is run, while the declared type of s is actually str! You need to be careful with Any types, since they let you lie to mypy, and this could easily hide bugs.
If you do not define a function return value or argument types, these default to Any:
def show_heading(s) -> None:
print('=== ' + s + ' ===') # No static type checking, as s has type Any
show_heading(1) # OK (runtime error only; mypy won't generate an error)
You should give a statically typed function an explicit None return type even if it doesn't return a value, as this lets mypy catch additional type errors:
def wait(t: float): # Implicit Any return value
print('Waiting...')
time.sleep(t)
if wait(2) > 1: # Mypy doesn't catch this error!
...
If we had used an explicit None return type, mypy would have caught the error:
def wait(t: float) -> None:
print('Waiting...')
time.sleep(t)
if wait(2) > 1: # Error: can't compare None and int
...
The Any type is discussed in more detail in section dynamic-typing.
Note
A function without any types in the signature is dynamically typed. The body of a dynamically typed function is not checked statically, and local variables have implicit Any types.
This makes it easier to migrate legacy Python code to mypy, as mypy won't complain about dynamically typed functions.
Tuple 类型¶
The type tuple[T1, ..., Tn] represents a tuple with the item types T1, ..., Tn:
# Use `typing.Tuple` in Python 3.8 and earlier
def f(t: tuple[int, str]) -> None:
t = 1, 'foo' # OK
t = 'foo', 1 # Type check error
A tuple type of this kind has exactly a specific number of items (2 in the above example). Tuples can also be used as immutable, varying-length sequences. You can use the type tuple[T, ...] (with a literal ... -- it's part of the syntax) for this purpose. Example:
def print_squared(t: tuple[int, ...]) -> None:
for n in t:
print(n, n ** 2)
print_squared(()) # OK
print_squared((1, 3, 5)) # OK
print_squared([1, 2]) # Error: only a tuple is valid
Note
Usually it's a better idea to use Sequence[T] instead of tuple[T, ...], as typing.Sequence is also compatible with lists and other non-tuple sequences.
Note
tuple[...] is valid as a base class in Python 3.6 and later, and always in stub files. In earlier Python versions you can sometimes work around this limitation by using a named tuple as a base class (see section named-tuples).
Tuple types
The type tuple[T1, ..., Tn] represents a tuple with the item types T1, ..., Tn:
# Use `typing.Tuple` in Python 3.8 and earlier
def f(t: tuple[int, str]) -> None:
t = 1, 'foo' # OK
t = 'foo', 1 # Type check error
A tuple type of this kind has exactly a specific number of items (2 in the above example). Tuples can also be used as immutable, varying-length sequences. You can use the type tuple[T, ...] (with a literal ... -- it's part of the syntax) for this purpose. Example:
def print_squared(t: tuple[int, ...]) -> None:
for n in t:
print(n, n ** 2)
print_squared(()) # OK
print_squared((1, 3, 5)) # OK
print_squared([1, 2]) # Error: only a tuple is valid
Note
Usually it's a better idea to use Sequence[T] instead of tuple[T, ...], as typing.Sequence is also compatible with lists and other non-tuple sequences.
Note
tuple[...] is valid as a base class in Python 3.6 and later, and always in stub files. In earlier Python versions you can sometimes work around this limitation by using a named tuple as a base class (see section named-tuples).
Callable 类型 (以及 lambdas)¶
You can pass around function objects and bound methods in statically typed code. The type of a function that accepts arguments A1, ..., An and returns Rt is Callable[[A1, ..., An], Rt]. Example:
from typing import Callable
def twice(i: int, next: Callable[[int], int]) -> int:
return next(next(i))
def add(i: int) -> int:
return i + 1
print(twice(3, add)) # 5
You can only have positional arguments, and only ones without default values, in callable types. These cover the vast majority of uses of callable types, but sometimes this isn't quite enough. Mypy recognizes a special form Callable[..., T] (with a literal ...) which can be used in less typical cases. It is compatible with arbitrary callable objects that return a type compatible with T, independent of the number, types or kinds of arguments. Mypy lets you call such callable values with arbitrary arguments, without any checking -- in this respect they are treated similar to a (*args: Any, **kwargs: Any) function signature. Example:
from typing import Callable
def arbitrary_call(f: Callable[..., int]) -> int:
return f('x') + f(y=2) # OK
arbitrary_call(ord) # No static error, but fails at runtime
arbitrary_call(open) # Error: does not return an int
arbitrary_call(1) # Error: 'int' is not callable
In situations where more precise or complex types of callbacks are necessary one can use flexible callback protocols. Lambdas are also supported. The lambda argument and return value types cannot be given explicitly; they are always inferred based on context using bidirectional type inference:
l = map(lambda x: x + 1, [1, 2, 3]) # Infer x as int and l as list[int]
If you want to give the argument or return value types explicitly, use an ordinary, perhaps nested function definition.
Callables can also be used against type objects, matching their __init__ or __new__ signature:
from typing import Callable
class C:
def __init__(self, app: str) -> None:
pass
CallableType = Callable[[str], C]
def class_or_callable(arg: CallableType) -> None:
inst = arg("my_app")
reveal_type(inst) # Revealed type is "C"
This is useful if you want arg to be either a Callable returning an instance of C or the type of C itself. This also works with callback protocols.
Callable types (and lambdas)
You can pass around function objects and bound methods in statically typed code. The type of a function that accepts arguments A1, ..., An and returns Rt is Callable[[A1, ..., An], Rt]. Example:
from typing import Callable
def twice(i: int, next: Callable[[int], int]) -> int:
return next(next(i))
def add(i: int) -> int:
return i + 1
print(twice(3, add)) # 5
You can only have positional arguments, and only ones without default values, in callable types. These cover the vast majority of uses of callable types, but sometimes this isn't quite enough. Mypy recognizes a special form Callable[..., T] (with a literal ...) which can be used in less typical cases. It is compatible with arbitrary callable objects that return a type compatible with T, independent of the number, types or kinds of arguments. Mypy lets you call such callable values with arbitrary arguments, without any checking -- in this respect they are treated similar to a (*args: Any, **kwargs: Any) function signature. Example:
from typing import Callable
def arbitrary_call(f: Callable[..., int]) -> int:
return f('x') + f(y=2) # OK
arbitrary_call(ord) # No static error, but fails at runtime
arbitrary_call(open) # Error: does not return an int
arbitrary_call(1) # Error: 'int' is not callable
In situations where more precise or complex types of callbacks are necessary one can use flexible callback protocols. Lambdas are also supported. The lambda argument and return value types cannot be given explicitly; they are always inferred based on context using bidirectional type inference:
l = map(lambda x: x + 1, [1, 2, 3]) # Infer x as int and l as list[int]
If you want to give the argument or return value types explicitly, use an ordinary, perhaps nested function definition.
Callables can also be used against type objects, matching their __init__ or __new__ signature:
from typing import Callable
class C:
def __init__(self, app: str) -> None:
pass
CallableType = Callable[[str], C]
def class_or_callable(arg: CallableType) -> None:
inst = arg("my_app")
reveal_type(inst) # Revealed type is "C"
This is useful if you want arg to be either a Callable returning an instance of C or the type of C itself. This also works with callback protocols.
Union 类型¶
Python functions often accept values of two or more different types. You can use overloading to represent this, but union types are often more convenient.
Use the Union[T1, ..., Tn] type constructor to construct a union type. For example, if an argument has type Union[int, str], both integers and strings are valid argument values.
You can use an isinstance check to narrow down a union type to a more specific type:
from typing import Union
def f(x: Union[int, str]) -> None:
x + 1 # Error: str + int is not valid
if isinstance(x, int):
# Here type of x is int.
x + 1 # OK
else:
# Here type of x is str.
x + 'a' # OK
f(1) # OK
f('x') # OK
f(1.1) # Error
Note
Operations are valid for union types only if they are valid for every union item. This is why it's often necessary to use an isinstance check to first narrow down a union type to a non-union type. This also means that it's recommended to avoid union types as function return types, since the caller may have to use isinstance before doing anything interesting with the value.
Union types
Python functions often accept values of two or more different types. You can use overloading to represent this, but union types are often more convenient.
Use the Union[T1, ..., Tn] type constructor to construct a union type. For example, if an argument has type Union[int, str], both integers and strings are valid argument values.
You can use an isinstance check to narrow down a union type to a more specific type:
from typing import Union
def f(x: Union[int, str]) -> None:
x + 1 # Error: str + int is not valid
if isinstance(x, int):
# Here type of x is int.
x + 1 # OK
else:
# Here type of x is str.
x + 'a' # OK
f(1) # OK
f('x') # OK
f(1.1) # Error
Note
Operations are valid for union types only if they are valid for every union item. This is why it's often necessary to use an isinstance check to first narrow down a union type to a non-union type. This also means that it's recommended to avoid union types as function return types, since the caller may have to use isinstance before doing anything interesting with the value.
Optional 和 None 类型¶
You can use the typing.Optional type modifier to define a type variant that allows None, such as Optional[int] (Optional[X] is the preferred shorthand for Union[X, None]):
from typing import Optional
def strlen(s: str) -> Optional[int]:
if not s:
return None # OK
return len(s)
def strlen_invalid(s: str) -> int:
if not s:
return None # Error: None not compatible with int
return len(s)
Most operations will not be allowed on unguarded None or typing.Optional values:
def my_inc(x: Optional[int]) -> int:
return x + 1 # Error: Cannot add None and int
Instead, an explicit None check is required. Mypy has powerful type inference that lets you use regular Python idioms to guard against None values. For example, mypy recognizes is None checks:
def my_inc(x: Optional[int]) -> int:
if x is None:
return 0
else:
# The inferred type of x is just int here.
return x + 1
Mypy will infer the type of x to be int in the else block due to the check against None in the if condition.
Other supported checks for guarding against a None value include if x is not None, if x and if not x. Additionally, mypy understands None checks within logical expressions:
def concat(x: Optional[str], y: Optional[str]) -> Optional[str]:
if x is not None and y is not None:
# Both x and y are not None here
return x + y
else:
return None
Sometimes mypy doesn't realize that a value is never None. This notably happens when a class instance can exist in a partially defined state, where some attribute is initialized to None during object construction, but a method assumes that the attribute is no longer None. Mypy will complain about the possible None value. You can use assert x is not None to work around this in the method:
class Resource:
path: Optional[str] = None
def initialize(self, path: str) -> None:
self.path = path
def read(self) -> str:
# We require that the object has been initialized.
assert self.path is not None
with open(self.path) as f: # OK
return f.read()
r = Resource()
r.initialize('/foo/bar')
r.read()
When initializing a variable as None, None is usually an empty place-holder value, and the actual value has a different type. This is why you need to annotate an attribute in cases like the class Resource above:
class Resource:
path: Optional[str] = None
...
This also works for attributes defined within methods:
class Counter:
def __init__(self) -> None:
self.count: Optional[int] = None
This is not a problem when using variable annotations, since no initial value is needed:
class Container:
items: list[str] # No initial value
Mypy generally uses the first assignment to a variable to infer the type of the variable. However, if you assign both a None value and a non-None value in the same scope, mypy can usually do the right thing without an annotation:
def f(i: int) -> None:
n = None # Inferred type Optional[int] because of the assignment below
if i > 0:
n = i
...
Sometimes you may get the error "Cannot determine type of \Optional[...] annotation (or type comment).
Note
None is a type with only one value, None. None is also used as the return type for functions that don't return a value, i.e. functions that implicitly return None.
Note
The Python interpreter internally uses the name NoneType for the type of None, but None is always used in type annotations. The latter is shorter and reads better. (NoneType is available as types.NoneType on Python 3.10+, but is not exposed at all on earlier versions of Python.)
Note
Optional[...] does not mean a function argument with a default value. It simply means that None is a valid value for the argument. This is a common confusion because None is a common default value for arguments.
Optional types and the None type
You can use the typing.Optional type modifier to define a type variant that allows None, such as Optional[int] (Optional[X] is the preferred shorthand for Union[X, None]):
from typing import Optional
def strlen(s: str) -> Optional[int]:
if not s:
return None # OK
return len(s)
def strlen_invalid(s: str) -> int:
if not s:
return None # Error: None not compatible with int
return len(s)
Most operations will not be allowed on unguarded None or typing.Optional values:
def my_inc(x: Optional[int]) -> int:
return x + 1 # Error: Cannot add None and int
Instead, an explicit None check is required. Mypy has powerful type inference that lets you use regular Python idioms to guard against None values. For example, mypy recognizes is None checks:
def my_inc(x: Optional[int]) -> int:
if x is None:
return 0
else:
# The inferred type of x is just int here.
return x + 1
Mypy will infer the type of x to be int in the else block due to the check against None in the if condition.
Other supported checks for guarding against a None value include if x is not None, if x and if not x. Additionally, mypy understands None checks within logical expressions:
def concat(x: Optional[str], y: Optional[str]) -> Optional[str]:
if x is not None and y is not None:
# Both x and y are not None here
return x + y
else:
return None
Sometimes mypy doesn't realize that a value is never None. This notably happens when a class instance can exist in a partially defined state, where some attribute is initialized to None during object construction, but a method assumes that the attribute is no longer None. Mypy will complain about the possible None value. You can use assert x is not None to work around this in the method:
class Resource:
path: Optional[str] = None
def initialize(self, path: str) -> None:
self.path = path
def read(self) -> str:
# We require that the object has been initialized.
assert self.path is not None
with open(self.path) as f: # OK
return f.read()
r = Resource()
r.initialize('/foo/bar')
r.read()
When initializing a variable as None, None is usually an empty place-holder value, and the actual value has a different type. This is why you need to annotate an attribute in cases like the class Resource above:
class Resource:
path: Optional[str] = None
...
This also works for attributes defined within methods:
class Counter:
def __init__(self) -> None:
self.count: Optional[int] = None
This is not a problem when using variable annotations, since no initial value is needed:
class Container:
items: list[str] # No initial value
Mypy generally uses the first assignment to a variable to infer the type of the variable. However, if you assign both a None value and a non-None value in the same scope, mypy can usually do the right thing without an annotation:
def f(i: int) -> None:
n = None # Inferred type Optional[int] because of the assignment below
if i > 0:
n = i
...
Sometimes you may get the error "Cannot determine type of \Optional[...] annotation (or type comment).
Note
None is a type with only one value, None. None is also used as the return type for functions that don't return a value, i.e. functions that implicitly return None.
Note
The Python interpreter internally uses the name NoneType for the type of None, but None is always used in type annotations. The latter is shorter and reads better. (NoneType is available as types.NoneType on Python 3.10+, but is not exposed at all on earlier versions of Python.)
Note
Optional[...] does not mean a function argument with a default value. It simply means that None is a valid value for the argument. This is a common confusion because None is a common default value for arguments.
Union 的 X | Y 语法¶
PEP 604 introduced an alternative way for spelling union types. In Python 3.10 and later, you can write Union[int, str] as int | str. It is possible to use this syntax in versions of Python where it isn't supported by the runtime with some limitations (see runtime troubles).
t1: int | str # equivalent to Union[int, str]
t2: int | None # equivalent to Optional[int]
X | Y syntax for Unions
PEP 604 introduced an alternative way for spelling union types. In Python 3.10 and later, you can write Union[int, str] as int | str. It is possible to use this syntax in versions of Python where it isn't supported by the runtime with some limitations (see runtime troubles).
t1: int | str # equivalent to Union[int, str]
t2: int | None # equivalent to Optional[int]
禁用严格的可选检查¶
Mypy also has an option to treat None as a valid value for every type (in case you know Java, it's useful to think of it as similar to the Java null). In this mode None is also valid for primitive types such as int and float, and typing.Optional types are not required.
The mode is enabled through the --no-strict-optional command-line option. In mypy versions before 0.600 this was the default mode. You can enable this option explicitly for backward compatibility with earlier mypy versions, in case you don't want to introduce optional types to your codebase yet.
It will cause mypy to silently accept some buggy code, such as this example -- it's not recommended if you can avoid it:
def inc(x: int) -> int:
return x + 1
x = inc(None) # No error reported by mypy if strict optional mode disabled!
However, making code "optional clean" can take some work! You can also use the mypy configuration file to migrate your code to strict optional checking one file at a time, since there exists the per-module flag strict_optional to control strict optional mode.
Often it's still useful to document whether a variable can be None. For example, this function accepts a None argument, but it's not obvious from its signature:
def greeting(name: str) -> str:
if name:
return f'Hello, {name}'
else:
return 'Hello, stranger'
print(greeting('Python')) # Okay!
print(greeting(None)) # Also okay!
You can still use Optional[t] to document that None is a valid argument type, even if strict None checking is not enabled:
from typing import Optional
def greeting(name: Optional[str]) -> str:
if name:
return f'Hello, {name}'
else:
return 'Hello, stranger'
Mypy treats this as semantically equivalent to the previous example if strict optional checking is disabled, since None is implicitly valid for any type, but it's much more useful for a programmer who is reading the code. This also makes it easier to migrate to strict None checking in the future.
Disabling strict optional checking
Mypy also has an option to treat None as a valid value for every type (in case you know Java, it's useful to think of it as similar to the Java null). In this mode None is also valid for primitive types such as int and float, and typing.Optional types are not required.
The mode is enabled through the --no-strict-optional command-line option. In mypy versions before 0.600 this was the default mode. You can enable this option explicitly for backward compatibility with earlier mypy versions, in case you don't want to introduce optional types to your codebase yet.
It will cause mypy to silently accept some buggy code, such as this example -- it's not recommended if you can avoid it:
def inc(x: int) -> int:
return x + 1
x = inc(None) # No error reported by mypy if strict optional mode disabled!
However, making code "optional clean" can take some work! You can also use the mypy configuration file to migrate your code to strict optional checking one file at a time, since there exists the per-module flag strict_optional to control strict optional mode.
Often it's still useful to document whether a variable can be None. For example, this function accepts a None argument, but it's not obvious from its signature:
def greeting(name: str) -> str:
if name:
return f'Hello, {name}'
else:
return 'Hello, stranger'
print(greeting('Python')) # Okay!
print(greeting(None)) # Also okay!
You can still use Optional[t] to document that None is a valid argument type, even if strict None checking is not enabled:
from typing import Optional
def greeting(name: Optional[str]) -> str:
if name:
return f'Hello, {name}'
else:
return 'Hello, stranger'
Mypy treats this as semantically equivalent to the previous example if strict optional checking is disabled, since None is implicitly valid for any type, but it's much more useful for a programmer who is reading the code. This also makes it easier to migrate to strict None checking in the future.
类型别名¶
In certain situations, type names may end up being long and painful to type:
def f() -> Union[list[dict[tuple[int, str], set[int]]], tuple[str, list[str]]]:
...
When cases like this arise, you can define a type alias by simply assigning the type to a variable:
AliasType = Union[list[dict[tuple[int, str], set[int]]], tuple[str, list[str]]]
# Now we can use AliasType in place of the full name:
def f() -> AliasType:
...
Note
A type alias does not create a new type. It's just a shorthand notation for another type -- it's equivalent to the target type except for generic aliases.
Since Mypy 0.930 you can also use explicit type aliases, which were introduced in PEP 613.
There can be confusion about exactly when an assignment defines an implicit type alias -- for example, when the alias contains forward references, invalid types, or violates some other restrictions on type alias declarations. Because the distinction between an unannotated variable and a type alias is implicit, ambiguous or incorrect type alias declarations default to defining a normal variable instead of a type alias.
Explicit type aliases are unambiguous and can also improve readability by making the intent clear:
from typing import TypeAlias # "from typing_extensions" in Python 3.9 and earlier
AliasType: TypeAlias = Union[list[dict[tuple[int, str], set[int]]], tuple[str, list[str]]]
Type aliases
In certain situations, type names may end up being long and painful to type:
def f() -> Union[list[dict[tuple[int, str], set[int]]], tuple[str, list[str]]]:
...
When cases like this arise, you can define a type alias by simply assigning the type to a variable:
AliasType = Union[list[dict[tuple[int, str], set[int]]], tuple[str, list[str]]]
# Now we can use AliasType in place of the full name:
def f() -> AliasType:
...
Note
A type alias does not create a new type. It's just a shorthand notation for another type -- it's equivalent to the target type except for generic aliases.
Since Mypy 0.930 you can also use explicit type aliases, which were introduced in PEP 613.
There can be confusion about exactly when an assignment defines an implicit type alias -- for example, when the alias contains forward references, invalid types, or violates some other restrictions on type alias declarations. Because the distinction between an unannotated variable and a type alias is implicit, ambiguous or incorrect type alias declarations default to defining a normal variable instead of a type alias.
Explicit type aliases are unambiguous and can also improve readability by making the intent clear:
from typing import TypeAlias # "from typing_extensions" in Python 3.9 and earlier
AliasType: TypeAlias = Union[list[dict[tuple[int, str], set[int]]], tuple[str, list[str]]]
命名元组¶
Mypy recognizes named tuples and can type check code that defines or uses them. In this example, we can detect code trying to access a missing attribute:
Point = namedtuple('Point', ['x', 'y'])
p = Point(x=1, y=2)
print(p.z) # Error: Point has no attribute 'z'
If you use namedtuple to define your named tuple, all the items are assumed to have Any types. That is, mypy doesn't know anything about item types. You can use typing.NamedTuple to also define item types:
from typing import NamedTuple
Point = NamedTuple('Point', [('x', int),
('y', int)])
p = Point(x=1, y='x') # Argument has incompatible type "str"; expected "int"
Python 3.6 introduced an alternative, class-based syntax for named tuples with types:
from typing import NamedTuple
class Point(NamedTuple):
x: int
y: int
p = Point(x=1, y='x') # Argument has incompatible type "str"; expected "int"
Note
You can use the raw NamedTuple "pseudo-class" in type annotations if any NamedTuple object is valid.
For example, it can be useful for deserialization:
def deserialize_named_tuple(arg: NamedTuple) -> Dict[str, Any]:
return arg._asdict()
Point = namedtuple('Point', ['x', 'y'])
Person = NamedTuple('Person', [('name', str), ('age', int)])
deserialize_named_tuple(Point(x=1, y=2)) # ok
deserialize_named_tuple(Person(name='Nikita', age=18)) # ok
# Error: Argument 1 to "deserialize_named_tuple" has incompatible type
# "Tuple[int, int]"; expected "NamedTuple"
deserialize_named_tuple((1, 2))
Note that this behavior is highly experimental, non-standard, and may not be supported by other type checkers and IDEs.
Named tuples
Mypy recognizes named tuples and can type check code that defines or uses them. In this example, we can detect code trying to access a missing attribute:
Point = namedtuple('Point', ['x', 'y'])
p = Point(x=1, y=2)
print(p.z) # Error: Point has no attribute 'z'
If you use namedtuple to define your named tuple, all the items are assumed to have Any types. That is, mypy doesn't know anything about item types. You can use typing.NamedTuple to also define item types:
from typing import NamedTuple
Point = NamedTuple('Point', [('x', int),
('y', int)])
p = Point(x=1, y='x') # Argument has incompatible type "str"; expected "int"
Python 3.6 introduced an alternative, class-based syntax for named tuples with types:
from typing import NamedTuple
class Point(NamedTuple):
x: int
y: int
p = Point(x=1, y='x') # Argument has incompatible type "str"; expected "int"
Note
You can use the raw NamedTuple "pseudo-class" in type annotations if any NamedTuple object is valid.
For example, it can be useful for deserialization:
def deserialize_named_tuple(arg: NamedTuple) -> Dict[str, Any]:
return arg._asdict()
Point = namedtuple('Point', ['x', 'y'])
Person = NamedTuple('Person', [('name', str), ('age', int)])
deserialize_named_tuple(Point(x=1, y=2)) # ok
deserialize_named_tuple(Person(name='Nikita', age=18)) # ok
# Error: Argument 1 to "deserialize_named_tuple" has incompatible type
# "Tuple[int, int]"; expected "NamedTuple"
deserialize_named_tuple((1, 2))
Note that this behavior is highly experimental, non-standard, and may not be supported by other type checkers and IDEs.
类对象的类型¶
(Freely after PEP 484: The type of class objects.)
Sometimes you want to talk about class objects that inherit from a given class. This can be spelled as type[C] (or, on Python 3.8 and lower, typing.Type[C]) where C is a class. In other words, when C is the name of a class, using C to annotate an argument declares that the argument is an instance of C (or of a subclass of C), but using type[C] as an argument annotation declares that the argument is a class object deriving from C (or C itself).
For example, assume the following classes:
class User:
# Defines fields like name, email
class BasicUser(User):
def upgrade(self):
"""Upgrade to Pro"""
class ProUser(User):
def pay(self):
"""Pay bill"""
Note that ProUser doesn't inherit from BasicUser.
Here's a function that creates an instance of one of these classes if you pass it the right class object:
def new_user(user_class):
user = user_class()
# (Here we could write the user object to a database)
return user
How would we annotate this function? Without the ability to parameterize type, the best we could do would be:
def new_user(user_class: type) -> User:
# Same implementation as before
This seems reasonable, except that in the following example, mypy doesn't see that the buyer variable has type ProUser:
buyer = new_user(ProUser)
buyer.pay() # Rejected, not a method on User
However, using the type[C] syntax and a type variable with an upper bound (see type-variable-upper-bound) we can do better:
U = TypeVar('U', bound=User)
def new_user(user_class: type[U]) -> U:
# Same implementation as before
Now mypy will infer the correct type of the result when we call new_user() with a specific subclass of User:
beginner = new_user(BasicUser) # Inferred type is BasicUser
beginner.upgrade() # OK
Note
The value corresponding to type[C] must be an actual class object that's a subtype of C. Its constructor must be compatible with the constructor of C. If C is a type variable, its upper bound must be a class object.
For more details about type[] and typing.Type[], see PEP 484: The type of class objects <484#the-type-of-class-objects>.
The type of class objects
(Freely after PEP 484: The type of class objects.)
Sometimes you want to talk about class objects that inherit from a given class. This can be spelled as type[C] (or, on Python 3.8 and lower, typing.Type[C]) where C is a class. In other words, when C is the name of a class, using C to annotate an argument declares that the argument is an instance of C (or of a subclass of C), but using type[C] as an argument annotation declares that the argument is a class object deriving from C (or C itself).
For example, assume the following classes:
class User:
# Defines fields like name, email
class BasicUser(User):
def upgrade(self):
"""Upgrade to Pro"""
class ProUser(User):
def pay(self):
"""Pay bill"""
Note that ProUser doesn't inherit from BasicUser.
Here's a function that creates an instance of one of these classes if you pass it the right class object:
def new_user(user_class):
user = user_class()
# (Here we could write the user object to a database)
return user
How would we annotate this function? Without the ability to parameterize type, the best we could do would be:
def new_user(user_class: type) -> User:
# Same implementation as before
This seems reasonable, except that in the following example, mypy doesn't see that the buyer variable has type ProUser:
buyer = new_user(ProUser)
buyer.pay() # Rejected, not a method on User
However, using the type[C] syntax and a type variable with an upper bound (see type-variable-upper-bound) we can do better:
U = TypeVar('U', bound=User)
def new_user(user_class: type[U]) -> U:
# Same implementation as before
Now mypy will infer the correct type of the result when we call new_user() with a specific subclass of User:
beginner = new_user(BasicUser) # Inferred type is BasicUser
beginner.upgrade() # OK
Note
The value corresponding to type[C] must be an actual class object that's a subtype of C. Its constructor must be compatible with the constructor of C. If C is a type variable, its upper bound must be a class object.
For more details about type[] and typing.Type[], see PEP 484: The type of class objects <484#the-type-of-class-objects>.
生成器¶
A basic generator that only yields values can be succinctly annotated as having a return type of either Iterator[YieldType] or Iterable[YieldType]. For example:
def squares(n: int) -> Iterator[int]:
for i in range(n):
yield i * i
A good rule of thumb is to annotate functions with the most specific return type possible. However, you should also take care to avoid leaking implementation details into a function's public API. In keeping with these two principles, prefer Iterator[YieldType] over Iterable[YieldType] as the return-type annotation for a generator function, as it lets mypy know that users are able to call next on the object returned by the function. Nonetheless, bear in mind that Iterable may sometimes be the better option, if you consider it an implementation detail that next() can be called on the object returned by your function.
If you want your generator to accept values via the generator.send method or return a value, on the other hand, you should use the Generator[YieldType, SendType, ReturnType] generic type instead of either Iterator or Iterable. For example:
def echo_round() -> Generator[int, float, str]:
sent = yield 0
while sent >= 0:
sent = yield round(sent)
return 'Done'
Note that unlike many other generics in the typing module, the SendType of typing.Generator behaves contravariantly, not covariantly or invariantly.
If you do not plan on receiving or returning values, then set the SendType or ReturnType to None, as appropriate. For example, we could have annotated the first example as the following:
def squares(n: int) -> Generator[int, None, None]:
for i in range(n):
yield i * i
This is slightly different from using Iterator[int] or Iterable[int], since generators have generator.close, generator.send, and generator.throw methods that generic iterators and iterables don't. If you plan to call these methods on the returned generator, use the typing.Generator type instead of typing.Iterator or typing.Iterable.
Generators
A basic generator that only yields values can be succinctly annotated as having a return type of either Iterator[YieldType] or Iterable[YieldType]. For example:
def squares(n: int) -> Iterator[int]:
for i in range(n):
yield i * i
A good rule of thumb is to annotate functions with the most specific return type possible. However, you should also take care to avoid leaking implementation details into a function's public API. In keeping with these two principles, prefer Iterator[YieldType] over Iterable[YieldType] as the return-type annotation for a generator function, as it lets mypy know that users are able to call next on the object returned by the function. Nonetheless, bear in mind that Iterable may sometimes be the better option, if you consider it an implementation detail that next() can be called on the object returned by your function.
If you want your generator to accept values via the generator.send method or return a value, on the other hand, you should use the Generator[YieldType, SendType, ReturnType] generic type instead of either Iterator or Iterable. For example:
def echo_round() -> Generator[int, float, str]:
sent = yield 0
while sent >= 0:
sent = yield round(sent)
return 'Done'
Note that unlike many other generics in the typing module, the SendType of typing.Generator behaves contravariantly, not covariantly or invariantly.
If you do not plan on receiving or returning values, then set the SendType or ReturnType to None, as appropriate. For example, we could have annotated the first example as the following:
def squares(n: int) -> Generator[int, None, None]:
for i in range(n):
yield i * i
This is slightly different from using Iterator[int] or Iterable[int], since generators have generator.close, generator.send, and generator.throw methods that generic iterators and iterables don't. If you plan to call these methods on the returned generator, use the typing.Generator type instead of typing.Iterator or typing.Iterable.
创建日期: 2023年7月6日