使用类型注解让Python代码更易读

发表于 | 分类于 | | 阅读次数: |
字数统计: 4,388 字 | 阅读时长 ≈ 18 分钟

我们知道 Python 是一种动态语言，在声明一个变量时我们不需要显式地声明它的类型，例如下面的例子：

1
2
a = 2
print('1 + a =', 1 + a)

运行结果：

1
1 + a = 3

这里我们首先声明了一个变量 a，并将其赋值为了 2，然后将最后的结果打印出来，程序输出来了正确的结果。但在这个过程中，我们没有声明它到底是什么类型。

但如果这时候我们将 a 变成一个字符串类型，结果会是怎样的呢？改写如下：

1
2
a = '2'
print('1 + a =', 1 + a)

运行结果：

1
TypeError: unsupported operand type(s) for +: 'int' and 'str'

直接报错了，错误原因是我们进行了字符串类型的变量和数值类型变量的加和，两种数据类型不同，是无法进行相加的。

如果我们将上面的语句改写成一个方法定义：

1
2
def add(a):
    return a + 1

这里定义了一个方法，传入一个参数，然后将其加 1 并返回。

如果这时候如果用下面的方式调用，传入的参数是一个数值类型：

1
add(2)

则可以正常输出结果 3。但如果我们传入的参数并不是我们期望的类型，比如传入一个字符类型，那么就会同样报刚才类似的错误。

但又由于 Python 的特性，很多情况下我们并不用去声明它的类型，因此从方法定义上面来看，我们实际上是不知道一个方法的参数到底应该传入什么类型的。

这样其实就造成了很多不方便的地方，在某些情况下一些复杂的方法，如果不借助于一些额外的说明，我们是不知道参数到底是什么类型的。

因此，Python 中的类型注解就显得比较重要了。

类型注解

在 Python 3.5 中，Python PEP 484 引入了类型注解（type hints），在 Python 3.6 中，PEP 526 又进一步引入了变量注解（Variable Annotations），所以上面的代码我们改写成如下写法：

1
2
3
4
5
a: int = 2
print('5 + a =', 5 + a)

def add(a: int) -> int:
    return a + 1

具体的语法是可以归纳为两点：

  • 在声明变量时，变量的后面可以加一个冒号，后面再写上变量的类型，如 int、list 等等。
  • 在声明方法返回值的时候，可以在方法的后面加一个箭头，后面加上返回值的类型，如int、list等等。

在 PEP 8 中，具体的格式是这样规定的：

  • 在声明变量类型时，变量后方紧跟一个冒号，冒号后面跟一个空格，再跟上变量的类型。
  • 在声明方法返回值的时候，箭头左边是方法定义，箭头右边是返回值的类型，箭头左右两边都要留有空格。

有了这样的声明，以后我们如果看到这个方法的定义，我们就知道传入的参数类型了，如调用add方法的时候，我们就知道传入的需要是一个数值类型的变量，而不是字符串类型，非常直观。

但值得注意的是，这种类型和变量注解实际上只是一种类型提示，对运行实际上是没有影响的，比如调用add方法的时候，我们传入的不是int 类型，而是一个float类型，它也不会报错，也不会对参数进行类型转换，如：

1
add(1.5)

我们传入的是一个 float 类型的数值 1.5，看下运行结果：

1
2.5

可以看到，运行结果正常输出，而且 1.5 并没有经过强制类型转换变成 1，否则结果会变成 2。

因此，类型和变量注解只是提供了一种提示，对于运行实际上没有任何影响。

不过有了类型注解，一些 IDE 是可以识别出来并提示的，比如 PyCharm 就可以识别出来在调用某个方法的时候参数类型不一致，会提示 WARNING。

比如上面的调用，如果在 PyCharm 中，就会有如下提示内容：

1
2
Expected type 'int', got 'float' instead
This inspection detects type errors in function call expressions. Due to dynamic dispatch and duck typing, this is possible in a limited but useful number of cases. Types of function parameters can be specified in docstrings or in Python 3 function annotations.

另外也有一些库是支持类型检查的，比如 mypy，安装之后，利用 mypy 即可检查出 Python 脚本中不符合类型注解的调用情况。

上面只是用一个简单的 int 类型做了实例，下面我们再看下一些相对复杂的数据结构，例如列表、元组、字典等类型怎么样来声明。

