FastAPI

FastAPI

https://fastapi.tiangolo.com/#performance

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.

The key features are:

• Fast: Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic). One of the fastest Python frameworks available.

• Fast to code: Increase the speed to develop features by about 200% to 300%. *

• Fewer bugs: Reduce about 40% of human (developer) induced errors. *
• Intuitive: Great editor support. Completion everywhere. Less time debugging.
• Easy: Designed to be easy to use and learn. Less time reading docs.
• Short: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
• Robust: Get production-ready code. With automatic interactive documentation.
• Standards-based: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema.

Typer, the FastAPI of CLIs

https://github.com/tiangolo/fastapi

https://typer.tiangolo.com/

Typer is a library for building CLI applications that users will love using and developers will love creating. Based on Python 3.6+ type hints.

The key features are:

• Intuitive to write: Great editor support. Completion everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.
• Easy to use: It's easy to use for the final users. Automatic help, and automatic completion for all shells.
• Short: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
• Start simple: The simplest example adds only 2 lines of code to your app: 1 import, 1 function call.
• Grow large: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups of subcommands, with options and arguments.

Click -- Typer depends

Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It’s the “Command Line Interface Creation Kit”. It’s highly configurable but comes with sensible defaults out of the box.

It aims to make the process of writing command line tools quick and fun while also preventing any frustration caused by the inability to implement an intended CLI API.

Click in three points:

• arbitrary nesting of commands

• automatic help page generation

• supports lazy loading of subcommands at runtime

What does it look like? Here is an example of a simple Click program:

import click

@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name',
              help='The person to greet.')
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

if __name__ == '__main__':
    hello()

And what it looks like when run:

$ python hello.py --count=3
Your name: John
Hello John!
Hello John!
Hello John!

Uvicorn

https://github.com/tiangolo/fastapi

You will also need an ASGI server, for production such as Uvicorn or Hypercorn.

$ pip install uvicorn[standard]

---> 100%

https://www.uvicorn.org/

异步网关，同时支持websocket

Uvicorn is a lightning-fast ASGI server implementation, using uvloop and httptools.

Until recently Python has lacked a minimal low-level server/application interface for asyncio frameworks. The ASGI specification fills this gap, and means we're now able to start building a common set of tooling usable across all asyncio frameworks.

ASGI should help enable an ecosystem of Python web frameworks that are highly competitive against Node and Go in terms of achieving high throughput in IO-bound contexts. It also provides support for HTTP/2 and WebSockets, which cannot be handled by WSGI.

Uvicorn currently supports HTTP/1.1 and WebSockets. Support for HTTP/2 is planned.

ASGI

https://asgi.readthedocs.io/en/latest/

异步网关，兼容同步的 WSGI

同时支持websocket

ASGI (Asynchronous Server Gateway Interface) is a spiritual successor to WSGI, intended to provide a standard interface between async-capable Python web servers, frameworks, and applications.

Where WSGI provided a standard for synchronous Python apps, ASGI provides one for both asynchronous and synchronous apps, with a WSGI backwards-compatibility implementation and multiple servers and application frameworks.

You can read more in the introduction to ASGI, look through the specifications, and see what implementations there already are or that are upcoming.

Code

https://github.com/tiangolo/fastapi#create-it

from typing import Optional

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

添加 reload 便于调试， 修改脚本后， 程序自动加载最新代码

Run it

Run the server with:

$ uvicorn main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [28720]
INFO:     Started server process [28722]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Interactive API docs

提供类似 swagger 界面， 可以在网页上试试调试接口。

Now go to http://127.0.0.1:8000/docs.

You will see the automatic interactive API documentation (provided by Swagger UI):

 

复合类型作请求body

https://github.com/tiangolo/fastapi#example-upgrade

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    is_offer: Optional[bool] = None


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}


@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_name": item.name, "item_id": item_id}

Optional of Typing

Optional是什么意思？

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

https://docs.python.org/3/library/typing.html

Union[X, None] 可以是 X类型， 也可以是None类型。

typing.Optional

Optional type.

Optional[X] is equivalent to Union[X, None].

Note that this is not the same concept as an optional argument, which is one that has a default. An optional argument with a default does not require the Optional qualifier on its type annotation just because it is optional. For example:

def foo(arg: int = 0) -> None:
    ...

On the other hand, if an explicit value of None is allowed, the use of Optional is appropriate, whether the argument is optional or not. For example:

def foo(arg: Optional[int] = None) -> None:
    ...

Union 是两个类型都可以。

typing.Union

Union type; Union[X, Y] means either X or Y.

To define a union, use e.g. Union[int, str]. Details:

• The arguments must be types and there must be at least one.

• Unions of unions are flattened, e.g.:

  Union[Union[int, str], float] == Union[int, str, float]
  

• Unions of a single argument vanish, e.g.:

  Union[int] == int  # The constructor actually returns int
  

• Redundant arguments are skipped, e.g.:

  Union[int, str, int] == Union[int, str]
  

• When comparing unions, the argument order is ignored, e.g.:

  Union[int, str] == Union[str, int]
  

• You cannot subclass or instantiate a union.

• You cannot write Union[X][Y].

• You can use Optional[X] as a shorthand for Union[X, None].

https://docs.python.org/3/library/typing.html#module-typing

This module provides runtime support for type hints as specified by PEP 484, PEP 526, PEP 544, PEP 586, PEP 589, and PEP 591. The most fundamental support consists of the types Any, Union, Tuple, Callable, TypeVar, and Generic. For full specification please see PEP 484. For a simplified introduction to type hints see PEP 483.

The function below takes and returns a string and is annotated as follows:

def greeting(name: str) -> str:
    return 'Hello ' + name

In the function greeting, the argument name is expected to be of type str and the return type str. Subtypes are accepted as arguments.

https://fastapi.tiangolo.com/python-types/

接口基于Python的 type hints 功能。

Python has support for optional "type hints".

These "type hints" are a special syntax that allow declaring the type of a variable.

By declaring types for your variables, editors and tools can give you better support.

This is just a quick tutorial / refresher about Python type hints. It covers only the minimum necessary to use them with FastAPI... which is actually very little.

FastAPI is all based on these type hints, they give it many advantages and benefits.

But even if you never use FastAPI, you would benefit from learning a bit about them.