Uplink 📡¶
A Declarative HTTP Client for Python. Inspired by Retrofit.
Note
Uplink is currently in initial development and, therefore, not
production ready at the moment. Furthermore, as the package follows a
semantic versioning
scheme, the public API outlined in this documentation should be
considered tentative until the v1.0.0 release.
However, while Uplink is under construction, we invite eager users to install early and provide open feedback, which can be as simple as opening a GitHub issue when you notice a missing feature, latent defect, documentation oversight, etc.
Moreover, for those interested in contributing, checkout the Contribution Guide on GitHub (‘tis `Hacktoberfest`__, after all)!
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:
r = github.update_user(token, bio="Beam me up, Scotty!").execute()
Voila, update_user() builds the request seamlessly (using the
decorators and annotations from the method’s definition), and
execute() sends that synchronously over the network. Furthermore,
the returned response r is simply a requests.Response
(documentation):
print(r.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 ☺️.
The User Manual¶
Follow this guide to get up and running with Uplink.
