Skip to content

Commit 69c60cf

Browse files
wu-clanwu-clan
committed
Update the API reference document style
1 parent 3cd02a0 commit 69c60cf

File tree

6 files changed

+49
-195
lines changed

6 files changed

+49
-195
lines changed

‎docs/api/crud-plus.md

Lines changed: 0 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -5,78 +5,3 @@
55
## 类定义
66

77
::: sqlalchemy_crud_plus.CRUDPlus
8-
9-
## 构造函数
10-
11-
```python
12-
from sqlalchemy_crud_plus import CRUDPlus
13-
from myapp.models import User
14-
15-
user_crud = CRUDPlus(User)
16-
```
17-
18-
## 查询方法
19-
20-
### select_model
21-
22-
::: sqlalchemy_crud_plus.CRUDPlus.select_model
23-
24-
### select_model_by_column
25-
26-
::: sqlalchemy_crud_plus.CRUDPlus.select_model_by_column
27-
28-
### select_models
29-
30-
::: sqlalchemy_crud_plus.CRUDPlus.select_models
31-
32-
### select_models_order
33-
34-
::: sqlalchemy_crud_plus.CRUDPlus.select_models_order
35-
36-
### count
37-
38-
::: sqlalchemy_crud_plus.CRUDPlus.count
39-
40-
### exists
41-
42-
::: sqlalchemy_crud_plus.CRUDPlus.exists
43-
44-
## 创建方法
45-
46-
### create_model
47-
48-
::: sqlalchemy_crud_plus.CRUDPlus.create_model
49-
50-
### create_models
51-
52-
::: sqlalchemy_crud_plus.CRUDPlus.create_models
53-
54-
## 更新方法
55-
56-
### update_model
57-
58-
::: sqlalchemy_crud_plus.CRUDPlus.update_model
59-
60-
### update_model_by_column
61-
62-
::: sqlalchemy_crud_plus.CRUDPlus.update_model_by_column
63-
64-
## 删除方法
65-
66-
### delete_model
67-
68-
::: sqlalchemy_crud_plus.CRUDPlus.delete_model
69-
70-
### delete_model_by_column
71-
72-
::: sqlalchemy_crud_plus.CRUDPlus.delete_model_by_column
73-
74-
## 底层方法
75-
76-
### select
77-
78-
::: sqlalchemy_crud_plus.CRUDPlus.select
79-
80-
### select_order
81-
82-
::: sqlalchemy_crud_plus.CRUDPlus.select_order

‎docs/api/errors.md

Lines changed: 5 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -6,71 +6,16 @@
66

77
SQLAlchemy CRUD Plus 定义了以下自定义异常类型：
88

9-
::: sqlalchemy_crud_plus.errors.SelectOperatorError
10-
11-
::: sqlalchemy_crud_plus.errors.ColumnSortError
12-
139
::: sqlalchemy_crud_plus.errors.ModelColumnError
1410

15-
::: sqlalchemy_crud_plus.errors.JoinConditionError
11+
::: sqlalchemy_crud_plus.errors.SelectOperatorError
1612

17-
::: sqlalchemy_crud_plus.errors.LoadingStrategyError
13+
::: sqlalchemy_crud_plus.errors.ColumnSortError
1814

1915
::: sqlalchemy_crud_plus.errors.MultipleResultsError
2016

21-
## 异常层次结构
22-
23-
```
24-
Exception
25-
├── SelectOperatorError # 选择操作符错误
26-
├── ColumnSortError # 列排序错误
27-
├── ModelColumnError # 模型列错误
28-
├── JoinConditionError # JOIN 条件错误
29-
├── LoadingStrategyError # 加载策略错误
30-
└── MultipleResultsFoundError # 多结果发现错误
31-
```
32-
33-
## 常见异常场景
34-
35-
### SelectOperatorError
17+
::: sqlalchemy_crud_plus.errors.CompositePrimaryKeysError
3618

