Package: uplink-protobuf
Uplink + Protocol Buffersuplink-protobufmakes it easy to send and receive protobuf messages over HTTP.This library is anUplinkplugin.Table of ContentsInstallationBasic UsageReceiving Protobuf MessagesSending Protobuf MessagesCommunicating with a JSON APIConverting JSON Responses into Protobuf MessagesConverting Protobuf Messages into JSON RequestsJSON OptionsFAQsInstallation$ pip install uplink-protobufBasic UsageReceiving Protobuf MessagesFor anyConsumermethod that is expecting a protobuf encoded response,
simply set the appropriate protobuf message type as the method'sreturn
value annotation:fromuplinkimportConsumer,get# Import Python code generated by Google's protobuf compiler:fromaddressbook_pb2.pyimportPersonclassAddressBookClient(Consumer):@get("/persons/{person_id}")defget_person(self,person_id)->Person:passThen 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:1234email:"omar.little@example.com"phones{number:"555-4321"type:HOME}Sending Protobuf MessagesFor aConsumermethod that needs to send a protobuf encoded request,
simply annotate the appropriate method argument withuplink.Body:fromuplinkimportConsumer,post,Body# Import Python code generated by Google's protobuf compiler:fromaddressbook_pb2.pyimportPersonclassAddressBookClient(Consumer):@post("/persons")defcreate_person(self,person:Body(type=Person)):passThen 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=5678person.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 APIThis library also supports converting JSON responses and requests
to and from protobuf messages.Converting JSON Responses into Protobuf Messagesuplink-protobufcan automatically convert JSON responses into
protobuf messages if theConsumermethod is annotated withreturns.from_json:fromuplinkimportConsumer,get,returns# Import Python code generated by Google's protobuf compiler:fromaddressbook_pb2.pyimportPersonclassAddressBookClient(Consumer):@returns.from_json@get("/persons/{person_id}")defget_person(self,person_id)->Person:passConverting Protobuf Messages into JSON Requestsuplink-protobufcan automatically convert a protobuf message into
JSON request body if theConsumermethod is annotated withuplink.json:fromuplinkimportConsumer,post,Body,json# Import Python code generated by Google's protobuf compiler:fromaddressbook_pb2.pyimportPersonclassAddressBookClient(Consumer):@json@post("/persons")defcreate_person(self,person:Body(type=Person)):passJSON OptionsThere are also a few decorators we provide that allows you to control
the JSON conversion. These decorators are available through theuplink_protobuf.json_optionssubmodule.Options for Sending JSON RequestsHere 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 ResponsesNext, 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 aConsumerthat uses these options:fromuplinkimportConsumer,post,Bodyfromuplink_protobufimportjson_options# Import Python code generated by Google's protobuf compiler:fromaddressbook_pb2.pyimportPersonclassAddressBookClient(Consumer):@returns.from_json@json_options.ignore_unknown_fields@get("/persons/{person_id}")defget_person(self,person_id)->Person:pass@json@json_options.include_default_value_fields@post("/persons")defcreate_person(self,person:Body(type=Person)):passFAQsWhat is Protocol Buffers?Checkout Google's official Protocol BuffersDeveloper Guide.How do I install Google's protobuf compiler,protoc?Checkoutthis guidefor installation instructions with Mac
and Linux.How do compile my.protofile usingprotoc?Refer tothis sectionin the offical Protocol Buffers Developer Guide.What is Uplink?It's a "Declarative HTTP Client". Checkout the library'sGitHub repofor more.