可想而知了，列表用 list 表示，元组用 tuple 表示，字典用 dict 来表示，那么很自然地，在声明的时候我们就很自然地写成这样了：

1
2
3
names: list = ['Germey', 'Guido']
version: tuple = (3, 7, 4)
operations: dict = {'show': False, 'sort': True}

这么看上去没有问题，确实声明为了对应的类型，但实际上并不能反映整个列表、元组的结构，比如我们只通过类型注解是不知道names里面的元素是什么类型的，只知道names 是一个列表list 类型，实际上里面都是字符串 str类型。我们也不知道 version 这个元组的每一个元素是什么类型的，实际上是int 类型。但这些信息我们都无从得知。因此说，仅仅凭借list、tuple这样的声明是非常“弱”的，我们需要一种更强的类型声明。

这时候我们就需要借助于 typing 模块了，它提供了非常“强“的类型支持，比如 List[str]、Tuple[int, int, int] 则可以表示由str类型的元素组成的列表和由 int类型的元素组成的长度为 3 的元组。所以上文的声明写法可以改写成下面的样子：

1
2
3
4
5
from typing import List, Tuple, Dict

names: List[str] = ['Germey', 'Guido']
version: Tuple[int, int, int] = (3, 7, 4)
operations: Dict[str, bool] = {'show': False, 'sort': True}

这样一来，变量的类型便可以非常直观地体现出来了。

目前typing模块也已经被加入到 Python 标准库中，不需要安装第三方模块，我们就可以直接使用了。

typing

下面我们再来详细看下typing模块的具体用法，这里主要会介绍一些常用的注解类型，如List、Tuple、Dict、Sequence等等，了解了每个类型的具体使用方法，我们可以得心应手的对任何变量进行声明了。

在引入的时候就直接通过typing模块引入就好了，例如：

1
from typing import List, Tuple

List

List、列表，是list的泛型，基本等同于list，其后紧跟一个方括号，里面代表了构成这个列表的元素类型，如由数字构成的列表可以声明为：

1
var: List[int or float] = [2, 3.5]

另外还可以嵌套声明都是可以的：

1
var: List[List[int]] = [[1, 2], [2, 3]]

Tuple、NamedTuple

Tuple、元组，是tuple 的泛型，其后紧跟一个方括号，方括号中按照顺序声明了构成本元组的元素类型，如 Tuple[X, Y] 代表了构成元组的第一个元素是 X 类型，第二个元素是 Y 类型。

比如想声明一个元组，分别代表姓名、年龄、身高，三个数据类型分别为str、int、float，那么可以这么声明：

1
person: Tuple[str, int, float] = ('Mike', 22, 1.75)

同样地也可以使用类型嵌套。

NamedTuple，是 collections.namedtuple 的泛型，实际上就和namedtuple 用法完全一致，但个人其实并不推荐使用 NamedTuple，推荐使用attrs这个库来声明一些具有表征意义的类。

Dict、Mapping、MutableMapping

Dict、字典，是dict的泛型；Mapping，映射，是 collections.abc.Mapping 的泛型。根据官方文档，Dict推荐用于注解返回类型，Mapping推荐用于注解参数。它们的使用方法都是一样的，其后跟一个中括号，中括号内分别声明键名、键值的类型，如：

1
2
def size(rect: Mapping[str, int]) -> Dict[str, int]:
    return {'width': rect['width'] + 100, 'height': rect['width'] + 100}

这里将 Dict 用作了返回值类型注解，将Mapping 用作了参数类型注解。

MutableMapping 则是Mapping 对象的子类，在很多库中也经常用 MutableMapping来代替Mapping。

Set、AbstractSet

Set、集合，是 set的泛型；AbstractSet是 collections.abc.Set 的泛型。根据官方文档，Set推荐用于注解返回类型，AbstractSet 用于注解参数。它们的使用方法都是一样的，其后跟一个中括号，里面声明集合中元素的类型，如：

1
2
def describe(s: AbstractSet[int]) -> Set[int]:
    return set(s)

这里将Set 用作了返回值类型注解，将 AbstractSet用作了参数类型注解。

Sequence

Sequence，是 collections.abc.Sequence 的泛型，在某些情况下，我们可能并不需要严格区分一个变量或参数到底是列表list类型还是元组 tuple类型，我们可以使用一个更为泛化的类型，叫做Sequence，其用法类似于 List，如：

