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!
A Quick Walkthrough, with GitHub API v3:¶
Turn a Python class into a self-describing consumer of your favorite HTTP webservice, using method decorators and function annotations:
from uplink import *
# To define common request metadata, you can decorate the class
# rather than each method separately.
@headers({"Accept": "application/vnd.github.v3.full+json"})
class GitHub(Consumer):
@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."""
Let’s build an instance of this GitHub API consumer for the main site!
(Notice that I can use this same consumer class to also access any
GitHub Enterprise instance by simply changing the base_url.):
github = GitHub(base_url="https://api.github.com/")
To access the GitHub API with this instance, we can invoke any of the
methods that we defined in our class definition above. To illustrate,
let’s update my GitHub profile bio with update_user():
response = github.update_user(token, bio="Beam me up, Scotty!")
Voila, the method seamlessly builds the request (using the decorators
and annotations from the method’s definition) and executes it in the same call.
And, by default, Uplink uses the powerful Requests library. So, the returned
response is simply 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 ☺️ .
The User Manual¶
Follow this guide to get up and running with Uplink.
