# Uplink + Protocol Buffers
[](https://travis-ci.org/prkumar/uplink-protobuf)
[](https://codecov.io/gh/prkumar/uplink-protobuf)
[](https://codeclimate.com/github/prkumar/uplink-protobuf/maintainability)
[](https://github.com/ambv/black)
`uplink-protobuf` makes it easy to send and receive protobuf messages over HTTP.
This library is an [Uplink](https://github.com/prkumar/uplink) plugin.
## Table of Contents
- **[Installation](#installation)**
- **[Basic Usage](#basic-usage)**
* **[Receiving Protobuf Messages](#receiving-protobuf-messages)**
* **[Sending Protobuf Messages](#sending-protobuf-messages)**
- **[Communicating with a JSON API](#communicating-with-a-json-api)**
* **[Converting JSON Responses into Protobuf Messages](#converting-json-responses-into-protobuf-messages)**
* **[Converting Protobuf Messages into JSON Requests](#converting-protobuf-messages-into-json-requests)**
* **[JSON Options](#json-options)**
- **[FAQs](#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](https://www.python.org/dev/peps/pep-3107/#return-values):
```python
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:
```python
>>> 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`](https://uplink.readthedocs.io/en/stable/quickstart.html#request-body):
```python
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:
```python
# 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`:
```python
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`:
```python
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:
```python
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](https://developers.google.com/protocol-buffers/docs/overview).
- **How do I install Google's protobuf compiler, `protoc`?**
Checkout [this guide](http://google.github.io/proto-lens/installing-protoc.html) for installation instructions with Mac
and Linux.
- **How do compile my `.proto` file using `protoc`?**
Refer to [this section](https://developers.google.com/protocol-buffers/docs/reference/python-generated#invocation)
in the offical Protocol Buffers Developer Guide.
- **What is Uplink?**
It's a "Declarative HTTP Client". Checkout the library's [GitHub repo](https://github.com/prkumar/uplink)
for more.
Raw data
{
"_id": null,
"home_page": "https://github.com/prkumar/uplink-protobuf",
"name": "uplink-protobuf",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "http api rest client retrofit protobuf protocol buffers",
"author": "P. Raj Kumar",
"author_email": "raj.pritvi.kumar@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/28/d8/cf52f9f50e0e425a750f704817cf330c857d3c6bfb96212dc693fa66c9f4/uplink-protobuf-0.1.0.tar.gz",
"platform": "",
"description": "\n# Uplink + Protocol Buffers\n[](https://travis-ci.org/prkumar/uplink-protobuf)\n[](https://codecov.io/gh/prkumar/uplink-protobuf)\n[](https://codeclimate.com/github/prkumar/uplink-protobuf/maintainability)\n[](https://github.com/ambv/black)\n\n`uplink-protobuf` makes it easy to send and receive protobuf messages over HTTP.\n\nThis library is an [Uplink](https://github.com/prkumar/uplink) plugin.\n\n## Table of Contents\n\n- **[Installation](#installation)**\n- **[Basic Usage](#basic-usage)**\n * **[Receiving Protobuf Messages](#receiving-protobuf-messages)**\n * **[Sending Protobuf Messages](#sending-protobuf-messages)**\n- **[Communicating with a JSON API](#communicating-with-a-json-api)**\n * **[Converting JSON Responses into Protobuf Messages](#converting-json-responses-into-protobuf-messages)**\n * **[Converting Protobuf Messages into JSON Requests](#converting-protobuf-messages-into-json-requests)**\n * **[JSON Options](#json-options)**\n- **[FAQs](#faqs)**\n\n## Installation\n\n```\n$ pip install uplink-protobuf\n```\n\n## Basic Usage\n\n### Receiving Protobuf Messages\n\nFor any `Consumer` method that is expecting a protobuf encoded response,\nsimply set the appropriate protobuf message type as the method's [return\nvalue annotation](https://www.python.org/dev/peps/pep-3107/#return-values):\n\n```python\nfrom uplink import Consumer, get\n\n# Import Python code generated by Google's protobuf compiler:\nfrom addressbook_pb2.py import Person\n\nclass AddressBookClient(Consumer):\n @get(\"/persons/{person_id}\")\n def get_person(self, person_id) -> Person:\n pass\n```\n\nThen when invoked, the annotated method will appropriately decode the\nresponse into the specified message type:\n\n```python\n>>> addressbook_client = AddressBookClient(base_url=BASE_URL)\n>>> addressbook_client.get_person(1234)\nname: \"Omar Little\"\nid: 1234\nemail: \"omar.little@example.com\"\nphones {\n number: \"555-4321\"\n type: HOME\n}\n```\n\n### Sending Protobuf Messages\n\nFor a `Consumer` method that needs to send a protobuf encoded request,\nsimply annotate the appropriate method argument with [`uplink.Body`](https://uplink.readthedocs.io/en/stable/quickstart.html#request-body):\n\n```python\nfrom uplink import Consumer, post, Body\n\n# Import Python code generated by Google's protobuf compiler:\nfrom addressbook_pb2.py import Person\n\nclass AddressBookClient(Consumer):\n @post(\"/persons\")\n def create_person(self, person: Body(type=Person)):\n pass\n```\n\nThen when the method is invoked, the value of the annotated argument is\nautomatically encoded:\n\n```python\n# Register new person:\nperson = Person()\nperson.name = \"Stringer Bell\"\nperson.id = 5678\nperson.email = \"stringer.bell@example.com\"\n\n# Send person to API:\naddressbook_client = AddressBookClient(base_url=BASE_URL)\naddressbook_client.create_person(person)\n```\n\n## Communicating with a JSON API\n\nThis library also supports converting JSON responses and requests\nto and from protobuf messages.\n\n### Converting JSON Responses into Protobuf Messages\n\n`uplink-protobuf` can automatically convert JSON responses into\nprotobuf messages if the `Consumer` method is annotated with\n`returns.from_json`:\n\n```python\nfrom uplink import Consumer, get, returns\n\n# Import Python code generated by Google's protobuf compiler:\nfrom addressbook_pb2.py import Person\n\nclass AddressBookClient(Consumer):\n @returns.from_json\n @get(\"/persons/{person_id}\")\n def get_person(self, person_id) -> Person:\n pass\n```\n\n### Converting Protobuf Messages into JSON Requests\n\n`uplink-protobuf` can automatically convert a protobuf message into\nJSON request body if the `Consumer` method is annotated with\n`uplink.json`:\n\n```python\nfrom uplink import Consumer, post, Body, json\n\n# Import Python code generated by Google's protobuf compiler:\nfrom addressbook_pb2.py import Person\n\nclass AddressBookClient(Consumer):\n @json\n @post(\"/persons\")\n def create_person(self, person: Body(type=Person)):\n pass\n```\n\n### JSON Options\n\nThere are also a few decorators we provide that allows you to control\nthe JSON conversion. These decorators are available through the\n`uplink_protobuf.json_options` submodule.\n\n#### Options for Sending JSON Requests\n\nHere are options that can be used with `@json`, to control\nthe conversion of protobuf messages to JSON objects:\n\n- `@json_options.include_default_value_fields`: This decorator\n indicates that the JSON output should include fields with their default\n values. By default, default values are omitted if the field is not set.\n- `@json_options.preserve_proto_field_names`: This decorator indicates\n that the JSON output should use the proto field names as the JSON names.\n By default, the JSON printer converts each proto field name to\n lowerCamelCase and uses that as the JSON name.\n- `@json_options.use_integers_for_enums`: This decorator indicates that\n the JSON output should use the numerical value of a proto enum value,\n instead of the name of the enum value. By default, the name of an\n enum value is used in the JSON output.\n\n\n#### Options for Parsing JSON Responses\n\nNext, Here are options that can be used with `@returns.json`, to control\nthe conversion of JSON responses to protobuf messages:\n\n- `@json_options.ignore_unknown_fields`: This decorator indicates\n that the JSON parser should ignore unknown fields in parsing.\n By default, the JSON parser raises an error if it encounters\n an unknown field.\n\n\nFinally, here's an example of a `Consumer` that uses these options:\n```python\nfrom uplink import Consumer, post, Body\nfrom uplink_protobuf import json_options\n\n# Import Python code generated by Google's protobuf compiler:\nfrom addressbook_pb2.py import Person\n\nclass AddressBookClient(Consumer):\n\n @returns.from_json\n @json_options.ignore_unknown_fields\n @get(\"/persons/{person_id}\")\n def get_person(self, person_id) -> Person:\n pass\n\n @json\n @json_options.include_default_value_fields\n @post(\"/persons\")\n def create_person(self, person: Body(type=Person)):\n pass\n```\n\n## FAQs\n\n- **What is Protocol Buffers?**\n\n Checkout Google's official Protocol Buffers [Developer Guide](https://developers.google.com/protocol-buffers/docs/overview).\n\n- **How do I install Google's protobuf compiler, `protoc`?**\n\n Checkout [this guide](http://google.github.io/proto-lens/installing-protoc.html) for installation instructions with Mac\n and Linux.\n\n- **How do compile my `.proto` file using `protoc`?**\n\n Refer to [this section](https://developers.google.com/protocol-buffers/docs/reference/python-generated#invocation)\n in the offical Protocol Buffers Developer Guide.\n\n- **What is Uplink?**\n\n It's a \"Declarative HTTP Client\". Checkout the library's [GitHub repo](https://github.com/prkumar/uplink)\n for more.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Protocol Buffers (Protobuf) support for Uplink.",
"version": "0.1.0",
"split_keywords": [
"http",
"api",
"rest",
"client",
"retrofit",
"protobuf",
"protocol",
"buffers"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "83266ee21985b19cdcd04e57630a5baafddd2c833b7cbc978f3f0fb97bae2ba7",
"md5": "2e6a5daedbf276ede063cf3caa85d240",
"sha256": "69ab7485657f0a53bf1bcb57078555eb233a27feb63277374a56117e0e9f2e81"
},
"downloads": -1,
"filename": "uplink_protobuf-0.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e6a5daedbf276ede063cf3caa85d240",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6747,
"upload_time": "2018-09-15T00:17:24",
"upload_time_iso_8601": "2018-09-15T00:17:24.268671Z",
"url": "https://files.pythonhosted.org/packages/83/26/6ee21985b19cdcd04e57630a5baafddd2c833b7cbc978f3f0fb97bae2ba7/uplink_protobuf-0.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28d8cf52f9f50e0e425a750f704817cf330c857d3c6bfb96212dc693fa66c9f4",
"md5": "42929391e0e572868eaa276b3620e588",
"sha256": "aa7e1ae29f1c8c3720cd8e6582eceb4633e95a2c86248960532492a9e208ad62"
},
"downloads": -1,
"filename": "uplink-protobuf-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "42929391e0e572868eaa276b3620e588",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7994,
"upload_time": "2018-09-15T00:17:25",
"upload_time_iso_8601": "2018-09-15T00:17:25.675885Z",
"url": "https://files.pythonhosted.org/packages/28/d8/cf52f9f50e0e425a750f704817cf330c857d3c6bfb96212dc693fa66c9f4/uplink-protobuf-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2018-09-15 00:17:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "prkumar",
"github_project": "uplink-protobuf",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "uplink-protobuf"
}
JSON
