Send and receive protobuf messages over HTTP, with ease.
MIT License
uplink-protobuf
makes it easy to send and receive protobuf messages over HTTP.
This library is an Uplink plugin.
$ pip install uplink-protobuf
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: "[email protected]"
phones {
number: "555-4321"
type: HOME
}
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 = "[email protected]"
# Send person to API:
addressbook_client = AddressBookClient(base_url=BASE_URL)
addressbook_client.create_person(person)
This library also supports converting JSON responses and requests to and from 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
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
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.
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@json_options.preserve_proto_field_names
: This decorator indicates@json_options.use_integers_for_enums
: This decorator indicates thatNext, 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 indicatesFinally, 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
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.