Bazel Build

This generator can be called from Bazel, which is a recommended way of using it inside a continuous integration build or any other automated pipeline.

Installing

Bazel

You will need Bazel version 3.0+. Please check the Bazel website for the available installation options.

Bazel is distributed in a form of a single binary, so one of the easiest ways to install it is simply downloading the binary and making it executable:

curl -L https://github.com/bazelbuild/bazel/releases/download/3.2.0/bazel-3.2.0-linux-x86_64 -o bazel
chmod +x bazel

Python and Dependencies

Bazel build is mostly hermetic, with a few exceptions for Python generator. Specifically it expects Python 3.7+ with the python dev packages to be installed.

On Linux, to install those, simply run:

sudo apt-get install \
    python-dev \
    python3-dev

Usage

To use this plugin, you will need an API which is specified using protocol buffers. Additionally, this plugin makes some assumptions at the margins according to Google API design conventions as described in AIPs, so following those conventions is recommended.

Example

To generate a client library with Bazel you will need a Bazel workspace. An example of such workspace would be googleapis. It is already integrated with this this generator in its WORKSPACE file.

You need to clone the googleapis repository from GitHub:

$ git clone https://github.com/googleapis/googleapis.git

The API we use as an example is the Document AI API, available in the google/cloud/documentai/v1beta2/ subdirectory.

Creating the Targets

To build something with bazel you need to create the corresponding targets in your BUILD.bazel file. You can use the Python section of the Document AI BUILD.bazel file as an example:

load(
    "@gapic_generator_python//rules_python_gapic:py_gapic.bzl",
    "py_gapic_library"
)

load(
    "@gapic_generator_python//rules_python_gapic:py_gapic_pkg.bzl",
    "py_gapic_assembly_pkg"
)

py_gapic_library(
    name = "documentai_py_gapic",
    srcs = [":documentai_proto"],
)

py_gapic_assembly_pkg(
    name = "documentai-v1beta2-py",
    deps = [
        ":documentai_py_gapic",
    ],
)

Compiling an API

To generate the client library simply run the bazel command from the repository root, specifying the py_gapic_assembly_pkg target name as the argument:

bazel build //google/cloud/documentai/v1beta2:documentai-v1beta2-py

This will generate a tar.gz archive with the generated library packaged in it. To unpack it in dest location simply run the following command from the Bazel workspace root:

tar -xzpf bazel-bin/google/cloud/documentai/v1beta2/documentai-v1beta2-py.tar.gz -C dest

Verifying the Library

Once you have compiled a client library, whether using a Docker image, local installation or bazel, it is time for the fun part: actually running it!

Create a virtual environment for the library:

$ virtualenv ~/.local/client-lib --python=`which python3.7`
$ source ~/.local/client-lib/bin/activate

Next, install the library:

$ cd dest/
$ pip install --editable .

Now it is time to play with it! Here is a test script:

# This is the client library generated by this plugin.
from google.cloud import vision

# Instantiate the client.
#
# If you need to manually specify credentials, do so here.
# More info: https://cloud.google.com/docs/authentication/getting-started
#
# If you wish, you can send `transport='grpc'` or `transport='http'`
# to change which underlying transport layer is being used.
ia = vision.ImageAnnotatorClient()

# Send the request to the server and get the response.
response = ia.batch_annotate_images({
    'requests': [{
        'features': [{
            'type': vision.Feature.Type.LABEL_DETECTION,
        }],
        'image': {'source': {
            'image_uri': 'https://images.pexels.com/photos/67636'
                         '/rose-blue-flower-rose-blooms-67636.jpeg',
        }},
    }],
})
print(response)