ApiQlient 0.0.3

Quickly create REST clients

ApiQlient

About

Want to develop an easy-to-use API client library for your HTTP server? Maybe you're already using FastAPI and want to share dataclass libraries between your server and client projects with little to no maintenance involved?

API Quick Client (or ApiQlient) is for you then. Attach custom serializable classes to your endpoints and allow your users to choose whether they want to use sync or async scheme. You don't need to set up anything else by yourself.

See the documentation for more information.

Requirements

ApiQlient utilizes starlette as it's base - similarly to FastAPI. Additionally, it requires yarl package for URL parsing and urllib3 for its' synchronous and aiohttp for asynchronous backends.

On top of that it provides several optional functionalities. You can use it with dataclass_wizard-defined classes or with pydantic model. If you don't want to define custom classes, you can fall back to using munch instead.

Installation

Pull straight from this repo to install manually or just use pip: pip install apiqlient will do the trick.

Usage

ApiQlient supports both: synchronous and asynchronous execution. The manner of which to use is decided by detecting which context manager we enter (with or async with). If we use with - urllib3 will be used. If async with - aiohttp.

Below you can see and example using dataclass_wizard package.

import asyncio
from dataclasses import dataclass

from apiqlient import ApiQlient
from dataclass_wizard import JSONSerializable, json_field

client = ApiQlient(base_url="https://jsonplaceholder.typicode.com/")


@client.router.get("/{id}")
@dataclass
class JSONPlaceholderDCW(JSONSerializable):
    id: int
    title: str
    completed: bool
    user_id: int = json_field("userId")


async def async_main():
    async with client:
        requests = [client.get(f"/todos/{i + 1}") for i in range(100)]
        responses = await asyncio.gather(*[request.response() for request in requests])
        objects = await asyncio.gather(*[response.object() for response in responses])
    print(f"My fist async object: {objects[0]}")


def sync_main():
    with client:
        requests = [client.get(f"/todos/{i + 1}") for i in range(100)]
        responses = [request.response() for request in requests]
        objects = [response.object() for response in responses]
    print(f"My first sync object: {objects[0]}")


asyncio.run(async_main())

As this project is meant to replicate behaviour of FastAPI and uses starlette as it's core functionality, it also supports router-based structure. Meaning that you can spread your dataclasses/models between different modules, and attach them to routers which will later be included into the app. See example.py for reference.

Performance

Performance will differ depending on the environment. However, on my local machine, at the time of writing this, these were the results from the example.py file:

ASYNC
Finished parsing 100 requests in 8.913177967071533 seconds

SYNC
Finished parsing 100 requests in 19.49611806869507 seconds

No obvious difference was spotted between using dataclass_wizard, pydantic or munch.

Development

Installation

Install virtual environment and apiqlient package in editable mode with dev dependencies.

python -m venv venv
source venv/bin/activate
pip install -e .[dev]

How to?

Automate as much as we can, see configuration in pyproject.toml file to see what are the flags used.

staging format  # Reformat the code
staging lint    # Check for linting issues
staging test    # Run unit tests and coverage report