Sensei: Simplifying API Client Generation

[blnkoff]

Sensei simplifies the process of creating API Clients by handling routing, data validation, and response mapping automatically.
This reduces the complexity of HTTP requests, making it easier to integrate APIs into your projects without writing
boilerplate code.

Sensei uses type hints to generate API clients, providing clear interfaces and robust validation for interacting with APIs.
Its syntax is very similar to the framework FastAPI

• Documentation: https://sensei.crocofactory.dev
  
• Source Code: https://github.com/CrocoFactory/sensei
  

Code Example

from typing import Annotated
from sensei import Router, Path, APIModel

router = Router('https://pokeapi.co/api/v2/')


class Pokemon(APIModel):
    name: str
    id: int
    height: int
    weight: int


@router.get('/pokemon/{name}')
def get_pokemon(name: Annotated[str, Path(max_length=300)]) -> Pokemon: 
    pass

pokemon = get_pokemon(name="pikachu")
print(pokemon) # Pokemon(name='pikachu' id=25 height=4 weight=60)

Didn't it seem to you that the function doesn't contain the code? Sensei writes it instead of you! The result of the
call get_pokemon(name="pikachu") is the object Pokemon(name='pikachu' id=25 height=4 weight=60) containing pokémon's data.

There is a wonderful OOP approach proposed by Sensei:

class User(APIModel):
    email: EmailStr
    id: PositiveInt
    first_name: str
    last_name: str
    avatar: AnyHttpUrl

    @classmethod
    @router.get('/users')
    def query(
            cls,
            page: Annotated[int, Query()] = 1,
            per_page: Annotated[int, Query(le=7)] = 3
    ) -> list[Self]:
        pass

    @classmethod
    @router.get('/users/{id_}')
    def get(cls, id_: Annotated[int, Path(alias='id')]) -> Self: 
        pass

    @router.post('/token')
    def login(self) -> str: 
        pass

    @login.prepare
    def _login_in(self, args: Args) -> Args:
        args.json_['email'] = self.email
        return args

    @login.finalize
    def _login_out(self, response: Response) -> str:
        return response.json()['token']

user = User.get(1)
user.login() # User(id=1, email="[email protected]", first_name="John", ...)

When Sensei doesn't know how to handle a request, you can do it yourself, using preprocessing as prepare and
postprocessing as finalize

Comparison

Sensei: It provides a high level of abstraction. Sensei simplifies creating API wrappers, offering decorators for
easy routing, data validation, and automatic mapping of API responses to models. This reduces boilerplate and improves
code readability and maintainability.

Bare HTTP Client: A bare HTTP client like requests or httpx requires manually managing requests,
handling response parsing, data validation, and error handling. You have to write repetitive code for each endpoint.

Features

Sensei provides features that are useful for both standard and messy APIs:

1. Validation 🛡️
2. Rate Limiting Handling ⏳
3. Automatic Handling of Return Types 🔄
4. DRY Architecture Without Duplications 🧹
5. Async Support ⚡
6. Case Conversion and Aliases 🔠
7. Own Client for Fast Requests 🚀

Target Audience

Developers Working with APIs, Data Scientists and Analysts, etc.