Show HN: Uplink - Build declarative web API clients for Python
GitHub - prkumar/uplink: A Declarative HTTP Client for Python
Uplink

  
  
 
 


Builds Reusable Objects for Consuming Web APIs.
Works with Requests, aiohttp, and Twisted.
Inspired by Retrofit.


A Quick Walkthrough, with GitHub API v3
Uplink turns your HTTP API into a Python class.
from uplink import Consumer, get, Path, Query


class GitHub(Consumer):
    """A Python Client for the GitHub API."""

    @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(user="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.
Ready to launch your first API client with Uplink? Start with this quick tutorial!

Features

Quickly Define Structured API Clients
Use decorators and type hints to describe each HTTP request
JSON, URL-encoded, and multipart request body and file upload
URL parameter replacement, request headers, and query parameter support


Bring Your Own HTTP Library
Non-blocking I/O support for Aiohttp and Twisted
Supply your own session (e.g., requests.Session) for greater control


Easy and Transparent Deserialization/Serialization
Define custom converters for your own objects
Support for marshmallow schemas, pydantic models, and handling collections (e.g., list of Users)


Extendable
Install optional plugins for additional features (e.g., protobuf support)
Compose custom response and error handling functions as middleware


Authentication
Built-in support for Basic Authentication
Use existing auth libraries for supported clients (e.g., requests-oauthlib)



Uplink officially supports Python 2.7 and 3.5+.
Note: Python 2.7 suport will be removed in v0.10.0.

Installation
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


Extra! Extra!
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]


User Testimonials
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.

Documentation
Check out the library's documentation at https://uplink.readthedocs.io/.
For new users, a good place to start is this quick tutorial.

Community
Use the Discussions tab on GitHub to join the conversation! Ask questions, provide feedback,
and meet other users!
We're migrating our community from Gitter to GitHub Discussions. Feel free to search our
Gitter lobby for past questions and answers. However, to help us transition, please start new
threads/posts in GitHub Discussions instead of Gitter.

Contributing
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 💜

