Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/prkumar/uplink-protobuf
Send and receive protobuf messages over HTTP, with ease.
https://github.com/prkumar/uplink-protobuf
aiohttp api-client protobuf-message protocol-buffers python python27 python3 requests uplink
Last synced: about 1 month ago
JSON representation
Send and receive protobuf messages over HTTP, with ease.
- Host: GitHub
- URL: https://github.com/prkumar/uplink-protobuf
- Owner: prkumar
- License: mit
- Created: 2018-06-21T03:29:51.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T04:52:22.000Z (about 2 years ago)
- Last Synced: 2024-11-26T03:12:08.848Z (about 1 month ago)
- Topics: aiohttp, api-client, protobuf-message, protocol-buffers, python, python27, python3, requests, uplink
- Language: Python
- Homepage:
- Size: 90.8 KB
- Stars: 13
- Watchers: 2
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
README
# Uplink + Protocol Buffers
[](https://travis-ci.com/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: "[email protected]"
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 = "[email protected]"
# 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.