README.rst

Overview

---

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

Features

• 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:

  • requests
  • aiohttp

Installation

pip install 'apiwrappers[aiohttp,requests]'

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

QuickStart

Making request is rather straightforward:

from dataclasses import dataclass
from typing import List

from apiwrappers import Request, fetch, make_driver

@dataclass
class Repo:
    name: str

url = "https://api.github.com/users/unmade/repos"
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)


@dataclass
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

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

    @overload
    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 api.github.com 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("https://api.github.com", 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("https://api.github.com", 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

Documentation for apiwrappers can be found at Read The Docs.

Check out Extended Client Example.

Contributing

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.