setuptools-grpc

Plugin for setuptools to compile protobuf and gRPC service files to python modules.

This package provides build_grpc command for setuptools. Its purpose is to build gRPC modules during build step of setuptools packaging.

What this isn't

This is not a command line script.

Direct invocation of setup.py (such as python setup.py build_grpc) has been deprecated and will be removed in future version of setuptools.

If you'd like to have CLI for building gRPC modules, use grpcio-tools directly (that's what this package uses under the hood). After installing that package, you can learn about its options by running python -m grpc_tools.protoc --help.

Installation

You probably shouldn't install this package directly. Instead, you should add it to the build-system.requires in pyproject.toml. See Configuration.

Options

Command build_grpc provides following options:

• proto_files: Newline separated list of glob patterns matching protobuf files to be compiled. Paths are relative to proto_path. ** can be used to match any files and zero or more directories. Default value is empty list.
• grpc_files: Newline separated list of glob patterns matching grpc service files to be compiled. Paths are relative to proto_path. ** can be used to match any files and zero or more directories. Default value is empty list.
• proto_path: Path to root directory with protobuf files. This path is passed through -I option to grpc_tools.protoc. Default is . (current directory).
• output_path: Path to root directory for generated python modules. This path is passed through --python_out or --grpc_python_out option to grpc_tools.protoc. Default is . (current directory).

Configuration

You have to specify setuptools-grpc as part of build backend requirements. This follows specification introduced in PEP 518. You can read more about it in setuptools docs.

# file: pyproject.toml
[build-system]
requires = ["setuptools", "setuptools-grpc"]
build-backend = "setuptools.build_meta"

Next, you need to configure setuptools_grpc itself. This can be done in setup.py, but we recommend declarative config in setup.cfg. Depending on your project structure, you may not need some of the options below. You'll always need to specify at least proto_files or grpc_files, otherwise setuptools_grpc won't do anything.

# file: setup.cfg
[build_grpc]
proto_files = **/*.proto
grpc_files = **/*_grpc.proto
proto_path = ./src
output_path = ./out

It's also recommended to add generated files to your MANIFEST.in. Otherwise they might be missing from the built wheel. See setuptools docs for more details about how files are included in the distribution.

# file: MANIFEST.in
graft out