37-
当使用不支持的过滤操作符时抛出。
38-
39-
```python
40-
from sqlalchemy_crud_plus.errors import SelectOperatorError
41-
42-
try:
43-
users = await user_crud.select_models(session, name__invalid_op='test')
44-
except SelectOperatorError as e:
45-
print(f"不支持的操作符: {e}")
46-
```
47-
48-
### ModelColumnError
49-
50-
当访问模型中不存在的列时抛出。
51-
52-
```python
53-
from sqlalchemy_crud_plus.errors import ModelColumnError
54-
55-
try:
56-
users = await user_crud.select_models(session, nonexistent_column='value')
57-
except ModelColumnError as e:
58-
print(f"列不存在: {e}")
59-
```
60-
61-
### MultipleResultsFoundError
62-
63-
当期望单个结果但找到多个结果时抛出。
64-
65-
```python
66-
from sqlalchemy_crud_plus.errors import MultipleResultsFoundError
19+
::: sqlalchemy_crud_plus.errors.LoadingStrategyError
6720

68-
try:
69-
count = await user_crud.update_model_by_column(
70-
session,
71-
obj={"name": "新名称"},
72-
name__like='%张%' # 可能匹配多条记录
73-
)
74-
except MultipleResultsFoundError as e:
75-
print(f"找到多条记录: {e}")
76-
```
21+
::: sqlalchemy_crud_plus.errors.JoinConditionError

‎docs/api/types.md

Lines changed: 31 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,20 @@ post_crud: CRUDPlus[Post] = CRUDPlus(Post)
3434
### LoadStrategiesConfig
3535

3636
```python
37-
from typing import Union, Dict, List
38-
39-
LoadStrategiesConfig = Union[
40-
List[str], # Simple list format
41-
Dict[str, str], # Strategy mapping
42-
Dict[str, Dict[str, str]] # Nested strategies
37+
from typing import Literal
38+
39+
LoadingStrategy = Literal[
40+
'selectinload', # SELECT IN loading (recommended for one-to-many)
41+
'joinedload', # JOIN loading (recommended for one-to-one)
42+
'subqueryload', # Subquery loading (for large datasets)
43+
'contains_eager', # Use with explicit JOINs
44+
'raiseload', # Prevent lazy loading
45+
'noload', # Don't load relationship
4346
]
4447

48+
# Configuration for relationship loading strategies
49+
LoadStrategiesConfig = list[str] | dict[str, LoadingStrategy]
50+
4551
# Examples
4652
load_strategies: LoadStrategiesConfig = ['posts', 'profile']
4753
load_strategies: LoadStrategiesConfig = {
@@ -53,13 +59,18 @@ load_strategies: LoadStrategiesConfig = {
5359
### JoinConditionsConfig
5460

5561
```python
56-
from typing import Union, Dict, List
62+
from typing import Literal
5763

