Repolode
Submit
nipunn1313

nipunn1313/mypy-protobuf

A protoc plugin that generates Python .pyi type stub files from Protocol Buffer definitions, with typed HasField, ClearField and gRPC stubs.

View on GitHub
Stars
711
Forks
81
Open issues
31
Last commit
4 days ago

What is it?

mypy-protobuf is a protoc plugin that generates mypy-compatible .pyi stub files from .proto definitions. It gives Python protobuf code static type information so that type checkers such as mypy and pyright can catch errors at check time instead of at runtime.

Compared with the stubs produced by protoc's built-in --pyi_out, the generated files add field-presence-aware constructor types, typed HasField, WhichOneof and ClearField methods, and type aliases for their arguments. Comments in .proto files are carried into the stubs as docstrings, and enum values are wrapped in NewType so that mismatched enum values are flagged. Deprecated elements can be marked with @warnings.deprecated.

The plugin also generates stubs for gRPC services and clients, in both sync and async variants, and supports casttype and keytype/valuetype options for wrapping scalar and map field types. It requires protoc 32 or later and python-protobuf 6.32 or later, and it dropped Python 2 targeting after version 2.10.

Key features

  • 01Generates .pyi stubs with field-presence-aware constructor types.
  • 02Provides typed HasField, WhichOneof and ClearField methods.
  • 03Carries .proto comments into stubs as docstrings.
  • 04Wraps enum values in NewType so mismatched values are caught by type checkers.
  • 05Generates sync and async gRPC service and client stubs.
  • 06Supports custom type wrappers for scalar and map fields.

Use cases

  • Adding static type checking with mypy or pyright to a Python project that uses protobuf messages.
  • Generating typed gRPC client and servicer stubs for Python services.
  • Improving IDE autocomplete and docstrings for generated protobuf classes.

Quick start

  1. 1

    Install protoc (version 32.0 or newer) from the protobuf releases page

  2. 2

    Install the plugin with pip

    pip3 install mypy-protobuf
  3. 3

    Generate mypy stubs alongside your Python code with protoc

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

Things to know

  • Requires recent versions: protoc 32.0 or newer and python-protobuf 6.32 or newer; earlier releases are untested.

In collections

Microservice frameworks & service infrastructure

Topics

#protobuf#type-stubs#mypy#grpc#python#code-generation#typing

FAQ

What is mypy-protobuf?
A protoc plugin that generates Python .pyi type stub files from Protocol Buffer definitions, with typed HasField, ClearField and gRPC stubs. mypy-protobuf is a protoc plugin that generates mypy-compatible .pyi stub files from .proto definitions. It gives Python protobuf code static type information so that type checkers such as mypy and pyright can catch errors at check time instead of at runtime.
Is mypy-protobuf free to use? What license does it have?
mypy-protobuf is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is mypy-protobuf still maintained?
Actively maintained. The last commit to mypy-protobuf was on Nov 2, 2026.
What can I use mypy-protobuf for?
Adding static type checking with mypy or pyright to a Python project that uses protobuf messages. Generating typed gRPC client and servicer stubs for Python services. Improving IDE autocomplete and docstrings for generated protobuf classes.
How do I install mypy-protobuf?
Install protoc (version 32.0 or newer) from the protobuf releases page Install the plugin with pip: pip3 install mypy-protobuf Generate mypy stubs alongside your Python code with protoc: protoc --python_out=output/location --mypy_out=output/location
Where can I get mypy-protobuf?
The source code and installation instructions are on GitHub: https://github.com/nipunn1313/mypy-protobuf

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects