Uplink + Protocol Buffers

uplink-protobuf makes it easy to send and receive protobuf messages over HTTP.

This library is an Uplink plugin.

Table of Contents

• Installation
• Basic Usage
  • Receiving Protobuf Messages
  • Sending Protobuf Messages
• Communicating with a JSON API
  • Converting JSON Responses into Protobuf Messages
  • Converting Protobuf Messages into JSON Requests
  • JSON Options
• FAQs

Installation

$ pip install uplink-protobuf

Basic Usage

Receiving Protobuf Messages

For any Consumer method that is expecting a protobuf encoded response, simply set the appropriate protobuf message type as the method's return value annotation:

from uplink import Consumer, get

# Import Python code generated by Google's protobuf compiler:
from addressbook_pb2.py import Person

class AddressBookClient(Consumer):
    @get("/persons/{person_id}")
    def get_person(self, person_id) -> Person:
        pass

Then when invoked, the annotated method will appropriately decode the response into the specified message type:

>>> addressbook_client = AddressBookClient(base_url=BASE_URL)
>>> addressbook_client.get_person(1234)
name: "Omar Little"
id: 1234
email: "omar.little@example.com"
phones {
  number: "555-4321"
  type: HOME
}

Sending Protobuf Messages

For a Consumer method that needs to send a protobuf encoded request, simply annotate the appropriate method argument with uplink.Body:

from uplink import Consumer, post, Body

# Import Python code generated by Google's protobuf compiler:
from addressbook_pb2.py import Person

class AddressBookClient(Consumer):
    @post("/persons")
    def create_person(self, person: Body(type=Person)):
        pass

Then when the method is invoked, the value of the annotated argument is automatically encoded:

# Register new person:
person = Person()
person.name = "Stringer Bell"
person.id = 5678
person.email = "stringer.bell@example.com"

# Send person to API:
addressbook_client = AddressBookClient(base_url=BASE_URL)
addressbook_client.create_person(person)

Communicating with a JSON API

This library also supports converting JSON responses and requests to and from protobuf messages.

Converting JSON Responses into Protobuf Messages

uplink-protobuf can automatically convert JSON responses into protobuf messages if the Consumer method is annotated with returns.from_json:

from uplink import Consumer, get, returns

# Import Python code generated by Google's protobuf compiler:
from addressbook_pb2.py import Person

class AddressBookClient(Consumer):
    @returns.from_json
    @get("/persons/{person_id}")
    def get_person(self, person_id) -> Person:
        pass

Converting Protobuf Messages into JSON Requests

uplink-protobuf can automatically convert a protobuf message into JSON request body if the Consumer method is annotated with uplink.json:

from uplink import Consumer, post, Body, json

# Import Python code generated by Google's protobuf compiler:
from addressbook_pb2.py import Person

class AddressBookClient(Consumer):
    @json
    @post("/persons")
    def create_person(self, person: Body(type=Person)):
        pass

JSON Options

There are also a few decorators we provide that allows you to control the JSON conversion. These decorators are available through the uplink_protobuf.json_options submodule.

Options for Sending JSON Requests

Here are options that can be used with @json, to control the conversion of protobuf messages to JSON objects:

• @json_options.include_default_value_fields: This decorator indicates that the JSON output should include fields with their default values. By default, default values are omitted if the field is not set.
• @json_options.preserve_proto_field_names: This decorator indicates that the JSON output should use the proto field names as the JSON names. By default, the JSON printer converts each proto field name to lowerCamelCase and uses that as the JSON name.
• @json_options.use_integers_for_enums: This decorator indicates that the JSON output should use the numerical value of a proto enum value, instead of the name of the enum value. By default, the name of an enum value is used in the JSON output.

Options for Parsing JSON Responses

Next, Here are options that can be used with @returns.json, to control the conversion of JSON responses to protobuf messages:

• @json_options.ignore_unknown_fields: This decorator indicates that the JSON parser should ignore unknown fields in parsing. By default, the JSON parser raises an error if it encounters an unknown field.

Finally, here's an example of a Consumer that uses these options:

from uplink import Consumer, post, Body
from uplink_protobuf import json_options

# Import Python code generated by Google's protobuf compiler:
from addressbook_pb2.py import Person

class AddressBookClient(Consumer):

    @returns.from_json
    @json_options.ignore_unknown_fields
    @get("/persons/{person_id}")
    def get_person(self, person_id) -> Person:
        pass

    @json
    @json_options.include_default_value_fields
    @post("/persons")
    def create_person(self, person: Body(type=Person)):
        pass

FAQs

• What is Protocol Buffers?

  Checkout Google's official Protocol Buffers Developer Guide.

• How do I install Google's protobuf compiler, protoc?

  Checkout this guide for installation instructions with Mac and Linux.

• How do compile my .proto file using protoc?

  Refer to this section in the offical Protocol Buffers Developer Guide.

• What is Uplink?

  It's a "Declarative HTTP Client". Checkout the library's GitHub repo for more.