mirror of
https://github.com/fastapi/fastapi.git
synced 2026-10-22 18:06:17 -04:00
📝 Update order of examples, latest Python version first, and simplify version tab names (#9269)
* 📝 Simplify names in Python versions in tabs in docs * 📝 Update docs for Types Intro, explain Python 3.6+, Python 3.9+, Python 3.10+ * 📝 Re-order all Python examples, show latest Python versions first
This commit is contained in:
Sebastián Ramírez authored and GitHub committed
1 parent
166d348ea6
commit
69673548bc
55 files changed
+2598
-2595
No files matched your search
@@ -6,18 +6,18 @@
|
||||
|
||||
在前面的例子中, 我们从依赖项 ("可依赖对象") 中返回了一个 `dict`:
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!> ../../../docs_src/dependencies/tutorial001.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及以上"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="7"
|
||||
{!> ../../../docs_src/dependencies/tutorial001_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!> ../../../docs_src/dependencies/tutorial001.py!}
|
||||
```
|
||||
|
||||
但是后面我们在路径操作函数的参数 `commons` 中得到了一个 `dict`。
|
||||
|
||||
我们知道编辑器不能为 `dict` 提供很多支持(比如补全)，因为编辑器不知道 `dict` 的键和值类型。
|
||||
@@ -79,46 +79,46 @@ fluffy = Cat(name="Mr Fluffy")
|
||||
|
||||
所以，我们可以将上面的依赖项 "可依赖对象" `common_parameters` 更改为类 `CommonQueryParams`:
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="11-15"
|
||||
{!> ../../../docs_src/dependencies/tutorial002.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及 以上"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="9-13"
|
||||
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
|
||||
```
|
||||
|
||||
注意用于创建类实例的 `__init__` 方法：
|
||||
=== "Python 3.6+"
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="12"
|
||||
```Python hl_lines="11-15"
|
||||
{!> ../../../docs_src/dependencies/tutorial002.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及 以上"
|
||||
注意用于创建类实例的 `__init__` 方法：
|
||||
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="10"
|
||||
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
|
||||
```
|
||||
|
||||
...它与我们以前的 `common_parameters` 具有相同的参数：
|
||||
=== "Python 3.6+"
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!> ../../../docs_src/dependencies/tutorial001.py!}
|
||||
```Python hl_lines="12"
|
||||
{!> ../../../docs_src/dependencies/tutorial002.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及 以上"
|
||||
...它与我们以前的 `common_parameters` 具有相同的参数：
|
||||
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="6"
|
||||
{!> ../../../docs_src/dependencies/tutorial001_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!> ../../../docs_src/dependencies/tutorial001.py!}
|
||||
```
|
||||
|
||||
这些参数就是 **FastAPI** 用来 "处理" 依赖项的。
|
||||
|
||||
在两个例子下，都有：
|
||||
@@ -133,18 +133,18 @@ fluffy = Cat(name="Mr Fluffy")
|
||||
|
||||
现在，您可以使用这个类来声明你的依赖项了。
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="19"
|
||||
{!> ../../../docs_src/dependencies/tutorial002.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及 以上"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="17"
|
||||
{!> ../../../docs_src/dependencies/tutorial002_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="19"
|
||||
{!> ../../../docs_src/dependencies/tutorial002.py!}
|
||||
```
|
||||
|
||||
**FastAPI** 调用 `CommonQueryParams` 类。这将创建该类的一个 "实例"，该实例将作为参数 `commons` 被传递给你的函数。
|
||||
|
||||
## 类型注解 vs `Depends`
|
||||
@@ -183,18 +183,18 @@ commons = Depends(CommonQueryParams)
|
||||
|
||||
..就像:
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="19"
|
||||
{!> ../../../docs_src/dependencies/tutorial003.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及 以上"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="17"
|
||||
{!> ../../../docs_src/dependencies/tutorial003_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="19"
|
||||
{!> ../../../docs_src/dependencies/tutorial003.py!}
|
||||
```
|
||||
|
||||
但是声明类型是被鼓励的，因为那样你的编辑器就会知道将传递什么作为参数 `commons` ，然后它可以帮助你完成代码，类型检查，等等：
|
||||
|
||||
<img src="/img/tutorial/dependencies/image02.png">
|
||||
@@ -227,18 +227,18 @@ commons: CommonQueryParams = Depends()
|
||||
|
||||
同样的例子看起来像这样：
|
||||
|
||||
=== "Python 3.6 以及 以上"
|
||||
|
||||
```Python hl_lines="19"
|
||||
{!> ../../../docs_src/dependencies/tutorial004.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 以及 以上"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="17"
|
||||
{!> ../../../docs_src/dependencies/tutorial004_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="19"
|
||||
{!> ../../../docs_src/dependencies/tutorial004.py!}
|
||||
```
|
||||
|
||||
... **FastAPI** 会知道怎么处理。
|
||||
|
||||
!!! tip
|
||||
|
||||
@@ -20,18 +20,18 @@
|
||||
|
||||
它接收一个对象，比如Pydantic模型，并会返回一个JSON兼容的版本：
|
||||
|
||||
=== "Python 3.6 and above"
|
||||
|
||||
```Python hl_lines="5 22"
|
||||
{!> ../../../docs_src/encoder/tutorial001.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 and above"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="4 21"
|
||||
{!> ../../../docs_src/encoder/tutorial001_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="5 22"
|
||||
{!> ../../../docs_src/encoder/tutorial001.py!}
|
||||
```
|
||||
|
||||
在这个例子中，它将Pydantic模型转换为`dict`，并将`datetime`转换为`str`。
|
||||
|
||||
调用它的结果后就可以使用Python标准编码中的<a href="https://docs.python.org/3/library/json.html#json.dumps" class="external-link" target="_blank">`json.dumps()`</a>。
|
||||
|
||||
@@ -124,18 +124,18 @@ contents = myfile.file.read()
|
||||
|
||||
您可以通过使用标准类型注解并将 None 作为默认值的方式将一个文件参数设为可选:
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="9 17"
|
||||
{!> ../../../docs_src/request_files/tutorial001_02.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="7 14"
|
||||
{!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="9 17"
|
||||
{!> ../../../docs_src/request_files/tutorial001_02.py!}
|
||||
```
|
||||
|
||||
## 带有额外元数据的 `UploadFile`
|
||||
|
||||
您也可以将 `File()` 与 `UploadFile` 一起使用，例如，设置额外的元数据:
|
||||
@@ -152,18 +152,18 @@ FastAPI 支持同时上传多个文件。
|
||||
|
||||
上传多个文件时，要声明含 `bytes` 或 `UploadFile` 的列表（`List`）：
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="10 15"
|
||||
{!> ../../../docs_src/request_files/tutorial002.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="8 13"
|
||||
{!> ../../../docs_src/request_files/tutorial002_py39.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="10 15"
|
||||
{!> ../../../docs_src/request_files/tutorial002.py!}
|
||||
```
|
||||
|
||||
接收的也是含 `bytes` 或 `UploadFile` 的列表（`list`）。
|
||||
|
||||
|
||||
@@ -177,18 +177,18 @@ FastAPI 支持同时上传多个文件。
|
||||
|
||||
和之前的方式一样, 您可以为 `File()` 设置额外参数, 即使是 `UploadFile`:
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="18"
|
||||
{!> ../../../docs_src/request_files/tutorial003.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="16"
|
||||
{!> ../../../docs_src/request_files/tutorial003_py39.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="18"
|
||||
{!> ../../../docs_src/request_files/tutorial003.py!}
|
||||
```
|
||||
|
||||
## 小结
|
||||
|
||||
本节介绍了如何用 `File` 把上传文件声明为（表单数据的）输入参数。
|
||||
@@ -246,22 +246,22 @@ connect_args={"check_same_thread": False}
|
||||
|
||||
但是为了安全起见，`password`不会出现在其他同类 Pydantic*模型*中，例如用户请求时不应该从 API 返回响应中包含它。
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="3 6-8 11-12 23-24 27-28"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```Python hl_lines="1 4-6 9-10 21-22 25-26"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="3 6-8 11-12 23-24 27-28"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 及以上版本"
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="1 4-6 9-10 21-22 25-26"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```Python hl_lines="3 6-8 11-12 23-24 27-28"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```
|
||||
|
||||
#### SQLAlchemy 风格和 Pydantic 风格
|
||||
@@ -290,22 +290,22 @@ name: str
|
||||
|
||||
不仅是这些项目的 ID，还有我们在 Pydantic*模型*中定义的用于读取项目的所有数据：`Item`.
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="15-17 31-34"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```Python hl_lines="13-15 29-32"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="15-17 31-34"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 及以上版本"
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="13-15 29-32"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```Python hl_lines="15-17 31-34"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```
|
||||
|
||||
!!! tip
|
||||
@@ -319,22 +319,22 @@ name: str
|
||||
|
||||
在`Config`类中，设置属性`orm_mode = True`。
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python hl_lines="15 19-20 31 36-37"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```Python hl_lines="13 17-18 29 34-35"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="15 19-20 31 36-37"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 及以上版本"
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="13 17-18 29 34-35"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```Python hl_lines="15 19-20 31 36-37"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```
|
||||
|
||||
!!! tip
|
||||
@@ -465,18 +465,18 @@ current_user.items
|
||||
|
||||
以非常简单的方式创建数据库表：
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="7"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
#### Alembic 注意
|
||||
|
||||
通常你可能会使用 <a href="https://alembic.sqlalchemy.org/en/latest/" class="external-link" target="_blank">Alembic</a>，来进行格式化数据库（创建表等）。
|
||||
@@ -499,18 +499,18 @@ current_user.items
|
||||
|
||||
我们的依赖项将创建一个新的 SQLAlchemy `SessionLocal`，它将在单个请求中使用，然后在请求完成后关闭它。
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="15-20"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="13-18"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="15-20"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
!!! info
|
||||
我们将`SessionLocal()`请求的创建和处理放在一个`try`块中。
|
||||
|
||||
@@ -524,18 +524,18 @@ current_user.items
|
||||
|
||||
*这将为我们在路径操作函数*中提供更好的编辑器支持，因为编辑器将知道`db`参数的类型`Session`：
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="24 32 38 47 53"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="22 30 36 45 51"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="24 32 38 47 53"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
!!! info "技术细节"
|
||||
参数`db`实际上是 type `SessionLocal`，但是这个类（用 创建`sessionmaker()`）是 SQLAlchemy 的“代理” `Session`，所以，编辑器并不真正知道提供了哪些方法。
|
||||
|
||||
@@ -545,18 +545,18 @@ current_user.items
|
||||
|
||||
现在，到了最后，编写标准的**FastAPI** *路径操作*代码。
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="23-28 31-34 37-42 45-49 52-55"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="21-26 29-32 35-40 43-47 50-53"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="23-28 31-34 37-42 45-49 52-55"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
我们在依赖项中的每个请求之前利用`yield`创建数据库会话，然后关闭它。
|
||||
|
||||
所以我们就可以在*路径操作函数*中创建需要的依赖，就能直接获取会话。
|
||||
@@ -638,22 +638,22 @@ def read_user(user_id: int, db: Session = Depends(get_db)):
|
||||
|
||||
* `sql_app/schemas.py`:
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
=== "Python 3.10+"
|
||||
|
||||
```Python
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/schemas.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.10 及以上版本"
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py310/schemas.py!}
|
||||
{!> ../../../docs_src/sql_databases/sql_app/schemas.py!}
|
||||
```
|
||||
|
||||
* `sql_app/crud.py`:
|
||||
@@ -664,18 +664,18 @@ def read_user(user_id: int, db: Session = Depends(get_db)):
|
||||
|
||||
* `sql_app/main.py`:
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python
|
||||
{!> ../../../docs_src/sql_databases/sql_app/main.py!}
|
||||
```
|
||||
|
||||
## 执行项目
|
||||
|
||||
您可以复制这些代码并按原样使用它。
|
||||
@@ -723,18 +723,18 @@ $ uvicorn sql_app.main:app --reload
|
||||
|
||||
我们将添加中间件（只是一个函数）将为每个请求创建一个新的 SQLAlchemy`SessionLocal`，将其添加到请求中，然后在请求完成后关闭它。
|
||||
|
||||
=== "Python 3.6 及以上版本"
|
||||
|
||||
```Python hl_lines="14-22"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/alt_main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.9 及以上版本"
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="12-20"
|
||||
{!> ../../../docs_src/sql_databases/sql_app_py39/alt_main.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.6+"
|
||||
|
||||
```Python hl_lines="14-22"
|
||||
{!> ../../../docs_src/sql_databases/sql_app/alt_main.py!}
|
||||
```
|
||||
|
||||
!!! info
|
||||
我们将`SessionLocal()`请求的创建和处理放在一个`try`块中。
|
||||
|
||||
|
||||
Reference in new issue
Block a user