58-
JoinConditionsConfig = Union[
59-
List[str], # Simple list format
60-
Dict[str, str] # JOIN type mapping
64+
JoinType = Literal[
65+
'inner', # INNER JOIN
66+
'left', # LEFT OUTER JOIN
67+
'right', # RIGHT OUTER JOIN
68+
'full', # FULL OUTER JOIN
6169
]
6270

71+
# Configuration for JOIN conditions
72+
JoinConditionsConfig = list[str] | dict[str, JoinType]
73+
6374
# Examples
6475
join_conditions: JoinConditionsConfig = ['posts', 'profile']
6576
join_conditions: JoinConditionsConfig = {
@@ -71,10 +82,9 @@ join_conditions: JoinConditionsConfig = {
7182
### QueryOptions
7283

7384
```python
74-
from typing import List, Any
75-
from sqlalchemy.orm import Load
85+
from sqlalchemy.sql.base import ExecutableOption
7686

77-
QueryOptions = List[Load]
87+
QueryOptions = list[ExecutableOption]
7888

7989
# Example
8090
from sqlalchemy.orm import selectinload, joinedload
@@ -85,6 +95,8 @@ load_options: QueryOptions = [
8595
]
8696
```
8797

98+
## 工具类型
99+
88100
### 常用过滤器模式
89101

90102
```python
@@ -96,9 +108,9 @@ age__le: int = 60
96108
status__ne: int = 0
97109

98110
# Range operators
99-
id__in: List[int] = [1, 2, 3, 4, 5]
100-
status__not_in: List[int] = [0, -1]
101-
age__between: List[int] = [30, 40]
111+
id__in: list[int] = [1, 2, 3, 4, 5]
112+
status__not_in: list[int] = [0, -1]
113+
age__between: list[int] = [30, 40]
102114

103115
# String operators
104116
name__like: str = '%张%'
@@ -111,51 +123,16 @@ deleted_at__is: None = None
111123
profile_id__is_not: None = None
112124

113125
# OR conditions
114-
__or__: Dict[str, List[Any]] = {
126+
__or__: dict[str, Any] = {
115127
'email__endswith': ['@gmail.com', '@qq.com']
116128
}
117129
```
118130

119-
## 会话类型
120-
121-
### AsyncSession
122-
123-
```python
124-
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
125-
126-
# Session factory type
127-
AsyncSessionFactory = async_sessionmaker[AsyncSession]
128-
129-
# Usage
130-
_async_db_session: AsyncSessionFactory = async_sessionmaker(
131-
engine,
132-
expire_on_commit=False
133-
)
134-
```
135-
136-
## 工具类型
137-
138-
### 主键类型
139-
140-
```python
141-
from typing import Union, Tuple, Any
142-
143-
# Single or composite primary key
144-
PrimaryKeyType = Union[Any, Tuple[Any, ...]]
145-
146-
# Examples
147-
pk: PrimaryKeyType = 1 # Single primary key
148-
pk: PrimaryKeyType = (1, 2) # Composite primary key
149-
pk: PrimaryKeyType = "uuid-string" # String primary key
150-
```
151-
152131
### 排序配置
153132

154133
```python
155-
from typing import Union, List
156-
157-
SortColumns = Union[str, List[str]]
158-
SortOrders = Union[str, List[str]]
134+
SortColumns = str | list[str]
135+
SortOrders = str | list[str] | None
159136

160137
# Examples
161138
sort_columns: SortColumns = "created_time"

‎docs/extra/custom.css

Whitespace-only changes.

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# SQLAlchemy CRUD Plus
1+
<h1 style="text-align: center; margin: 3rem auto">SQLAlchemy CRUD Plus</h1>
22

33
SQLAlchemy CRUD Plus 是一个强大的 Python 库，为 SQLAlchemy 提供了增强的 CRUD（创建、读取、更新、删除）操作功能
44

‎mkdocs.yml

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,6 @@ nav:
2323
theme:
2424
name: material
2525
language: zh
26-
font:
27-
code: Roboto Mono
2826
palette:
2927
- media: '(prefers-color-scheme)'
3028
toggle:
@@ -50,7 +48,6 @@ theme:
5048
- navigation.instant.progress
5149
- navigation.path
5250
- navigation.tracking
53-
- navigation.tabs
5451
- navigation.tabs.sticky
5552
- navigation.top
5653
- navigation.footer
@@ -65,9 +62,16 @@ plugins:
6562
python:
6663
options:
6764
docstring_style: sphinx
68-
show_source: true
65+
filters: [ "!^_" ]
66+
parameter_headings: true
6967
show_root_heading: true
70-
show_root_toc_entry: true
68+
show_root_full_path: false
69+
show_symbol_type_heading: true
70+
show_symbol_type_toc: true
71+
members_order: source
72+
separate_signature: true
73+
show_signature_annotations: true
74+
signature_crossrefs: true
7175

7276
markdown_extensions:
7377
- toc:
@@ -96,3 +100,6 @@ extra:
96100
link: https://github.com/wu-clan/sqlalchemy-crud-plus
97101
- icon: fontawesome/brands/discord
98102
link: https://wu-clan.github.io/homepage/
103+
104+
extra_css:
105+
- 'extra/custom.css'

0 commit comments

Comments
 (0)