- Builds Reusable Objects for Consuming Web APIs.
- Works with Requests, asyncio, and Twisted.
- Inspired by Retrofit.
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
.
Use decorators and function annotations to describe the HTTP request:
- URL parameter replacement and query parameter support
- Convert responses into Python objects (e.g., using
marshmallow
) - JSON, URL-encoded, and multipart request body and file upload
- Inject functions as middleware to apply custom response and error handling
uplink
supports Python 2.7 & 3.3-3.7.
To install the latest stable release, you can use pip
:
$ pip install -U uplink
If you are interested in the cutting-edge, preview the upcoming release with:
$ pip install https://github.com/prkumar/uplink/archive/master.zip
Further, uplink has optional integrations and features. You can view a full list of available extras here.
When installing Uplink with pip
, you can specify any of number of extras
using the format:
$ pip install -U uplink[extra1, extra2, ..., extraN]
For instance, to install aiohttp
and marshmallow
support:
$ pip install -U uplink[aiohttp, marshmallow]
For more details, check out the documentation at https://uplink.readthedocs.io/.
Want to report a bug, request a feature, or contribute code to Uplink? Checkout the Contribution Guide for where to start. Thank you for taking the time to improve an open source project 💜