nipunn1313/mypy-protobuf

这是什么？

核心功能

• 01生成能体现字段是否存在的构造函数类型标注。
• 02为 HasField、WhichOneof、ClearField 提供带类型的方法签名。
• 03将 .proto 注释转换为 .pyi 中的 docstring，IDE 补全时可见。
• 04用 NewType 包装枚举值，类型检查器可以发现误用的枚举值。
• 05为 gRPC 服务和客户端生成同步与异步存根。
• 06支持为标量和 map 字段指定自定义类型包装。

适用场景

• 在使用 protobuf 消息的 Python 项目中启用 mypy 或 pyright 类型检查。
• 为 Python 服务生成带类型的 gRPC 客户端和服务端存根。
• 改善生成的 protobuf 类在 IDE 中的自动补全和文档提示。

快速上手

1. 1

   从 protobuf 发布页面安装 protoc（32.0 或更新版本）

2. 2

   使用 pip 安装插件

   pip3 install mypy-protobuf
3. 3

   使用 protoc 生成与 Python 代码并列的 mypy 存根文件

   protoc --python_out=output/location --mypy_out=output/location

使用前须知

• !需要较新的版本：protoc 32.0 或更新版本，以及 python-protobuf 6.32 或更新版本；更早的版本未经测试。

收录于专题

标签

常见问题

mypy-protobuf 是什么？

一个 protoc 插件，从 Protocol Buffers 定义生成 Python 的 .pyi 类型存根文件。 mypy-protobuf 是一个 protoc 插件，可以从 .proto 文件生成与 mypy 兼容的 .pyi 存根文件。生成的类型信息能让 mypy、pyright 等类型检查器在静态检查阶段发现问题，而不必等到运行时。

mypy-protobuf 可以免费使用吗？用的什么许可证？

mypy-protobuf 以 Apache-2.0 许可证开源。用于商业产品前，请先确认许可证条款。

mypy-protobuf 还在维护吗？

活跃维护中。mypy-protobuf 最近一次提交是在 2026年11月2日。

mypy-protobuf 适合用来做什么？

在使用 protobuf 消息的 Python 项目中启用 mypy 或 pyright 类型检查。 为 Python 服务生成带类型的 gRPC 客户端和服务端存根。 改善生成的 protobuf 类在 IDE 中的自动补全和文档提示。

mypy-protobuf 怎么安装和运行？

从 protobuf 发布页面安装 protoc（32.0 或更新版本） 使用 pip 安装插件: pip3 install mypy-protobuf 使用 protoc 生成与 Python 代码并列的 mypy 存根文件: protoc --python_out=output/location --mypy_out=output/location

在哪里获取 mypy-protobuf？

源代码和安装说明在 GitHub 上：https://github.com/nipunn1313/mypy-protobuf