Falibrary

Falcon的API规范和验证的附加库。

为Flask服务提供OpenAPI文档和验证。

主要为机器学习模型服务构建。

如果你正在使用Flask，请检查我的另一个Python库 Flaskerk。

注意

我创建了一个名为 SpecTree 的新库。它支持Falibrary的所有功能，但拥有更好的界面。试试看！这个库可能会在未来被存档。

功能

• 使用 Redoc UI 或 Swagger UI 生成API文档：yum
• 更少的样板代码，注释使用起来非常简单：sparkles
• 使用 pydantic 验证查询、JSON数据和响应数据：wink
• 更好的API服务HTTP异常（默认和自定义）（JSON而不是HTML）：grimacing

快速入门

使用 pip install falibrary 安装（Python 3.6+）

基本示例

import falcon
from wsgiref import simple_server
from pydantic import BaseModel

from falibrary import Falibrary

api = Falibrary(
    title='Demo Service',
    version='0.1.2',
)

class Query(BaseModel):
    text: str

class Demo():
    @api.validate(query=Query)
    def on_post(self, req, resp):
        print(req.context.query)
        pass

if __name__ == '__main__':
    app = falcon.API()
    app.add_route('/api/demo', Demo())
    api.register(app)

    httpd = simple_server.make_server('localhost', 8000, app)
    httpd.serve_forever()

需要做的更改

• 使用 pydantic 创建模型
• 使用 Falibrary.validate() 装饰路由函数
• 在 validate 中指定需要的部分
  • query（URL中的参数）
    • 内置转换器（int，uuid，dt）
  • data（请求中的JSON数据）
  • resp（响应）这将在验证后转换为JSON数据
  • x（HTTP异常列表）
  • tags（此路由的标签）
• 注册到Falcon应用程序

之后，此库将帮助您验证传入的请求，并在 /apidoc 中提供API文档。

更多详情，请参阅 文档。

更多功能

import falcon
from wsgiref import simple_server
from pydantic import BaseModel, Field
from random import random

from falibrary import Falibrary


api = Falibrary(
    title='Demo Service',
    version='0.1.2',
)


class Query(BaseModel):
    text: str = Field(
        ...,
        max_length=100,
    )


class Response(BaseModel):
    label: int = Field(
        ...,
        ge=0,
        le=9,
    )
    score: float = Field(
        ...,
        gt=0,
        lt=1,
    )


class Data(BaseModel):
    uid: str
    limit: int
    vip: bool


class Classification():
    """
    classification demo
    """
    @api.validate(tags=['demo'])
    def on_get(self, req, resp, source, target):
        """
        API summary

        description here: test information with `source` and `target`
        """
        resp.media = {'msg': f'hello from {source} to {target}'}

    @api.validate(query=Query, data=Data, resp=Response, x=[falcon.HTTP_403])
    def on_post(self, req, resp, source, target):
        """
        post demo

        demo for `query`, `data`, `resp`, `x`
        """
        print(f'{source} => {target}')
        print(req.context.query)
        print(req.context.data)
        if random() < 0.5:
            raise falcon.HTTPForbidden("Bad luck. You're fobidden.")
        return Response(label=int(10 * random()), score=random())


if __name__ == '__main__':
    app = falcon.API()
    app.add_route('/api/{source}/{target}', Classification())
    api.register(app)

    httpd = simple_server.make_server('localhost', 8000, app)
    httpd.serve_forever()

尝试使用 http POST ':8000/api/zh/en?text=hello' uid=0b01001001 limit=5 vip=true。

在 http://127.0.0.1:8000/apidoc 中打开文档。

更多示例，请查看 示例。