Skip to content

Commit f22b8e2

Browse files
authored
Update some usage documents (#27)
* Update some usage documents * Update the theme color
1 parent 5286278 commit f22b8e2

19 files changed

+90
-75
lines changed

docs/advanced/commit.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
SQLAlchemy CRUD Plus 内部很多方法都提供了 `commit` 参数,默认值为 `False`,它既不会执行提交操作,也不包含 `flush`
2+
等行为,要想真正写入到数据库,你可以通过以下几种方案
3+
4+
## `commit=True`
5+
6+
这通常适用于手动创建的 [session 生成器](https://fastapi.tiangolo.com/tutorial/sql-databases/?h=get_db#create-a-dependency),
7+
SQLAlchemy CRUD Plus 将在内部自动执行提交
8+
9+
```py hl_lines="31"
10+
from fastapi import FastAPI, Depends
11+
12+
--8<-- "docs/ext/get_db.py"
13+
14+
app = FastAPI()
15+
16+
17+
class CreateIns(BaseModel):
18+
# your pydantic schema
19+
pass
20+
21+
22+
@app.post('/api', summary='新增一条数据')
23+
async def create(self, obj: CreateIns, db: AsyncSession = Depends(get_db)) -> None:
24+
await self.create_model(db, obj, commit=True)
25+
```
26+
27+
## `begin()`
28+
29+
适用于自动提交,[这一切都由 sqlalchemy 在内部完成](https://docs.sqlalchemy.org.cn/en/20/orm/session_transaction.html)
30+
,因此,用户无需重复调用 commit 方法
31+
32+
```py hl_lines="9"
33+
--8<-- "docs/ext/async_db_session.py"
34+
35+
36+
async def create(self, obj: CreateIns) -> None:
37+
async with async_db_session.begin() as db:
38+
await self.create_model(db, obj)
39+
```

docs/advanced/primary_key.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ async def delete(self, db: AsyncSession, primary_key: int) -> int:
99

1010
## 主键定义
1111

12-
!!! warning 自动主键
12+
!!! tip 自动主键
1313

1414
我们在 SQLAlchemy CRUD Plus 内部通过 [inspect()](https://docs.sqlalchemy.org/en/20/core/inspection.html) 自动搜索表主键,
1515
而非强制绑定主键列必须命名为 id,感谢 [@DavidSche](https://github.com/DavidSche) 提供帮助

docs/changelog.md

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,5 @@
11
# Change Logs
22

3-
* Prepare for 1.3.0 release. PR [#22](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/22) by [@wu-clan](https://github.com/wu-clan).
4-
* Add mor and **gor** filters . PR [#21](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/21) by [@wu-clan](https://github.com/wu-clan).
5-
* Prepare for 1.2.0 release. PR [#20](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/20) by [@wu-clan](https://github.com/wu-clan).
6-
* Add select and sort constructors. PR [#19](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/19) by [@wu-clan](https://github.com/wu-clan).
7-
* Add ci for change logs. PR [#18](https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/18) by [@wu-clan](https://github.com/wu-clan).
8-
93
## 1.4.0 - 2024-08-27
104

115
### What's Changed

docs/ext/async_db_session.py

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
#!/usr/bin/env python3
2-
# -*- coding: utf-8 -*-
31
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
42

53
async_engine = create_async_engine('数据库连接', future=True)

docs/ext/get_db.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
2+
3+
async_engine = create_async_engine('数据库连接', future=True)
4+
async_db_session = async_sessionmaker(async_engine, autoflush=False, expire_on_commit=False)
5+
6+
7+
async def get_db() -> AsyncSession:
8+
"""
9+
session 生成器
10+
"""
11+
session = async_db_session()
12+
try:
13+
yield session
14+
except Exception as se:
15+
await session.rollback()
16+
raise se
17+
finally:
18+
await session.close()

docs/ext/model.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
#!/usr/bin/env python3
2+
# -*- coding: utf-8 -*-

docs/index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,12 @@
2020
pdm add sqlalchemy-crud-plus
2121
```
2222

23+
=== "uv"
24+
25+
```sh
26+
uv add sqlalchemy-crud-plus
27+
```
28+
2329
## 示例
2430

2531
=== "api.py"

docs/installing.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@
1818
```sh
1919
pdm add sqlalchemy-crud-plus
2020
```
21+
22+
=== "uv"
23+
24+
```sh
25+
uv add sqlalchemy-crud-plus
26+
```

docs/usage/create_model.md

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ async def create_model(
88
) -> Model:
99
````
1010

11-
!!! note "create_model 独特的关键字参数"
11+
!!! note "create_model <独特>的关键字参数"
1212

1313
除了必须传入 obj schema 外,还可以通过关键字入参,传入非 schema
1414
参数,比如,对于某些特定场景,其中一个字段并不是通用的,也不需要进行输入控制,只需在写入时赋予指定值,那么你可以使用关键字入参即可
@@ -24,26 +24,7 @@ async def create_model(
2424
1. 在数据被最终写入前,所有入参(schema 和关键字参数)都会赋值给 SQLAlchemy 模型,即便你传入了非模型数据,
2525
这也是安全的,因为它不会被模型所引用
2626

27-
## 提交
2827

29-
此方法提供 `commit` 参数,默认值为 False,它既不会执行提交操作,也不包含 `flush` 等行为,要想真正写入到数据库,你可以通过以下几种方案
30-
31-
1. 设置 `commit=True` 手动提交
32-
33-
```py hl_lines="2"
34-
async def create(self, db: AsyncSession, obj: CreateIns) -> None:
35-
await self.create_model(db, obj, commit=True)
36-
```
37-
38-
2. 使用 `begin()` 事务自动提交
39-
40-
```py hl_lines="9"
41-
--8<-- "docs/ext/async_db_session.py"
42-
43-
async def create(self, obj: CreateIns) -> None:
44-
async with async_db_session.begin() as db:
45-
await self.create_model(db, obj)
46-
```
4728

4829
## 示例
4930

docs/usage/create_models.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ async def create_models(
77
) -> list[Model]:
88
```
99

10-
此方法提供 `commit` 参数,详见:[提交](./create_model.md/#_1)
10+
此方法提供 `commit` 参数,详见:[提交](../advanced/commit.md)
1111

1212
## 示例
1313

0 commit comments

Comments
 (0)