diff --git a/README.md b/README.md index 6102bb21e..2be4bf731 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ **Documentation**: [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com) +**Source Code**: [https://github.com/tiangolo/fastapi](https://github.com/tiangolo/fastapi) + --- FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+. @@ -27,12 +29,17 @@ FastAPI is a modern, fast (high-performance), web framework for building APIs wi The key features are: * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). + +* **Fast to code**: Increase the speed to develop features by about 200% to 300% *. +* **Less 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. +* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Less bugs. * **Robust**: Get production-ready code. With automatic interactive documentation. * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI and JSON Schema. +* estimation based on tests on an internal development team, building production applications. + ## Requirements @@ -65,22 +72,39 @@ from fastapi import FastAPI app = FastAPI() +@app.get('/') +def read_root(): + return {'hello': 'world'} +``` + +Or if your code uses `async` / `await`, use `async def`: + +```Python hl_lines="6" +from fastapi import FastAPI + +app = FastAPI() + @app.get('/') async def read_root(): return {'hello': 'world'} ``` +!!! note + If you don't know, check the section about [`async` and `await` in the docs](async.md). + + * Run the server with: ```bash uvicorn main:app --debug ``` -**Note**: the command `uvicorn main:app` refers to: +!!! note + The command `uvicorn main:app` refers to: -* `main`: the file `main.py` (the Python "module"). -* `app`: the object created inside of `main.py` with the line `app = FastAPI()`. -* `--debug`: make the server restart after code changes. Only use for development. + * `main`: the file `main.py` (the Python "module"). + * `app`: the object created inside of `main.py` with the line `app = FastAPI()`. + * `--debug`: make the server restart after code changes. Only do this for development. ### Check it @@ -118,7 +142,7 @@ Now modify the file `main.py` to include: * an optional query parameter `q`. -```Python +```Python hl_lines="2 7 8 9 10 19" from fastapi import FastAPI from pydantic import BaseModel @@ -171,7 +195,13 @@ And now, go to http://127. ### Recap -In summary, you declare **once** the types of parameters, body, etc. as function parameters. You don't have to learn a new syntax, use a specific library, class or object to declare fields, you just type standard Python types. +In summary, you declare **once** the types of parameters, body, etc. as function parameters. + +You do that with standard modern Python types. + +You don't have to learn a new syntax, the methods or classes of a specific library, etc. + +Just standard **Python 3.6+**. For example, for an `int`: @@ -193,15 +223,15 @@ item: Item * Validation of data: * Automatic and clear errors when the data is invalid. * Validation even for deeply nested JSON objects. -* Serialization of input data: from the network to Python, reading from: +* Conversion of input data: coming from the network, to Python data and types. Reading from: * JSON. - * Forms. - * Files. * Path parameters. * Query parameters. * Cookies. * Headers. -* Serialization of output data: from Python to network (as JSON): + * Forms. + * Files. +* Conversion of output data: converting from Python data and types to network data (as JSON): * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). * `datetime` objects. * `UUID` objects. @@ -216,16 +246,21 @@ item: Item Coming back to the previous code example, **FastAPI** will: * Validate that there is an `item_id` in the path. -* Validate that the `item_id` is of type `int`. If it is not, the client will see a useful error. -* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`). As the `q` parameter is declared with `= None`, it is optional. Without the `None` it would be required (as is the body). +* Validate that the `item_id` is of type `int`. + * If it is not, the client will see a useful, clear error. +* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`). + * As the `q` parameter is declared with `= None`, it is optional. + * Without the `None` it would be required (as is the body). * Read the body as JSON: * Check that it has a required attribute `name` that should be a `str`. * Check that is has a required attribute `price` that has to be a `float`. * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present. - * All this would also work for deeply nested JSON objects + * All this would also work for deeply nested JSON objects. * Convert from and to JSON automatically. -* Document everything as OpenAPI, so the interactive documentation is created and updated automatically. -* Provide the interactive documentation web interfaces. +* Document everything as an OpenAPI schema, that can be used by: + * Interactive documentation sytems. + * Automatic client code generation systems, for many languages. +* Provide 2 interactive documentation web interfaces directly. --- @@ -255,16 +290,22 @@ Try changing the line with: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -For a more complete example including more features, [see the tutorial](tutorial). +For a more complete example including more features, [see the tutorial - user guide](tutorial/intro/). -**Spoiler alert**: the tutorial, although very short, includes: +**Spoiler alert**: the tutorial - user guide includes: -* Declaration of **parameters** from different places as: headers, cookies, form data and files. +* Declaration of **parameters** from other different places as: **headers**, **cookies**, **form fields** and **files**. * How to set **validation constrains** as `maximum_length` or `regex`. -* A very powerful and easy to use **Dependency Injection** system (also known as "components", "resources", "providers", "services"). +* A very powerful and easy to use **Dependency Injection** system. * Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth. -* More advanced (but equally easy) techniques for declaring **deeply nested models** (JSON body, Form and Files) (thanks to Pydantic). -* Many extra features (thanks to Starlette) as **WebSockets**, **GraphQL**, extremely easy tests based on `requests` and `pytest`, CORS, Cookie Sessions and more. +* More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic). +* Many extra features (thanks to Starlette) as: + * **WebSockets** + * **GraphQL** + * extremely easy tests based on `requests` and `pytest` + * **CORS** + * **Cookie Sessions** + * ...and more. @@ -272,7 +313,7 @@ For a more complete example including more features, [see the tutorial](tutorial Used by Pydantic: -* ujson - for faster JSON parsing. +* ujson - for faster JSON "parsing". * email_validator - for email validation. @@ -281,12 +322,15 @@ Used by Starlette: * requests - Required if you want to use the `TestClient`. * aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. -* python-multipart - Required if you want to support form parsing, with `request.form()`. +* python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. * pyyaml - Required for `SchemaGenerator` support. * graphene - Required for `GraphQLApp` support. * ujson - Required if you want to use `UJSONResponse`. +Used by FastAPI / Starlette: + +* uvicorn - for the server that loads and serves your application. You can install all of these with `pip3 install fastapi[full]`. diff --git a/docs/features.md b/docs/features.md index 710dffeb0..fde01a2cd 100644 --- a/docs/features.md +++ b/docs/features.md @@ -123,7 +123,7 @@ Security and authentication integrated. Without any compromise with databases or All the security schemes defined in OpenAPI, including: * HTTP Basic. -* **OAuth2** (also with **JWT tokens**). Check the [tutorial on OAuth2 with JWT](tutorial/oauth2-jwt.md). +* **OAuth2** (also with **JWT tokens**). Check the [tutorial on OAuth2 with JWT](tutorial/security/oauth2-jwt.md). * API keys in: * Headers. * Query parameters. diff --git a/docs/index.md b/docs/index.md index b36541dc5..2be4bf731 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ **Documentation**: [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com) -**Source**: [https://github.com/tiangolo/fastapi](https://github.com/tiangolo/fastapi) +**Source Code**: [https://github.com/tiangolo/fastapi](https://github.com/tiangolo/fastapi) --- diff --git a/docs/tutorial/oauth2-jwt.md b/docs/tutorial/oauth2-jwt.md deleted file mode 100644 index 39fe646c4..000000000 --- a/docs/tutorial/oauth2-jwt.md +++ /dev/null @@ -1 +0,0 @@ -Sorry! Coming soon... come back in a couple days. \ No newline at end of file diff --git a/docs/tutorial/python-types.md b/docs/tutorial/python-types.md index 39fe646c4..684e27f7d 100644 --- a/docs/tutorial/python-types.md +++ b/docs/tutorial/python-types.md @@ -1 +1 @@ -Sorry! Coming soon... come back in a couple days. \ No newline at end of file +Coming soon... diff --git a/fastapi/__init__.py b/fastapi/__init__.py index d300668bb..1088995d3 100644 --- a/fastapi/__init__.py +++ b/fastapi/__init__.py @@ -1,6 +1,6 @@ """FastAPI framework, high performance, easy to learn, fast to code, ready for production""" -__version__ = "0.1.10" +__version__ = "0.1.11" from .applications import FastAPI from .routing import APIRouter diff --git a/mkdocs.yml b/mkdocs.yml index 645e052e7..45866680e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,6 +18,7 @@ nav: - Features: 'features.md' - Tutorial - User Guide: - Tutorial - User Guide - Intro: 'tutorial/intro.md' + - Python types intro: 'tutorial/python-types.md' - First Steps: 'tutorial/first-steps.md' - Path Parameters: 'tutorial/path-params.md' - Query Parameters: 'tutorial/query-params.md' diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 4c08b127e..895356568 100644 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -1,3 +1,5 @@ #!/usr/bin/env bash mkdocs build + +cp ./docs/index.md ./README.md