Guide to Techmo ASR API usage for Python¶

Introduction¶

Before you get started, know that there is an officially supported PyPI package (techmo-asr-api-python) from Techmo with Python sources already generated from the APIs. By using it, you do not need to follow the steps below to generate code and go directly to the example of using it.

Note. Unless otherwise specified, assume that command examples are called from the root of the repository.

Code generation tutorial¶

The tutorial is based on .proto files from techmo.asr.api.v1. If you need to generate code for another API release, refer to these lists from the general usage guide to select input files.

TL;DR¶

Install grpcio-tools.

python3 -m venv .venv
source .venv/bin/activate
pip install --require-virtualenv grpcio-tools

Compile .proto files of your choice.

mkdir out
python -m grpc_tools.protoc --proto_path=./proto --python_out=./out --pyi_out=./out ./proto/techmo/api/status.proto ./proto/techmo/asr/api/v1/asr.proto
python -m grpc_tools.protoc --proto_path=./proto --grpc_python_out=./out ./proto/techmo/asr/api/v1/asr.proto

Getting a compiler¶

To generate source code from .proto files (protos), a compiler (protoc) is required. If you have not installed it, for Python, you may:

download (or even build) it with the Protocol Buffers library*

simply use it from an all-in-one PyPI package (grpcio-tools) from Google (Example 1.).

Example 1. Installing grpcio-tools.

pip install --require-virtualenv grpcio-tools

There is no better approach. The first is universal across different languages; the latter is easier, however.

* With protoc, to generate sources for gRPC, you will also need to get a separate plugin for the compiler (grpc_python_plugin) from the gRPC repository (downloadable or buildable). With grpcio-tools, the plugin is already included.

Compiling the protos¶

Once you have the compiler, it is time to generate the sources. First, create a directory for them (Example 2.). This step is not required but recommended.

Example 2. Creating an output directory.

mkdir out

Compiling the protos with protoc¶

Before calling protoc, ensure it is in the PATH environment variable or use absolute paths. The same applies to the gRPC plugin.

Example 3. Compiling a .proto file with the official Protocol Buffers compiler.

protoc --proto_path=./proto --python_out=./out ./proto/techmo/api/status.proto ./proto/techmo/asr/api/v1/asr.proto
protoc --proto_path=./proto --plugin=protoc-gen-grpc="$(which grpc_python_plugin)" --grpc_out=./out ./proto/techmo/asr/api/v1/asr.proto

Note. For .proto files without service, the --plugin and --grpc_out parameters are redundant. You can omit them in this case, not to generate a *_pb2_grpc.py file.

Compiling the protos with grpcio-tools¶

Example 4. Compiling a .proto file with grpcio-tools.

python -m grpc_tools.protoc --proto_path=./proto --python_out=./out --pyi_out=./out ./proto/techmo/api/status.proto ./proto/techmo/asr/api/v1/asr.proto
python -m grpc_tools.protoc --proto_path=./proto --grpc_python_out=./out ./proto/techmo/asr/api/v1/asr.proto

Note. For .proto files without service, the --grpc_python_out parameter is redundant. You can omit it in this case, not to generate a *_pb2_grpc.py file.

Outcome¶

In both cases, if everything goes fine, you find some Python sources with Protocol Buffers (*_pb2.py, *_pb2.pyi*) and gRPC (*_pb2_grpc.py) classes in the out directory.

* .pyi files only with grpcio-tools.

Generated code usage tutorial¶

techmo.asr.api.v1¶

Invoking an RPC¶

TODO