Skip to content

dutradda/apidaora

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

apidaora

apidaora

OpenAPI / HTTP / REST API using dataclasses and TypedDict annotation for python


Documentation: https://dutradda.github.io/apidaora

Source Code: https://github.com/dutradda/apidaora


Key Features

  • Declaration of request/response as dataclasses and dicts using typing annotations
  • Input data validation with jsondaora
  • One of the fastest python api framework
  • Can run on any asgi server

Requirements

  • Python 3.8+
  • jsondaora for json validation/parsing
  • orjson for json/bytes serialization (jsondaora dependency)

Instalation

$ pip install apidaora

Simple example

from apidaora import appdaora, route


@route.get('/hello')
def hello_controller(name: str) -> str:
    return f'Hello {name}!'


app = appdaora(hello_controller)

Running the server (needs uvicorn installed):

uvicorn myapp:app
INFO: Started server process [16220]
INFO: Waiting for application startup.
INFO: ASGI 'lifespan' protocol appears unsupported.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Quering the server (needs curl installed):

curl -i localhost:8000/hello?name=World
HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 14

"Hello World!"

Basic example

from typing import TypedDict

from jsondaora import IntegerField, StringField, jsondaora

from apidaora import Header, appdaora, route


class Integer(IntegerField, minimum=18):
    ...


class String(StringField, max_length=100):
    ...


class Age(Header, type=Integer):
    ...


@jsondaora
class You(TypedDict):
    name: str
    last_name: str
    location: str
    age: int


@jsondaora
class ReqBody(TypedDict):
    last_name: str


@jsondaora
class HelloOutput(TypedDict):
    hello_message: str
    about_you: You


@route.put('/hello/{name}')
async def hello_controller(
    name: str, location: String, age: Age, body: ReqBody
) -> HelloOutput:
    you = You(
        name=name,
        location=location.value,
        age=age.value.value,
        last_name=body['last_name'],
    )
    return HelloOutput(
        hello_message=await hello_message(name, location.value), about_you=you
    )


async def hello_message(name: str, location: str) -> str:
    return f'Hello {name}! Welcome to {location}!'


app = appdaora(hello_controller)

Running the server:

uvicorn myapp:app
INFO: Started server process [16220]
INFO: Waiting for application startup.
INFO: ASGI 'lifespan' protocol appears unsupported.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Quering the server:

curl -i -X PUT localhost:8000/hello/Me?location=World \
    -H 'x-age: 32' \
    -d '{"last_name":"My Self"}'
HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 123

{"hello_message":"Hello Me! Welcome to World!","about_you":{"name":"Me","location":"World","age":32,"last_name":"My Self"}}

Example for more request/response details

from http import HTTPStatus
from typing import Dict

from jsondaora import jsondaora

from apidaora import BadRequestError, Header, Response, appdaora, json, route


# Domain layer, here are the domain related definitions
# it is apidaora/framework/http independent


@jsondaora
class You:
    name: str
    last_name: str
    age: int


DB: Dict[str, You] = {}


def add_you(you: You) -> None:
    if you.name in DB:
        raise YouAlreadyBeenAddedError(you.name)
    DB[you.name] = you


def get_you(name: str) -> You:
    try:
        return DB[name]
    except KeyError:
        raise YouWereNotFoundError(name)


class DBError(Exception):
    @property
    def info(self) -> Dict[str, str]:
        return {'name': self.args[0]}


class YouAlreadyBeenAddedError(DBError):
    name = 'you-already-been-added'


class YouWereNotFoundError(DBError):
    name = 'you-were-not-found'


# Application layer, here are the http related definitions

# See: https://dutrdda.github.io/apidaora/tutorial/headers/
class ReqID(Header, type=str, http_name='http_req_id'):
    ...


@route.post('/you/')
async def add_you_controller(req_id: ReqID, body: You) -> Response:
    try:
        add_you(body)
    except YouAlreadyBeenAddedError as error:
        raise BadRequestError(name=error.name, info=error.info) from error

    return json(body, HTTPStatus.CREATED, headers=(req_id,))


@route.get('/you/{name}')
async def get_you_controller(name: str, req_id: ReqID) -> Response:
    try:
        return json(get_you(name), headers=(req_id,))
    except YouWereNotFoundError as error:
        raise BadRequestError(name=error.name, info=error.info) from error


app = appdaora([add_you_controller, get_you_controller])

Running the server:

uvicorn myapp:app
INFO: Started server process [16220]
INFO: Waiting for application startup.
INFO: ASGI 'lifespan' protocol appears unsupported.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Quering the server:

curl -X POST -i localhost:8000/you/ -H 'http_req_id: 1a2b3c4d' -d '{"name":"Me","last_name":"Myself","age":32}'
HTTP/1.1 201 Created
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 43
http_req_id: 1a2b3c4d

{"name":"Me","last_name":"Myself","age":32}

curl -i localhost:8000/you/Me -H 'http_req_id: 4d3c2b1a'
HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 43
http_req_id: 4d3c2b1a

{"name":"Me","last_name":"Myself","age":32}

Benchmark

techempower benchmark

The full results can be found here

About

HTTP/REST API using dataclasses and TypedDict annotation for python

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages