ToB企服应用市场:ToB评测及商务社交产业平台

标题: 使用 Mypy 检查 30 万行 Python 代码，总结出 3 大痛点与 6 个技巧！ [打印本页]
作者: 花瓣小跑    时间: 2022-9-17 08:30
标题: 使用 Mypy 检查 30 万行 Python 代码，总结出 3 大痛点与 6 个技巧！
作者：Charlie Marsh
译者：豌豆花下猫@Python猫
英文：Using Mypy in production at Spring (https://notes.crmarsh.com/using-mypy-in-production-at-spring)
在 Spring ，我们维护了一个大型的 Python 单体代码库（英：monorepo），用上了 Mypy 最严格的配置项，实现了 Mypy 全覆盖。简而言之，这意味着每个函数签名都是带注解的，并且不允许有隐式的 Any 转换。
（译注：此处的 Spring 并不是 Java 中那个著名的 Spring 框架，而是一家生物科技公司，专注于找到与年龄相关的疾病的疗法，2022 年 3 月曾获得比尔&梅琳达·盖茨基金会 120 万美元的资助。）
诚然，代码行数是一个糟糕的衡量标准，但可作一个粗略的估计：我们的代码仓有超过 30 万行 Python 代码，其中大约一半构成了核心的数据平台，另一半是由数据科学家和机器学习研究员编写的终端用户代码。
我有个大胆的猜测，就这个规模而言，这是最全面的加了类型的 Python 代码仓之一。
我们在 2019 年 7 月首次引入了 Mypy，大约一年后实现了全面的类型覆盖，从此成为了快乐的 Mypy 用户。
几周前，我跟 Leo Boytsov 和 Erik Bernhardsson 在 Twitter 上对 Python 类型有一次简短的讨论——然后我看到 Will McGugan 也对类型大加赞赏。由于 Mypy 是我们在 Spring 公司发布和迭代 Python 代码的关键部分，我想写一下我们在过去几年中大规模使用它的经验。
一句话总结：虽然采用 Mypy 是有代价的（前期和持续的投入、学习曲线等），但我发现它对于维护大型 Python 代码库有着不可估量的价值。Mymy 可能不适合于所有人，但它十分适合我。
Mypy 是什么？

（如果你很熟悉 Mypy，可跳过本节。）
Mypy 是 Python 的一个静态类型检查工具。如果你写过 Python 3，你可能会注意到 Python 支持类型注解，像这样:
  1. def greeting(name: str) -> str:
  2.     return 'Hello ' + name
复制代码
Python 在 2014 年通过 PEP-484 定义了这种类型注解语法。虽然这些注解是语言的一部分，但 Python（以及相关的第一方工具）实际上并不拿它们来强制做到类型安全。
相反，类型检查通过第三方工具来实现。Mypy 就是这样的工具。Facebook 的 Pyre也是这样的工具——但就我所知，Mypy 更受欢迎（Mypy 在 GitHub 上有两倍多的星星，它是 Pants 默认使用的工具）。IntelliJ 也有自己的类型检查工具，支持在 PyCharm 中实现类型推断。这些工具都声称自己“兼容 PEP-484”，因为它们使用 Python 本身定义的类型注解。
（译注：最著名的类型检查工具还有谷歌的pytype 和微软的pyright ，关于基本情况介绍与对比，可查阅这篇文章 ）
换句话说：Python 认为自己的责任是定义类型注解的语法和语义（尽管 PEP-484 本身很大程度上受到了 Mypy 现有版本的启发），但有意让第三方工具来检查这些语义。
请注意，当你使用像 Mypy 这样的工具时，你是在 Python 本身之外运行它的——比如，当你运行mypy path/to/file.py 后，Mypy 会把推断出的违规代码都吐出来。Python 在运行时显露但不利用那些类型注解。
（顺便一提：在写本文时，我了解到相比于 Pypy 这样的项目，Mypy 最初有着非常不同的目标。那时还没有 PEP-484（它的灵感来自 Mypy！），所以 Mypy 定义了自己的语法，与 Python 不同，并实现了自己的运行时（也就是说，Mypy 代码是通过 Mypy 执行的）。当时，Mypy 的目标之一是利用静态类型、不可变性等来提高性能——而且明确地避开了与 CPython 兼容。Mypy 在 2013 年切换到兼容 Python 的语法，而 PEP-484 在 2015 年才推出。（“使用静态类型加速 Python”的概念催生了 Mypyc，它仍然是一个活跃的项目，可用于编译 Mypy 本身。））
在 Spring 集成 Mypy

我们在 2019 年 7 月将 Mypy 引入代码库（#1724）。当首次发起提议时，我们有两个主要的考虑：
尽管有所犹豫，我们还是决定给 Mypy 一个机会。在公司内部，我们有强烈偏好于静态类型的工程师文化（除了 Python，我们写了很多 Rust 和 TypeScript）。所以，我们准备使用 Mypy。
我们首先类型化了一些文件。一年后，我们完成了全部代码的类型化（#2622），并升级到最严格的 Mypy 设置（最关键的是 disallow_untyped_defs ，它要求对所有函数签名进行注解），从那时起，我们一直维护着这些设置。（Wolt 团队有一篇很好的文章，他们称之为“专业级的 Mypy 配置”，巧合的是，我们使用的正是这种配置。）
Mypy 配置：https://blog.wolt.com/engineering/2021/09/30/professional-grade-mypy-configuration/
反馈

总体而言：我对 Mypy 持积极的看法。 作为核心基础设施的开发人员（跨服务和跨团队使用的公共库），我认为它极其有用。
我将在以后的任何 Python 项目中继续使用它。
好处

Zulip 早在 2016 年写了一篇漂亮的文章，内容关于使用 Mypy 的好处（这篇文章也被收入了 Mypy 官方文档 中）。
Zulip 博文：https://blog.zulip.com/2016/10/13/static-types-in-python-oh-mypy/#benefitsofusingmypy
我不想重述静态类型的所有好处（它很好），但我想简要地强调他们在帖子中提到的几个好处：
第三点的价值怎么强调都不为过。毫不夸张地说，在 Mypy 的帮助下，我发布更改的速度快了十倍，甚至快了一百倍。
虽然这是完全主观的，但在写这篇文章时，我意识到：我信任 Mypy。虽然程度还不及，比如说 OCaml 编译器，但它完全改变了我维护 Python 代码的关系，我无法想象回到没有注解的世界。
痛点

Zulip 的帖子同样强调了他们在迁移 Mypy 时所经历的痛点（与静态代码分析工具的交互，循环导入）。
坦率地说，我在 Mypy 上经历的痛点与 Zulip 文章中提到的不一样。我把它们分成三类：
让我们来逐一回顾一下：
1. 外部库缺乏类型注解

最重要的痛点是，我们引入的大多数第三方 Python 库要么是无类型的，要么不兼容 PEP-561。在实践中，这意味着对这些外部库的引用会被解析为不兼容，这会大大削弱类型的覆盖率。
每当在环境里添加一个第三方库时，我们都会在mypy.ini 里添加一个许可条目，它告诉 Mypy 要忽略那些模块的类型注解（有类型或提供类型存根的库，比较罕见）：
  1. [mypy-altair.*]
  2. ignore_missing_imports = True
  4. [mypy-apache_beam.*]
  5. ignore_missing_imports = True
  7. [mypy-bokeh.*]
  8. ignore_missing_imports = True
  10. ...
复制代码
由于有了这样的安全出口，即使是随便写的注解也不会生效。例如，Mypy 允许这样做：
  1. import pandas as pd
  3. def return_data_frame() -> pd.DataFrame:
  4.     """Mypy interprets pd.DataFrame as Any, so returning a str is fine!"""
  5.     return "Hello, world!"
复制代码
除了第三方库，我们在 Python 标准库上也遇到了一些不顺。例如，functools.lru_cache 尽管在  typeshed 里有类型注解，但由于复杂的原因，它不保留底层函数的签名，所以任何用 @functools.lru_cache 装饰的函数都会被移除所有类型注解。
例如，Mypy 允许这样做：
  1. import functools
  3. @functools.lru_cache
  4. def add_one(x: float) -> float:
  5.     return x + 1
  7. add_one("Hello, world!")
复制代码
第三方库的情况正在改善。例如，NumPy 在 1.20 版本中开始提供类型。Pandas 也有一系列公开的类型存根 ，但它们被标记为不完整的。（添加存根到这些库是非常重要的，这是一个巨大的成就！）另外值得一提的是，我最近在 Twitter 上看到了 Wolt 的 Python 项目模板 ，它也默认包括类型。
所以，类型正在变得不再罕见。过去当我们添加一个有类型注解的依赖时，我会感到惊讶。有类型注解的库还是少数，并未成为主流。
2. Mypy 学习曲线

大多数加入 Spring 的人没有使用过 Mypy（写过 Python），尽管他们基本知道并熟悉 Python 的类型注解语法。
同样地，在面试中，候选人往往不熟悉typing 模块。我通常在跟候选人作广泛的技术讨论时，会展示一个使用了typing.Protocol 的代码片段，我不记得有任何候选人看到过这个特定的构造——当然，这完全没问题！但这体现了 typing 在 Python 生态的流行程度。
所以，当我们招募团队成员时，Mypy 往往是他们必须学习的新东西。虽然类型注解语法的基础很简单，但我们经常听到这样的问题：“为什么 Mypy 会这样？”、“为什么 Mypy 在这里报错？”等等。
例如，这是一个通常需要解释的例子：
  1. if condition:
  2.         value: str = "Hello, world"
  3. else:
  4.   # Not ok -- we declared `value` as `str`, and this is `None`!
  5.   value = None
  7. ...
  9. if condition:
  10.         value: str = "Hello, world"
  11. else:
  12.   # Not ok -- we already declared the type of `value`.
  13.   value: Optional[str] = None
  15. ...
  17. # This is ok!
  18. if condition:
  19.         value: Optional[str] = "Hello, world"
  20. else:
  21.   value = None
复制代码
另外，还有一个容易混淆的例子:
  1. from typing import Literal
  3. def my_func(value: Literal['a', 'b']) -> None:
  4.   ...
  6. for value in ('a', 'b'):
  7.         # Not ok -- `value` is `str`, not `Literal['a', 'b']`.
  8.   my_func(value)
复制代码
当解释之后，这些例子的“原因”是有道理的，但我不可否认的是，团队成员需要耗费时间去熟悉 Mypy。有趣的是，我们团队中有人说 PyCharm 的类型辅助感觉还不如在同一个 IDE 中使用 TypeScript 得到的有用和完整（即使有足够的静态类型）。不幸的是，这只是使用 Mypy 的代价。
除了学习曲线之外，还有持续地注解函数和变量的开销。我曾建议对某些“种类”的代码（如探索性数据分析）放宽我们的 Mypy 规则——然而，团队的感觉是注解是值得的，这件事很酷。
3. 对抗类型系统

在编写代码时，我会尽量避免几件事，以免导致自己与类型系统作斗争：写出我知道可行的代码，并强迫 Mypy 接受。
首先是@overload ，来自typing 模块：非常强大，但很难正确使用。当然，如果需要重载一个方法，我就会使用它——但是，就像我说的，如果可以的话，我宁可避免它。
基本原理很简单：
  1. @overload
  2. def clean(s: str) -> str:
  3.     ...
  5. @overload
  6. def clean(s: None) -> None:
  7.     ...
  9. def clean(s: Optional[str]) -> Optional[str]:
  10.     if s:
  11.         return s.strip().replace("\u00a0", " ")
  12.     else:
  13.         return None
复制代码
但通常，我们想要做一些事情，比如“基于布尔值返回不同的类型，带有默认值”，这需要这样的技巧：
  1. @overload
  2. def lookup(
  3.     paths: Iterable[str], *, strict: Literal[False]
  4. ) -> Mapping[str, Optional[str]]:
  5.     ...
  8. @overload
  9. def lookup(
  10.     paths: Iterable[str], *, strict: Literal[True]
  11. ) -> Mapping[str, str]:
  12.     ...
  15. @overload
  16. def lookup(
  17.     paths: Iterable[str]
  18. ) -> Mapping[str, Optional[str]]:
  19.     ...
  22. def lookup(
  23.     paths: Iterable[str], *, strict: Literal[True, False] = False
  24. ) -> Any:
  25.     pass
复制代码
即使这是一个 hack——你不能传一个bool到 find_many_latest，你必须传一个字面量 True 或False。
同样地，我也遇到过其它问题，使用 @typing.overload 或者@overload 、在类方法中使用@overload ，等等。
其次是TypedDict ，同样来自typing 模块：可能很有用，但往往会产生笨拙的代码。
例如，你不能解构一个TypedDict ——它必须用字面量 key 构造——所以下方第二种写法是行不通的：
  1. from typing import TypedDict
  3. class Point(TypedDict):
  4.     x: float
  5.     y: float
  7. a: Point = {"x": 1, "y": 2}
  9. # error: Expected TypedDict key to be string literal
  10. b: Point = {**a, "y": 3}
复制代码
在实践中，很难用TypedDict对象做一些 Pythonic 的事情。我最终倾向于使用 dataclass 或 typing.NamedTuple 对象。
第三是装饰器。Mypy 的文档 对保留签名的装饰器和装饰器工厂有一个规范的建议。它很先进，但确实有效：
  1. F = TypeVar("F", bound=Callable[..., Any])
  3. def decorator(func: F) -> F:
  4.     def wrapper(*args: Any, **kwargs: Any):
  5.         return func(*args, **kwargs)
  7.     return cast(F, wrapper)
  9. @decorator
  10. def f(a: int) -> str:
  11.     return str(a)
复制代码
但是，我发现使用装饰器做任何花哨的事情（特别是不保留签名的情况），都会导致代码难以类型化或者充斥着强制类型转换。
这可能是一件好事！Mypy 确实改变了我编写 Python 的方式：耍小聪明的代码更难被正确地类型化，因此我尽量避免编写讨巧的代码。
（装饰器的另一个问题是我前面提过的@functools.lru_cache ：由于装饰器最终定义了一个全新的函数，所以如果你不正确地注解代码，就可能会出现严重而令人惊讶的错误。）
我对循环导入也有类似的感觉——由于要导入类型作为注解使用，这就可能导致出现本可避免的循环导入（这也是 Zulip 团队强调的一个痛点）。虽然循环导入是 Mypy 的一个痛点，但这通常意味着系统或代码本身存在着设计缺陷，这是 Mypy 强迫我们去考虑的问题。
不过，根据我的经验，即使是经验丰富的 Mypy 用户，在类型检查通过之前，他们也需对本来可以正常工作的代码进行一两处更正。
（顺便说一下：Python 3.10 使用ParamSpec 对装饰器的情况作了重大的改进。）
提示与技巧

最后，我要介绍几个在使用 Mypy 时很有用的技巧。
1. reveal_type

在代码中添加reveal_type ，可以让 Mypy 在对文件进行类型检查时，显示出变量的推断类型。这是非常非常非常有用的。
最简单的例子是：
  1. # No need to import anything. Just call `reveal_type`.
  2. # Your editor will flag it as an undefined reference -- just ignore that.
  3. x = 1
  4. reveal_type(x)  # Revealed type is "builtins.int"
复制代码
当你处理泛型时，reveal_type 特别地有用，因为它可以帮助你理解泛型是如何被“填充”的、类型是否被缩小了，等等。
2. Mypy 作为一个库

Mypy 可以用作一个运行时库！
我们内部有一个工作流编排库，看起来有点像 Flyte 或 Prefect。细节并不重要，但值得注意的是，它是完全类型化的——因此我们可以静态地提升待运行任务的类型安全性，因为它们被链接在一起。
把类型弄准确是非常具有挑战性的。为了确保它完好，不被意外的Any毒害，我们在一组文件上写了调用 Mypy 的单元测试，并断言 Mypy 抛出的错误能匹配一系列预期内的异常：
  1. def test_check_function(self) -> None:
  2.           result = api.run(
  3.               [
  4.                   os.path.join(
  5.                       os.path.dirname(__file__),
  6.                       "type_check_examples/function.py",
  7.                   ),
  8.                   "--no-incremental",
  9.               ],
  10.           )
  11.        
  12.           actual = result[0].splitlines()
  13.           expected = [
  14.               # fmt: off
  15.               'type_check_examples/function.py:14: error: Incompatible return value type (got "str", expected "int")',  # noqa: E501
  16.               'type_check_examples/function.py:19: error: Missing positional argument "x" in call to "__call__" of "FunctionPipeline"',  # noqa: E501
  17.               'type_check_examples/function.py:22: error: Argument "x" to "__call__" of "FunctionPipeline" has incompatible type "str"; expected "int"',  # noqa: E501
  18.               'type_check_examples/function.py:25: note: Revealed type is "builtins.int"',  # noqa: E501
  19.               'type_check_examples/function.py:28: note: Revealed type is "builtins.int"',  # noqa: E501
  20.               'type_check_examples/function.py:34: error: Unexpected keyword argument "notify_on" for "options" of "Expression"',  # noqa: E501
  21.               'pipeline.py:307: note: "options" of "Expression" defined here',  # noqa: E501
  22.               "Found 4 errors in 1 file (checked 1 source file)",
  23.               # fmt: on
  24.           ]
  25.        
  26.           self.assertEqual(actual, expected)
复制代码
3. GitHub 上的问题

当搜索如何解决某个类型问题时，我经常会找到 Mypy 的 GitHub Issues （比 Stack Overflow 还多）。它可能是 Mypy 类型相关问题的解决方案和 How-To 的最佳知识源头。你会发现其核心团队（包括 Guido）对重要问题的提示和建议。
主要的缺点是，GitHub Issue 中的每个评论仅仅是某个特定时刻的评论——2018 年的一个问题可能已经解决了，去年的一个变通方案可能有了新的最佳实践。所以在查阅 issue 时，一定要把这一点牢记于心。
4. typing-extensions

typing 模块在每个 Python 版本中都有很多改进，同时，还有一些特性会通过typing-extensions 模块向后移植。
例如，虽然只使用 Python 3.8，但我们借助typing-extensions ，在前面提到的工作流编排库中使用了3.10 版本的ParamSpec。（遗憾的是，PyCharm 似乎不支持通过typing-extensions 引入的ParamSpec 语法，并将其标记为一个错误，但是，还算好吧。）当然，Python 本身语法变化而出现的特性，不能通过typing-extensions 获得。
5. NewType

在 typing 模块中有很多有用的辅助对象，NewType 是我的最爱之一。
NewType 可让你创建出不同于现有类型的类型。例如，你可以使用NewType 来定义合规的谷歌云存储 URL，而不仅是str 类型，比如：
  1. from typing import NewType
  3. GCSUrl = NewType("GCSUrl", str)
  5. def download_blob(url: GCSUrl) -> None:
  6.     ...
  8. # Incompatible type "str"; expected "GCSUrl"
  9. download_blob("gs://my_bucket/foo/bar/baz.jpg")
  11. # Ok!
  12. download_blob(GCSUrl("gs://my_bucket/foo/bar/baz.jpg"))
复制代码
通过向download_blob 的调用者指出它的意图，我们使这个函数具备了自描述能力。
我发现 NewType对于将原始类型（如 str 和 int ）转换为语义上有意义的类型特别有用。
6. 性能

Mypy 的性能并不是我们的主要问题。Mypy 将类型检查结果保存到缓存中，能加快重复调用的速度（据其文档称：“Mypy 增量地执行类型检查，复用前一次运行的结果，以加快后续运行的速度”）。
在我们最大的服务中运行 mypy，冷缓存大约需要 50-60 秒，热缓存大约需要 1-2 秒。
至少有两种方法可以加速 Mypy，这两种方法都利用了以下的技术（我们内部没有使用）：
结论

Mypy 对我们产生了很大的影响，提升了我们发布代码时的信心。虽然采纳它需要付出一定的成本，但我们并不后悔。
除了工具本身的价值之外，Mypy 还是一个让人印象非常深刻的项目，我非常感谢维护者们多年来为它付出的工作。在每一个 Mypy 和 Python 版本中，我们都看到了对 typing模块、注解语法和 Mypy 本身的显著改进。（例如：新的联合类型语法（ X|Y）、 ParamSpec 和 TypeAlias，这些都包含在 Python 3.10 中。）
原文发布于 2022 年 8 月 21 日。
作者：Charlie Marsh
译者：豌豆花下猫@Python猫
英文：Using Mypy in production at Spring (https://notes.crmarsh.com/using-mypy-in-production-at-spring)

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！



欢迎光临 ToB企服应用市场:ToB评测及商务社交产业平台 (https://dis.qidao123.com/) Powered by Discuz! X3.4