Uplink

0.10.0 verified Mon Apr 27 auth: no python

A declarative HTTP client for Python that uses decorators and type hints to define API endpoints. Version 0.10.0, released in 2024, modernises to Pydantic v2 and requires Python 3.10+. Development is active but low velocity.

pip install uplink

Common errors

error ImportError: cannot import name 'retry' from 'uplink' ↓

cause 'retry' is in the 'uplink.retry' submodule, not top-level.

fix

Use: from uplink.retry import retry

error TypeError: __init__() got an unexpected keyword argument 'model_config' ↓

cause Using pydantic v2 model syntax (e.g., 'model_config') with uplink <0.10.0 that expects pydantic v1.

fix

Upgrade to uplink>=0.10.0 or revert to pydantic v1 with 'class Config'.

error AttributeError: 'GitHub' object has no attribute 'session' ↓

cause The Consumer subclass was not instantiated correctly; the 'session' property is available only after calling the parent __init__.

fix

Ensure you instantiate the consumer correctly: github = GitHub()

Warnings

breaking Pydantic v2 migration: Uplink 0.10.0 requires pydantic>=2.0. Code using pydantic v1 models will break unless models are updated to v2 syntax (e.g., 'class Config' -> 'model_config'). ↓

fix Upgrade pydantic to v2 and update your models accordingly, or pin uplink<0.10.0 if you must keep pydantic v1.

breaking Python 3.10 minimum: Uplink 0.10.0 dropped support for Python <3.10. Running on older versions will fail with import errors or syntax errors. ↓

fix Upgrade to Python 3.10+ or use uplink==0.9.7 (last supporting Python 3.7+).

gotcha Async requires aiohttp: Uplink's async support works only with the 'aiohttp' client. Using 'requests' with async methods will raise a NotImplementedError. ↓

fix Install aiohttp (pip install uplink[aiohttp]) and configure the client with 'client=aiohttp.ClientSession()'.

deprecated The 'timeout' argument in decorators is deprecated as of 0.9.x; use 'timeout' parameter in Consumer constructor or per-request. ↓

fix Pass timeout via the Consumer's 'timeout' argument or the 'request_timeout' parameter in method calls.

Imports

Consumer
wrong
```
from uplink import Uplink
```
correct
```
from uplink import Consumer
```
Uplink does not export any 'Uplink' class; the base class is 'Consumer'.
get, post, put, patch, delete, returns, json, headers, response_handler
wrong
```
from uplink.decorators import get
```
correct
```
from uplink import get, post, put, patch, delete, returns, json, headers, response_handler
```
All decorators are available directly from the 'uplink' package, not from a submodule.
retry
wrong
```
from uplink import retry
```
correct
```
from uplink.retry import retry
```
The 'retry' decorator is in the 'upload.retry' submodule, not top-level.

Quickstart

Define a GitHub API client that fetches a user by username.

from uplink import Consumer, get, returns

class GitHub(Consumer):
    base_url = "https://api.github.com/"

    @returns.json
    @get("users/{user}")
    def get_user(self, user):
        pass

if __name__ == "__main__":
    github = GitHub()
    response = github.get_user("prkumar")
    print(response.json())