1
2
def square(elements: Sequence[float]) -> List[float]:
    return [x ** 2 for x in elements]

NoReturn

NoReturn，当一个方法没有返回结果时，为了注解它的返回类型，我们可以将其注解为NoReturn，例如：

1
2
def hello() -> NoReturn:
    print('hello')

Any

Any，是一种特殊的类型，它可以代表所有类型，静态类型检查器的所有类型都与Any 类型兼容，所有的无参数类型注解和返回类型注解的都会默认使用Any类型，也就是说，下面两个方法的声明是完全等价的：

1
2
3
4
5
def add(a):
    return a + 1

def add(a: Any) -> Any:
    return a + 1

原理类似于object，所有的类型都是object的子类。但如果我们将参数声明为object类型，静态参数类型检查便会抛出错误，而Any则不会，具体可以参考官方文档的说明：https://docs.python.org/zh-cn/3/library/typing.html?highlight=typing#the-any-type。

TypeVar

TypeVar，我们可以借助它来自定义兼容特定类型的变量，比如有的变量声明为int、float、None都是符合要求的，实际就是代表任意的数字或者空内容都可以，其他的类型则不可以，比如列表list、字典dict等等，像这样的情况，我们可以使用TypeVar来表示。

例如一个人的身高，便可以使用int 或float或 None来表示，但不能用 dict 来表示，所以可以这么声明：

1
2
3
4
height = 1.75
Height = TypeVar('Height', int, float, None)
def get_height() -> Height:
    return height

这里我们使用TypeVar声明了一个Height类型，然后将其用于注解方法的返回结果。

NewType

NewType，我们可以借助于它来声明一些具有特殊含义的类型，例如像Tuple 的例子一样，我们需要将它表示为Person，即一个人的含义，但但从表面上声明为Tuple 并不直观，所以我们可以使用NewType 为其声明一个类型，如：

1
2
Person = NewType('Person', Tuple[str, int, float])
person = Person(('Mike', 22, 1.75))

这里实际上person 就是一个tuple类型，我们可以对其像tuple 一样正常操作。

Callable

Callable，可调用类型，它通常用来注解一个方法，比如我们刚才声明了一个add方法，它就是一个 Callable类型：

1
print(Callable, type(add), isinstance(add, Callable))

运行结果：

1
typing.Callable <class 'function'> True

在这里虽然二者add利用type方法得到的结果是function，但实际上利用isinstance方法判断确实是 True。

Callable在声明的时候需要使用 Callable[[Arg1Type, Arg2Type, ...], ReturnType] 这样的类型注解，将参数类型和返回值类型都要注解出来，例如：

1
2
3
4
5
def date(year: int, month: int, day: int) -> str:
    return f'{year}-{month}-{day}'

def get_date_fn() -> Callable[[int, int, int], str]:
    return date

这里首先声明了一个方法date，接收三个int参数，返回一个 str结果，get_date_fn方法返回了这个方法本身，它的返回值类型就可以标记为 Callable，中括号内分别标记了返回的方法的参数类型和返回值类型。

Union

Union，联合类型，Union[X, Y] 代表要么是 X 类型，要么是 Y 类型。

联合类型的联合类型等价于展平后的类型：

1
Union[Union[int, str], float] == Union[int, str, float]

仅有一个参数的联合类型会坍缩成参数自身，比如：

1
Union[int] == int

多余的参数会被跳过，比如：

1
Union[int, str, int] == Union[int, str]

在比较联合类型的时候，参数顺序会被忽略，比如：

1
Union[int, str] == Union[str, int]

这个在一些方法参数声明的时候比较有用，比如一个方法，要么传一个字符串表示的方法名，要么直接把方法传过来：

1
2
3
4
5
6
def process(fn: Union[str, Callable]):
    if isinstance(fn, str):
        # str2fn and process
        pass
    elif isinstance(fn, Callable):
        fn()

这样的声明在一些类库方法定义的时候十分常见。

Optional

Optional，意思是说这个参数可以为空或已经声明的类型，即 Optional[X] 等价于 Union[X, None]。

但值得注意的是，这个并不等价于可选参数，当它作为参数类型注解的时候，不代表这个参数可以不传递了，而是说这个参数可以传为None。

如果还是想不传 还是需要设置 默认值为 None

