Add type stub files to the Python package

[jenstroeger]

Is your feature request related to a problem? Please describe.

Currently, the generated Python files are not accompanied by type stub files, which, in turn, forces users to disable type checking for some of their gRPC related code. The low-profile (and unmaintained?) package henribru/googleapis-common-protos-stubs provides stubs; however, it’s not been updated recently and its versioning does not lockstep with the actual Python package. It also requires users to take dependency on yet another third-party package that’s not officially maintained by gRPC/Google.

Describe the solution you'd like

I don’t see a problem to generate the type stub files as part of the official package. First, take a look at nipunn1313/mypy-protobuf which provides a protoc plugin to generate said type stub files alongside the Python files. The current proto compilation here

https://github.com/googleapis/api-common-protos/blob/3332dec527759859840a3a2ff108c67a54708130/.circleci/config.yml#L51-L56

would need to be expanded:

1. Install the plugin as per instructions
2. Invoke the plugin

   protoc --proto_path=/usr/src/protoc/include --proto_path=. \
     --python_out=$PYTHON_PROTO_PATH \
     --mypy_out=$PYTHON_PROTO_PATH \
     --mypy_grpc_out=$PYTHON_PROTO_PATH \
     $(find google -not -path "*/iam/*" -name "*.proto")

3. Add the PEP-561 marker to the package.

Describe alternatives you've considered

The alternative is to either ignore missing imports, or use the aforementioned third-party package and bear the risks such a dependency brings.

Additional context

None.

[aabmass]

There's also support for this directly in protoc with --pyi_out option protocolbuffers/protobuf#2638.

[jenstroeger]

@aabmass are you saying that --pyi_out built into protoc (available sometime soon?) will replace the --mypy_out* options mentioned above?

[aabmass]

Not sure about replacing it, but might be easier to add a single "first party" flag than a new protoc plugin. There is some discussion in nipunn1313/mypy-protobuf#368 comparing these two generators.

That said, I don't think the version of protoc/grpcio-tools used here supports it either based on googleapis/python-api-common-protos#141

[troyswanson]

Hi, I'd like to bump this issue, please. Type hints for these generated protobuf message types would be very helpful.

[parthea]

Transferring this issue to google-cloud-python as the code for python-api-common-protos will be migrated there