Update prek docs typing and links (#97)

wu-clan · web-flow · commit bb59208359c4 · 2026-04-14T23:40:35.000+08:00
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -30,5 +30,5 @@ jobs:
       - name: Run lint
         run: |
           source .venv/bin/activate
-          chmod 755 pre-commit.sh
-          ./pre-commit.sh
+          chmod 755 prek.sh
+          ./prek.sh
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -6,7 +6,7 @@ repos:
       - id: check-toml
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.14.0
+    rev: v0.15.10
     hooks:
       - id: ruff
         args:
@@ -15,7 +15,7 @@ repos:
       - id: ruff-format
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.0
+    rev: 0.11.6
     hooks:
       - id: uv-lock
       - id: uv-export
diff --git a/README.md b/README.md
@@ -13,15 +13,9 @@ pip install sqlalchemy-crud-plus
 ### uv
 
 ```shell
-uv pip install sqlalchemy-crud-plus
-# 或
 uv add sqlalchemy-crud-plus
 ```
 
 ## 文档
 
 [SQLAlchemy CRUD Plus](https://fastapi-practices.github.io/sqlalchemy-crud-plus)
-
-## 互动
-
-[Discord](https://wu-clan.github.io/homepage/)
diff --git a/docs/advanced/filter.md b/docs/advanced/filter.md
@@ -278,7 +278,7 @@ recent_users = await user_crud.select_models(
 
 ## 注意事项
 
-1. **参数命名**: 主键参数使用 `pk`，避免与 Python 关键字 `id` 冲突
+1. **参数命名**: 主键参数使用 `pk`，避免与常见字段名 `id` 混淆
 2. **自动主键检测**: 支持各种主键类型，包括字符串主键和复合主键
 3. **性能考虑**: 为常用过滤字段创建数据库索引
 4. **OR 查询**: 过多 OR 条件可能影响性能，合理使用
diff --git a/docs/advanced/relationship.md b/docs/advanced/relationship.md
@@ -516,7 +516,7 @@ users = await user_crud.select_models(
 2. 关联查询获取多表数据
     - 使用原生 `select(Model1, Model2).join()` 获取多表数据
     - 构建字典结果用于 API 返回
-    - `JoinConfig` 主要用于过滤，不直接返回关联表数据
+    - `JoinConfig` 默认主要用于过滤；如需返回关联表数据，设置 `fill_result=True`
 
 3. 性能优化
     - 为关联字段添加索引
diff --git a/docs/advanced/transaction.md b/docs/advanced/transaction.md
@@ -194,6 +194,7 @@ async with async_session.begin() as session:
     await user_crud.update_model_by_column(
         session,
         obj={"is_active": True},
+        allow_multiple=True,
         created_at__ge=datetime.now() - timedelta(days=1)
     )
 ```
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -170,7 +170,7 @@ await user_crud.update_model_by_column(
 await user_crud.delete_model(session, pk=1)
 
 # 条件删除
-await user_crud.delete_model_by_column(session, is_active=False)
+await user_crud.delete_model_by_column(session, allow_multiple=True, is_active=False)
 
 # 逻辑删除（推荐）
 await user_crud.delete_model_by_column(
@@ -241,6 +241,8 @@ users_dict = [
     {"name": "用户3", "email": "user3@example.com"}
 ]
 users = await user_crud.bulk_create_models(session, users_dict)
+if users is None:
+    print("当前数据库已写入数据，但不返回 ORM 实例")
 
 # 批量更新不同数据
 users_update = [
diff --git a/docs/usage/crud.md b/docs/usage/crud.md
@@ -39,6 +39,10 @@ users_dict = [
     {"name": "用户5", "email": "user5@example.com"}
 ]
 users = await user_crud.bulk_create_models(session, users_dict)
+
+# 仅当数据库方言支持 executemany RETURNING 时，users 才会是模型列表
+if users is None:
+    print("记录已插入，但当前方言不返回 ORM 实例")
 ```
 
 ## 查询操作
@@ -323,13 +327,14 @@ async def batch_update_same_data(session: AsyncSession, update_data: dict, **fil
     return await user_crud.update_model_by_column(
         session,
         obj=update_data,
+        allow_multiple=True,
         **filters
     )
 ```
 
 ## 注意事项
 
-1. **主键参数**: 由于 `id` 是 Python 关键字，主键参数使用 `pk`
+1. **主键参数**: 主键参数使用 `pk`，避免与常见字段名 `id` 混淆
 2. **事务管理**: 推荐使用 `async with session.begin()` 自动管理事务
 3. **flush vs commit**: `flush` 用于获取主键，`commit` 用于立即提交
 4. **复合主键**: 使用元组格式，如 `pk=(1, 2)`
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -88,9 +88,6 @@ extra:
     - icon: fontawesome/brands/github
       link: https://github.com/fastapi-practices/sqlalchemy-crud-plus
       name: GitHub
-    - icon: fontawesome/brands/discord
-      link: https://discord.com/invite/yNN3wTbVAC
-      name: Discord
 
 extra_javascript:
 - https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js
diff --git a/pre-commit.sh b/pre-commit.sh
diff --git a/prek.sh b/prek.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+prek run --all-files --verbose --show-diff-on-failure
diff --git a/pyproject.toml b/pyproject.toml
@@ -28,20 +28,19 @@ repository = "https://github.com/fastapi-practices/sqlalchemy-crud-plus"
 
 [dependency-groups]
 dev = [
-    "aiosqlite>=0.21.0",
-    "pytest>=8.4.0",
-    "pytest-asyncio>=1.2.0",
-    "pytest-cov>=7.0.0",
-    "ty>=0.0.1a23",
+    "aiosqlite>=0.22.1",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ty>=0.0.30",
 ]
 lint = [
-    "pre-commit>=4.3.0",
+    "prek>=0.3.9",
 ]
 docs = [
-    "click==8.2.1",
-    "mkdocs-material>=9.6.22",
-    "mkdocstrings[python]>=0.30.0",
-    "ruff>=0.14.0",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.3",
+    "ruff>=0.15.10",
 ]
 
 [tool.uv]
diff --git a/requirements.txt b/requirements.txt
@@ -1,72 +1,54 @@
 # This file was autogenerated by uv via the following command:
 #    uv export -o requirements.txt --no-hashes
 -e .
-aiosqlite==0.21.0
+aiosqlite==0.22.1
 annotated-types==0.7.0
     # via pydantic
 backports-asyncio-runner==1.2.0 ; python_full_version < '3.11'
     # via pytest-asyncio
-cfgv==3.4.0
-    # via pre-commit
 colorama==0.4.6 ; sys_platform == 'win32'
     # via pytest
-coverage==7.11.1
+coverage==7.13.5
     # via pytest-cov
-distlib==0.4.0
-    # via virtualenv
-exceptiongroup==1.3.0 ; python_full_version < '3.11'
+exceptiongroup==1.3.1 ; python_full_version < '3.11'
     # via pytest
-filelock==3.20.0
-    # via virtualenv
-greenlet==3.2.4 ; platform_machine == 'AMD64' or platform_machine == 'WIN32' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'ppc64le' or platform_machine == 'win32' or platform_machine == 'x86_64'
+greenlet==3.4.0 ; platform_machine == 'AMD64' or platform_machine == 'WIN32' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'ppc64le' or platform_machine == 'win32' or platform_machine == 'x86_64'
     # via sqlalchemy
-identify==2.6.15
-    # via pre-commit
-iniconfig==2.1.0
+iniconfig==2.3.0
     # via pytest
-nodeenv==1.9.1
-    # via pre-commit
-packaging==25.0
+packaging==26.0
     # via pytest
-platformdirs==4.5.0
-    # via virtualenv
 pluggy==1.6.0
     # via
     #   pytest
     #   pytest-cov
-pre-commit==4.3.0
-pydantic==2.12.2
+prek==0.3.9
+pydantic==2.13.0
     # via sqlalchemy-crud-plus
-pydantic-core==2.41.4
+pydantic-core==2.46.0
     # via pydantic
-pygments==2.19.2
+pygments==2.20.0
     # via pytest
-pytest==8.4.2
+pytest==9.0.3
     # via
     #   pytest-asyncio
     #   pytest-cov
-pytest-asyncio==1.2.0
-pytest-cov==7.0.0
-pyyaml==6.0.3
-    # via pre-commit
-sqlalchemy==2.0.44
+pytest-asyncio==1.3.0
+pytest-cov==7.1.0
+sqlalchemy==2.0.49
     # via sqlalchemy-crud-plus
-tomli==2.3.0 ; python_full_version <= '3.11'
+tomli==2.4.1 ; python_full_version <= '3.11'
     # via
     #   coverage
     #   pytest
-ty==0.0.1a23
+ty==0.0.30
 typing-extensions==4.15.0
     # via
-    #   aiosqlite
     #   exceptiongroup
     #   pydantic
     #   pydantic-core
     #   pytest-asyncio
     #   sqlalchemy
     #   typing-inspection
-    #   virtualenv
 typing-inspection==0.4.2
     # via pydantic
-virtualenv==20.35.3
-    # via pre-commit
diff --git a/sqlalchemy_crud_plus/crud.py b/sqlalchemy_crud_plus/crud.py
@@ -670,7 +670,7 @@ async def delete_model_by_column(
             if total_count > 1:
                 raise MultipleResultsError(f'Only one record is expected to be deleted, found {total_count} records.')
 
-        data = {deleted_flag_column: True}
+        data: dict[str, Any] = {deleted_flag_column: True}
 
         if deleted_at_column in self.model_column_names:
             data[deleted_at_column] = deleted_at_factory
diff --git a/sqlalchemy_crud_plus/types.py b/sqlalchemy_crud_plus/types.py
@@ -26,21 +26,16 @@
     # Load
     'defer',
     'load_only',
-    'selectin_polymorphic',
     'undefer',
     'undefer_group',
-    'with_expression',
 ]
 
 # https://docs.sqlalchemy.org/en/20/orm/queryguide/columns.html#column-loading-api
 ColumnLoadingStrategyType = Literal[
     'defer',
-    'deferred',
     'load_only',
-    'query_expression',
     'undefer',
     'undefer_group',
-    'with_expression',
 ]
 
 LoadStrategies = list[str] | dict[str, RelationshipLoadingStrategyType] | dict[str, ColumnLoadingStrategyType]
@@ -55,7 +50,7 @@
 class JoinConfig(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    model: type[Model] | AliasedClass | Alias | Table = Field(
+    model: type[DeclarativeBase] | AliasedClass | Alias | Table = Field(
         description='The target model, aliased class, alias, or table to join with'
     )
     join_on: Any = Field(description='The join condition expression (e.g., model.id == other_model.id)')
diff --git a/sqlalchemy_crud_plus/utils.py b/sqlalchemy_crud_plus/utils.py
@@ -22,7 +22,6 @@
 )
 from sqlalchemy.orm.util import AliasedClass
 from sqlalchemy.sql.base import ExecutableOption
-from sqlalchemy.sql.operators import ColumnOperators
 from sqlalchemy.sql.schema import Column
 
 from sqlalchemy_crud_plus.errors import (
@@ -134,7 +133,7 @@ def get_column(model: type[Model] | AliasedClass, field_name: str) -> Column:
     return column
 
 
-def _create_or_filters(column: Column, op: str, value: dict[str, Any]) -> list[ColumnOperators | None]:
+def _create_or_filters(column: Column, op: str, value: dict[str, Any]) -> list[ColumnElement[bool]]:
     """
     Create OR filter expressions.
 
@@ -152,7 +151,7 @@ def _create_or_filters(column: Column, op: str, value: dict[str, Any]) -> list[C
     return or_filters
 
 
-def _create_arithmetic_filters(column: Column, op: str, value: dict[str, Any]) -> list[ColumnOperators | None]:
+def _create_arithmetic_filters(column: Column, op: str, value: dict[str, Any]) -> list[ColumnElement[bool]]:
     """
     Create arithmetic filter expressions.
 
@@ -178,7 +177,7 @@ def _create_arithmetic_filters(column: Column, op: str, value: dict[str, Any]) -
     return arithmetic_filters
 
 
-def _create_and_filters(column: Column, op: str, value: Any) -> list[ColumnElement[Any] | None]:
+def _create_and_filters(column: Column, op: str, value: Any) -> list[ColumnElement[bool]]:
     """
     Create AND filter expressions.
 
diff --git a/tests/test_relationship.py b/tests/test_relationship.py
@@ -327,35 +327,26 @@ async def test_column_loading_strategies_defer(
     db: AsyncSession, rel_sample_data: dict, rel_crud_user: CRUDPlus[RelUser]
 ):
     users = rel_sample_data['users']
-    try:
-        user = await rel_crud_user.select_model(db, users[0].id, load_strategies={'name': 'defer'})
-        assert user is not None
-    except (AttributeError, Exception):
-        pass
+    user = await rel_crud_user.select_model(db, users[0].id, load_strategies={'name': 'defer'})
+    assert user is not None
 
 
 @pytest.mark.asyncio
 async def test_column_loading_strategies_load_only(
     db: AsyncSession, rel_sample_data: dict, rel_crud_user: CRUDPlus[RelUser]
 ):
     users = rel_sample_data['users']
-    try:
-        user = await rel_crud_user.select_model(db, users[0].id, load_strategies={'id': 'load_only'})
-        assert user is not None
-    except (AttributeError, Exception):
-        pass
+    user = await rel_crud_user.select_model(db, users[0].id, load_strategies={'id': 'load_only'})
+    assert user is not None
 
 
 @pytest.mark.asyncio
 async def test_column_loading_strategies_undefer(
     db: AsyncSession, rel_sample_data: dict, rel_crud_user: CRUDPlus[RelUser]
 ):
     users = rel_sample_data['users']
-    try:
-        user = await rel_crud_user.select_model(db, users[0].id, load_strategies={'name': 'undefer'})
-        assert user is not None
-    except (AttributeError, Exception):
-        pass
+    user = await rel_crud_user.select_model(db, users[0].id, load_strategies={'name': 'undefer'})
+    assert user is not None
 
 
 @pytest.mark.asyncio
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -194,6 +194,7 @@ async with async_session.begin() as session:`
`194`	`194`	`await user_crud.update_model_by_column(`
`195`	`195`	`session,`
`196`	`196`	`obj={"is_active": True},`
	`197`	`+ allow_multiple=True,`
`197`	`198`	`created_at__ge=datetime.now() - timedelta(days=1)`
`198`	`199`	`)`
`199`	`200`	```