itstehkman/uplink

A Declarative HTTP Client for Python

Uplink

Python HTTP Made Expressive. Inspired by Retrofit.

A Quick Walkthrough, with GitHub API v3

Using decorators and function annotations, you can turn any plain old Python class into a self-describing consumer of your favorite HTTP webservice:

from uplink import *

# To register entities that are common to all API requests, you can
# decorate the enclosing class rather than each method separately:
@headers({"Accept": "application/vnd.github.v3.full+json"})
class GitHub(object):

    @get("/users/{username}")
    def get_user(self, username):
        """Get a single user."""

    @json
    @patch("/user")
    def update_user(self, access_token: Query, **info: Body):
        """Update an authenticated user."""

To construct a consumer instance, use the helper function uplink.build:

github = build(GitHub, base_url="https://api.github.com/")

To access the GitHub API with this instance, we simply invoke any of the methods that we defined in the interface above. To illustrate, let's update my GitHub profile bio:

response = github.update_user(oauth_token, bio="Beam me up, Scotty!").execute()

Voila, update_user(...) seamlessly builds the request (using the decorators and annotations from the method's definition), and execute() sends that synchronously over the network. Furthermore, the returned response is a requests.Response (documentation):

print(response.json()) # {u'disk_usage': 216141, u'private_gists': 0, ...

In essence, Uplink delivers reusable and self-sufficient objects for accessing HTTP webservices, with minimal code and user pain ☺️.

Installation

uplink supports Python 2.7 & 3.3-3.7. To install the package, you can use pip:

$ pip install uplink

Documentation

For more details, check out the documentation at http://uplink.readthedocs.io/.