- 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 get_repos(self, user: Path, sort_by: Query("sort")):
"""Retrieves the 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.get_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
.
- Quickly Define Structured API Clients
- Use decorators and function annotations to describe the HTTP request.
- URL parameter replacement, request headers, and query parameter support.
- JSON, URL-encoded, and multipart request body and file upload.
- Bring Your Own HTTP Library
- Use Requests by default.
- Send non-blocking HTTP requests with Aiohttp or Twisted.
- Supply your own
requests.Session
oraiohttp.ClientSession
object for greater control.
- Directly Convert Response Bodies into Python Objects
- Built-in support for
marshmallow
schemas. - Define custom converters for your own objects.
- Built-in support for converting collections (e.g., list of Users).
- Built-in support for
- Extendable
- Inject custom response and error handling as middleware.
- Install optional plugins for additional features (e.g., protobuf support)
- Authentication
- Built-in support for Basic Authentication.
- Works with external auth support for Requests or Aiohttp.
Uplink officially supports Python 2.7 & 3.3-3.7.
To install the latest stable release, you can use pip
(or pipenv
):
$ 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 select 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]
Michael Kennedy (@mkennedy), host of Talk Python and Python Bytes podcasts-
Of course our first reaction when consuming HTTP resources in Python is to reach for Requests. But for structured APIs, we often want more than ad-hoc calls to Requests. We want a client-side API for our apps. Uplink is the quickest and simplest way to build just that client-side API. Highly recommended.
Or Carmi (@liiight), notifiers maintainer-
Uplink’s intelligent usage of decorators and typing leverages the most pythonic features in an elegant and dynamic way. If you need to create an API abstraction layer, there is really no reason to look elsewhere.
Ready to create an API client with Uplink? Get started with this quickstart guide! 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 💜