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.

Features

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

  • Customizable - middleware mechanism to customize request/response

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

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

Installation

pip install apiwrappers[requests,aiohttp]

Note: extras are optional and mainly needed for the final user of your future API wrapper

Getting Started

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

Writing a Simple API Client

Here is how a typical API client would look like:

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

from apiwrappers import AsyncDriver, Driver, Method, Request, 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.host = 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):
        path = f"/users/{username}/repos"
        request = Request(Method.GET, self.host, path)
        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.

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.

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.

Project details


Download files

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

Files for apiwrappers, version 0.1.0b1
Filename, size File type Python version Upload date Hashes
Filename, size apiwrappers-0.1.0b1-py3-none-any.whl (19.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size apiwrappers-0.1.0b1.tar.gz (15.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page