Add count and exists usages (#37)

* Add count and exists usages

* fix lint

Author: wu-clan

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: end-of-file-fixer
       - id: check-toml
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.7.2
+    rev: v0.11.5
     hooks:
       - id: ruff
         args:
@@ -16,7 +16,7 @@ repos:
       - id: ruff-format
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.4.29
+    rev: 0.6.14
     hooks:
       - id: uv-lock
       - id: uv-export

README.md

@@ -1,6 +1,6 @@
 # sqlalchemy-crud-plus
 
-Asynchronous CRUD operations based on SQLAlChemy 2.0
+基于 SQLAlChemy 2.0 的异步 CRUD 操作
 
 ## Download
 
@@ -14,7 +14,7 @@ pip install sqlalchemy-crud-plus
 
 ## 互动
 
-[TG / Discord](https://wu-clan.github.io/homepage/)
+[Discord](https://wu-clan.github.io/homepage/)
 
 ## 赞助
 

docs/advanced/commit.md

@@ -1,4 +1,4 @@
-SQLAlchemy CRUD Plus 内部很多方法都提供了 `commit` 参数，默认值为 `False`，它既不会执行提交操作，也不包含 `flush`
+SQLAlchemy CRUD Plus 内部为很多方法都提供了 `commit` 参数，默认值为 `False`，它既不会执行提交操作，也不包含 `flush`
 等行为，要想真正写入到数据库，你可以通过以下几种方案
 
 ## `commit=True`
@@ -9,6 +9,8 @@ SQLAlchemy CRUD Plus 将在内部自动执行提交
 ```py hl_lines="31"
 from fastapi import FastAPI, Depends
 
+from pydantic import BaseModel
+
 --8<-- "docs/ext/get_db.py"
 
 app = FastAPI()
@@ -32,7 +34,6 @@ async def create(self, obj: CreateIns, db: AsyncSession = Depends(get_db)) -> No
 ```py hl_lines="9"
 --8<-- "docs/ext/async_db_session.py"
 
-
 async def create(self, obj: CreateIns) -> None:
     async with async_db_session.begin() as db:
         await self.create_model(db, obj)

docs/advanced/filter.md

@@ -1,15 +1,5 @@
 SQLAlchemy CRUD Plus 支持高级过滤选项，允许使用运算符查询记录，如大于（`__gt`）、小于（`__lt`）；
 
-大多数过滤器操作符需要一个字符串或整数值
-
-```python
-# 获取年龄大于 30 岁以上的员工
-items = await item_crud.select_models(
-    session=db,
-    age__gt=30,
-)
-```
-
 ## 比较运算符
 
 - `__gt`：大于
@@ -20,6 +10,14 @@ items = await item_crud.select_models(
 - `__ne`: 不等于
 - `__between`: 在两者之间
 
+```python title="e.g."
+# 获取年龄大于 30 岁以上的员工
+items = await item_crud.select_models(
+    session=db,
+    age__gt=30,
+)
+```
+
 ## IN 比较
 
 - `__in`: 包含
@@ -30,7 +28,7 @@ items = await item_crud.select_models(
 - `__is`：用于测试 “真”、“假” 和 “无”。
 - `__is_not`：“is” 的否定
 - `__is_distinct_from`: 产生 SQL IS DISTINCT FROM
-- `__is_not_distinct_from`: Produces SQL IS NOT DISTINCT FROM
+- `__is_not_distinct_from`: 产生 SQL IS NOT DISTINCT FROM
 - `__like`：针对特定文本模式的 SQL “like” 搜索
 - `__not_like`：“like” 的否定
 - `__ilike`：大小写不敏感的 “like”
@@ -52,7 +50,13 @@ items = await item_crud.select_models(
 
 ## 算术运算符
 
-此过滤器使用方法需查看：[算数](#_7)
+!!! note
+
+    此过滤器必须传递字典，且字典结构必须为 `{'value': xxx, 'condition': {'已支持的过滤器': xxx}}`
+
+    `value`：此值将与列值进行条件运算
+
+    `condition`：此值将作为运算条件和预期结果
 
 - `__add`: Python `+` 运算符
 - `__radd`: Python `+` 反向运算
@@ -67,6 +71,14 @@ items = await item_crud.select_models(
 - `__mod`: Python `%` 运算符
 - `__rmod`: Python `%` 反向运算
 
+```python title="e.g."
+# 获取薪资打八折以后仍高于 20k 的员工
+items = await item_crud.select_models(
+    session=db,
+    payroll__mul={'value': 0.8, 'condition': {'gt': 20000}},
+)
+```
+
 ## BETWEEN、IN、NOT IN
 
 !!! note
@@ -84,7 +96,7 @@ items = await item_crud.select_models(
 
 ## AND
 
-可以通过将多个过滤器链接在一起来实现 AND 子句
+当多个过滤器同时存在时，将自动转为 AND 子句
 
 ```python
 # 获取年龄在 30 以上，薪资大于 20k 的员工
@@ -142,21 +154,3 @@ items = await item_crud.select_models(
     ]
 )
 ```
-
-## 算数
-
-!!! note
-
-    此过滤器必须传递字典，且字典结构必须为 `{'value': xxx, 'condition': {'已支持的过滤器': xxx}}`
-
-    `value`：此值将与列值进行运算
-
-    `condition`：此值将作为运算后的比较值，比较条件取决于使用的过滤器
-
-```python
-# 获取薪资打八折以后仍高于 20k 的员工
-items = await item_crud.select_models(
-    session=db,
-    payroll__mul={'value': 0.8, 'condition': {'gt': 20000}},
-)
-```

docs/advanced/primary_key.md

@@ -1,6 +1,6 @@
 !!! note 主键参数命名
 
-    由于在 python 内部 id 的特殊性，我们设定 pk (参考 Django) 作为模型主键命名，所以在 crud 方法中，任何涉及到主键的地方，入参都为 `pk`
+    由于在 python 内部 `id` 为关键字，因此，我们设定默认主键入参为 `pk`。这仅用于函数入参，并不要求模型主键必须定义为 `pk`
 
 ```py title="e.g." hl_lines="2"
 async def delete(self, db: AsyncSession, primary_key: int) -> int:
@@ -12,11 +12,10 @@ async def delete(self, db: AsyncSession, primary_key: int) -> int:
 !!! tip 自动主键
 
     我们在 SQLAlchemy CRUD Plus 内部通过 [inspect()](https://docs.sqlalchemy.org/en/20/core/inspection.html) 自动搜索表主键，
-    而非强制绑定主键列必须命名为 id，感谢 [@DavidSche](https://github.com/DavidSche) 提供帮助 
+    而非强制绑定主键列必须命名为 `id`
 
 ```py title="e.g." hl_lines="4"
 class ModelIns(Base):
-    # your sqlalchemy model
-    # define your primary_key
-    custom_id: Mapped[int] = mapped_column(primary_key=True, index=True, autoincrement=True)
+    # define primary_key
+    primary_key: Mapped[int] = mapped_column(primary_key=True, index=True, autoincrement=True)
 ```

docs/ext/get_db.py

@@ -1,18 +1,14 @@
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from typing import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 
 async_engine = create_async_engine('数据库连接', future=True)
 async_db_session = async_sessionmaker(async_engine, autoflush=False, expire_on_commit=False)
 
 
-async def get_db() -> AsyncSession:
+async def get_db() -> AsyncGenerator:
     """
     session 生成器
     """
-    session = async_db_session()
-    try:
+    async with async_db_session() as session:
         yield session
-    except Exception as se:
-        await session.rollback()
-        raise se
-    finally:
-        await session.close()

docs/ext/model.py

@@ -0,0 +1,46 @@
+查询符合条件过滤的记录数
+
+```py title="count" hl_lines="14"
+from sqlalchemy_crud_plus import CRUDPlus
+
+from sqlalchemy import DeclarativeBase as Base
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class ModelIns(Base):
+    # your sqlalchemy model
+    pass
+
+
+class CRUDIns(CRUDPlus[ModelIns]):
+    async def create(self, db: AsyncSession) -> int:
+        return await self.count(db, name="foo")
+```
+
+## API
+
+```python
+async def count(
+    self,
+    session: AsyncSession,
+    filters: ColumnElement | list[ColumnElement] | None = None,
+    **kwargs,
+) -> int:
+```
+
+**Parameters:**
+
+| Name    | Type                                               | Description      | Default |
+|---------|----------------------------------------------------|------------------|---------|
+| session | AsyncSession                                       | 数据库会话            | 必填      |
+| filters | `ColumnElement `\|` list[ColumnElement] `\|` None` | 要应用于查询的 WHERE 子句 | `None`  |
+
+!!! note "**kwargs"
+
+    [条件过滤](../advanced/filter.md)，将创建条件查询 SQL
+
+**Returns:**
+
+| Type | Description |
+|------|-------------|
+| int  | 记录数         |

docs/usage/count.md

@@ -1,4 +1,32 @@
-````py
+添加单条新纪录
+
+```py title="create_model" hl_lines="21"
+from pydantic import BaseModel
+
+from sqlalchemy_crud_plus import CRUDPlus
+
+from sqlalchemy import DeclarativeBase as Base
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class ModelIns(Base):
+    # your sqlalchemy model
+    pass
+
+
+class CreateIns(BaseModel):
+    # your pydantic schema
+    pass
+
+
+class CRUDIns(CRUDPlus[ModelIns]):
+    async def create(self, db: AsyncSession, obj: CreateIns) -> ModelIns:
+        return await self.create_model(db, obj)
+```
+
+## API
+
+```py
 async def create_model(
     self,
     session: AsyncSession,
@@ -7,12 +35,18 @@ async def create_model(
     commit: bool = False,
     **kwargs,
 ) -> Model:
-````
+```
 
-- 此方法提供 `flush` 参数，详见：[冲洗](../advanced/flush.md)
-- 此方法提供 `commit` 参数，详见：[提交](../advanced/commit.md)
+**Parameters:**
 
-!!! note "关键字参数"
+| Name    | Type         | Description                 | Default |
+|---------|--------------|-----------------------------|---------|
+| session | AsyncSession | 数据库会话                       | 必填      |
+| obj     | TypeVar      | 创建新数据参数                     | 必填      |
+| flush   | bool         | [冲洗](../advanced/flush.md)  | `False` |
+| commit  | bool         | [提交](../advanced/commit.md) | `False` |
+
+!!! note "**kwargs"
 
     除了必须传入 obj schema 外，还可以通过关键字入参，传入非 schema
     参数，比如，对于某些特定场景，其中一个字段并不是通用的，也不需要进行输入控制，只需在写入时赋予指定值，那么你可以使用关键字入参即可
@@ -28,30 +62,8 @@ async def create_model(
     1. 在数据被最终写入前，所有入参（schema 和关键字参数）都会赋值给 SQLAlchemy 模型，即便你传入了非模型数据，
        这也是安全的，因为它不会被模型所引用
 
+**Returns:**
 
-
-## 示例
-
-```py title="create_model" hl_lines="21"
-from pydantic import BaseModel
-
-from sqlalchemy_crud_plus import CRUDPlus
-
-from sqlalchemy import DeclarativeBase as Base
-from sqlalchemy.ext.asyncio import AsyncSession
-
-
-class ModelIns(Base):
-    # your sqlalchemy model
-    pass
-
-
-class CreateIns(BaseModel):
-    # your pydantic schema
-    pass
-
-
-class CRUDIns(CRUDPlus[ModelIns]):
-    async def create(self, db: AsyncSession, obj: CreateIns) -> ModelIns:
-        return await self.create_model(db, obj)
-```
+| Type    | Description |
+|---------|-------------|
+| TypeVar | 模型实例        |