如当一个方法执行结果，如果执行完毕就不返回错误信息， 如果发生问题就返回错误信息，则可以这么声明：

1
2
def judge(result: bool) -> Optional[str]:
    if result: return 'Error Occurred'

Generator

如果想代表一个生成器类型，可以使用 Generator，它的声明比较特殊，其后的中括号紧跟着三个参数，分别代表YieldType、SendType、ReturnType，如：

1
2
3
4
5
def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

在这里yield关键字后面紧跟的变量的类型就是YieldType，yield返回的结果的类型就是SendType，最后生成器 return的内容就是ReturnType。

当然很多情况下，生成器往往只需要yield 内容就够了，我们是不需要 SendType和ReturnType 的，可以将其设置为空，如：

1
2
3
4
def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

案例实战

接下来让我们看一个实际的项目，看看经常用到的类型一般是怎么使用的。

这里我们看的库是 requests-html，是由 Kenneth Reitz所开发的，其 GitHub 地址为：https://github.com/psf/requests-html，下面我们主要看看它的源代码中一些类型是如何声明的。

这个库的源代码其实就一个文件，那就是 https://github.com/psf/requests-html/blob/master/requests_html.py，我们看一下它里面的一些` typing` 的定义和方法定义。

首先Typing 的定义部分如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from typing import Set, Union, List, MutableMapping, Optional

_Find = Union[List['Element'], 'Element']
_XPath = Union[List[str], List['Element'], str, 'Element']
_Result = Union[List['Result'], 'Result']
_HTML = Union[str, bytes]
_BaseHTML = str
_UserAgent = str
_DefaultEncoding = str
_URL = str
_RawHTML = bytes
_Encoding = str
_LXML = HtmlElement
_Text = str
_Search = Result
_Containing = Union[str, List[str]]
_Links = Set[str]
_Attrs = MutableMapping
_Next = Union['HTML', List[str]]
_NextSymbol = List[str]

这里可以看到主要用到的类型有 Set、Union、List、MutableMapping、Optional，这些在上文都已经做了解释，另外这里使用了多次 Union 来声明了一些新的类型，如 _Find 则要么是是 Element 对象的列表，要么是单个Element对象，_Result 则要么是Result对象的列表，要么是单个Result对象。另外 _Attrs 其实就是字典类型，这里用 MutableMapping来表示了，没有用Dict，也没有用Mapping。

接下来再看一个Element 类的声明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class Element(BaseParser):
    """An element of HTML.
    :param element: The element from which to base the parsing upon.
    :param url: The URL from which the HTML originated, used for ``absolute_links``.
    :param default_encoding: Which encoding to default to.
    """

    __slots__ = [
        'element', 'url', 'skip_anchors', 'default_encoding', '_encoding',
        '_html', '_lxml', '_pq', '_attrs', 'session'
    ]

    def __init__(self, *, element, url: _URL, default_encoding: _DefaultEncoding = None) -> None:
        super(Element, self).__init__(element=element, url=url, default_encoding=default_encoding)
        self.element = element
        self.tag = element.tag
        self.lineno = element.sourceline
        self._attrs = None

    def __repr__(self) -> str:
        attrs = ['{}={}'.format(attr, repr(self.attrs[attr])) for attr in self.attrs]
        return "<Element {} {}>".format(repr(self.element.tag), ' '.join(attrs))

    @property
    def attrs(self) -> _Attrs:
        """Returns a dictionary of the attributes of the :class:`Element <Element>`
        (`learn more <https://www.w3schools.com/tags/ref_attributes.asp>`_).
        """
        if self._attrs is None:
            self._attrs = {k: v for k, v in self.element.items()}

            # Split class and rel up, as there are ussually many of them:
            for attr in ['class', 'rel']:
                if attr in self._attrs:
                    self._attrs[attr] = tuple(self._attrs[attr].split())

        return self._attrs

这里 __init__ 方法接收非常多的参数，同时使用 _URL 、_DefaultEncoding 进行了参数类型注解，另外 attrs 方法使用了 _Attrs 进行了返回结果类型注解。

整体看下来，每个参数的类型、返回值都进行了清晰地注解，代码可读性大大提高。

以上便是类型注解和typing 模块的详细介绍。

官方文档：typing — 类型提示支持

文章原文: 使用类型注解让Python代码更易读

知识就是财富
如果您觉得文章对您有帮助, 欢迎请我喝杯水！