Skip to main content

apiwrappers is a library for building API clients that work both with regular and async code

Project description

Build Status Documentation Status Coverage Status Checked with mypy PyPI Package latest release Supported versions MIT License

apiwrappers is a library for building API clients that work both with regular and async code.


  • DRY - support both regular and async code with one implementation

  • Flexible - middleware mechanism to customize request/response

  • Typed - library is fully typed and it’s relatively easy to get fully typed wrappers

  • Modern - decode JSON with no effort using dataclasses and type annotations

  • Unified interface - work with different python HTTP client libraries in the same way. Currently supported:


pip install 'apiwrappers[aiohttp,requests]'

Note: extras are mainly needed for the final user of your API client


Making request is rather straightforward:

from dataclasses import dataclass
from typing import List

from apiwrappers import Request, fetch, make_driver

class Repo:
    name: str

url = ""
request = Request("GET", url)

driver = make_driver("requests")
fetch(driver, request)  # Response(..., status_code=200, ...)
fetch(driver, request, model=List[Repo])  # [Repo(name='am-date-picker'), ...]

driver = make_driver("aiohttp")
await fetch(driver, request)  # Response(..., status_code=200, ...)
await fetch(driver, request, model=List[Repo])  # [Repo(name='am-date-picker'), ...]

Writing a Simple API Client

With apiwrappers you can bootstrap clients for different API pretty fast and easily.

Here is how a typical API client would look like:

from __future__ import annotations

from dataclasses import dataclass
from typing import Awaitable, Generic, List, TypeVar, overload

from apiwrappers import AsyncDriver, Driver, Request, Url, fetch

T = TypeVar("T", Driver, AsyncDriver)

class Repo:
    id: int
    name: str

class GitHub(Generic[T]):
    def __init__(self, host: str, driver: T):
        self.url = Url(host)
        self.driver: T = driver

    def get_repos(self: Github[Driver], username: str) -> List[Repo]:

    def get_repos(self: Github[AsyncDriver], username: str) -> Awaitable[List[Repo]]:

    def get_repos(self, username: str):
        url = self.url("/users/{username}/repos", username=username)
        request = Request("GET", url)
        return fetch(self.driver, request, model=List[Repo])

This is small, but fully typed, API client for one of the endpoints to get all user repos by username:

Here we defined Repo dataclass that describes what we want to get from response and pass it to the fetch function. fetch will then make a request and will cast response to that type.

Note how we create URL:

url = self.url("/users/{username}/repos", username=username)

Sometimes, it’s useful to have an URL template, for example, for logging or for aggregating metrics, so instead of formatting immediately, we provide a template and replacement fields.

Using the API Client

Here how we can use it:

>>> from apiwrappers import make_driver
>>> driver = make_driver("requests")
>>> github = GitHub("", driver=driver)
>>> github.get_repos("unmade")
[Repo(id=47463599, name='am-date-picker'),
 Repo(id=231653904, name='apiwrappers'),
 Repo(id=144204778, name='conway'),

To use it with asyncio all we need to do is provide a proper driver and don’t forget to await method call:

Use IPython or Python 3.8+ with python -m asyncio to try this code interactively

>>> from apiwrappers import make_driver
>>> driver = make_driver("aiohttp")
>>> github = GitHub("", driver=driver)
>>> await github.get_repos("unmade")
[Repo(id=47463599, name='am-date-picker'),
 Repo(id=231653904, name='apiwrappers'),
 Repo(id=144204778, name='conway'),


Documentation for apiwrappers can be found at Read The Docs.

Check out Extended Client Example.


Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

See contributing guide to learn more.

Currently the code and the issues are hosted on GitHub.

The project is licensed under MIT.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

apiwrappers-0.5.0.tar.gz (17.6 kB view hashes)

Uploaded Source

Built Distribution

apiwrappers-0.5.0-py3-none-any.whl (21.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page