Uplink 📡¶
A Declarative HTTP Client for Python. Inspired by Retrofit.
Note
Uplink is currently in initial development. Until the official
release (v1.0.0), the public API should be considered provisional.
Although we don’t expect any considerable changes to the API at this point,
please avoid using the code in production, for now.
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!
Uplink turns your HTTP API into a Python class.
from uplink import Consumer, get, headers, Path, Query
class GitHub(Consumer):
@get("users/{user}/repos")
def list_repos(self, user: Path, sort_by: Query("sort")):
"""Get user's public repositories."""
Build an instance to interact with the webservice.
github = GitHub(base_url="https://api.github.com/")
Then, executing an HTTP request is as simply as invoking a method.
repos = github.list_repos("octocat", sort_by="created")
The returned object is a friendly requests.Response:
print(repos.json())
# Output: [{'id': 64778136, 'name': 'linguist', ...
For sending non-blocking requests, Uplink comes with support for
aiohttp and twisted (example).
Use decorators and function annotations to describe the HTTP request:
- URL parameter replacement and query parameter support
- Convert response bodies into Python objects (e.g., using
marshmallowor a custom converter) - JSON, URL-encoded, and multipart request body and file upload
- Inject functions as middleware to define custom response and error handling
The User Manual¶
Follow this guide to get up and running with Uplink.
The Public API¶
This guide details the classes and methods in Uplink’s public API.
