Add create and update kwargs usage (#30)

Author: wu-clan

.github/workflows/changelog.yml

@@ -14,18 +14,13 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0
           ref: ${{ github.event.release.target_commitish }}
 
-      - name: Extract release date from git tag
-        run: |
-          echo "date=$(git log -1 --date=short --format=%ad '${{ github.event.release.tag_name }}')" >> $GITHUB_OUTPUT;
-
       - name: Update Changelog
         uses: stefanzweifel/changelog-updater-action@v1
         with:
-          latest-version: ${{ github.event.release.tag_name }}
           release-notes: ${{ github.event.release.body }}
+          latest-version: ${{ github.event.release.tag_name }}
           path-to-changelog: docs/changelog.md
 
       - name: Commit updated CHANGELOG

README.md

@@ -12,6 +12,10 @@ pip install sqlalchemy-crud-plus
 
 [SQLAlchemy CRUD Plus](https://fastapi-practices.github.io/sqlalchemy-crud-plus)
 
+## 互动
+
+[TG / Discord](https://wu-clan.github.io/homepage/)
+
 ## 赞助
 
 如果此项目能够帮助到你，你可以赞助作者一些咖啡豆表示鼓励：[:coffee: Sponsor :coffee:](https://wu-clan.github.io/sponsor/)

docs/changelog.md

@@ -1,16 +1 @@
 # Change Logs
-
-## 1.4.0 - 2024-08-27
-
-### What's Changed
-
-* Add lint and test ci by @wu-clan in https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/24
-* Fix the cache for docs ci by @wu-clan in https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/25
-* Update model primary key for dynamic retrieval by @DavidSche in https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/23
-* Prepare for 1.4.0 release by @wu-clan in https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/26
-
-### New Contributors
-
-* @DavidSche made their first contribution in https://github.com/fastapi-practices/sqlalchemy-crud-plus/pull/23
-
-**Full Changelog**: https://github.com/fastapi-practices/sqlalchemy-crud-plus/compare/1.3.0...1.4.0

docs/usage/create_model.md

@@ -4,11 +4,13 @@ async def create_model(
     session: AsyncSession,
     obj: CreateSchema,
     commit: bool = False,
-    **kwargs
+    **kwargs,
 ) -> Model:
 ````
 
-!!! note "create_model <独特>的关键字参数"
+此方法提供 `commit` 参数，详见：[提交](../advanced/commit.md)
+
+!!! note "关键字参数"
 
     除了必须传入 obj schema 外，还可以通过关键字入参，传入非 schema
     参数，比如，对于某些特定场景，其中一个字段并不是通用的，也不需要进行输入控制，只需在写入时赋予指定值，那么你可以使用关键字入参即可

docs/usage/create_models.md

@@ -1,13 +1,16 @@
 ```python
 async def create_models(
-    self, 
-    session: AsyncSession, 
-    obj: Iterable[CreateSchema], 
-    commit: bool = False
+    self,
+    session: AsyncSession,
+    objs: Iterable[CreateSchema],
+    commit: bool = False,
+    **kwargs,
 ) -> list[Model]:
 ```
 
-此方法提供 `commit` 参数，详见：[提交](../advanced/commit.md)
+- 此方法提供 `commit` 参数，详见：[提交](../advanced/commit.md)
+
+- 此方法还提供与 `create_model()` 相同用法的关键字参数，需要额外注意的是，`create_models()` 会将关键字参数写入每个实例中
 
 ## 示例
 
@@ -33,8 +36,8 @@ class CreateIns(BaseModel):
 
 
 class CRUDIns(CRUDPlus[ModelIns]):
-    async def creates(self, db: AsyncSession, obj: Iterable[CreateIns]) -> list[ModelIns]:  # (1)
-        return await self.create_models(db, obj)
+    async def creates(self, db: AsyncSession, objs: Iterable[CreateIns]) -> list[ModelIns]:  # (1)
+        return await self.create_models(db, objs)
 ```
 
-1. obj 必须是一个 schema 列表
+1. objs 必须是一个 schema 列表

docs/usage/delete_model.md

@@ -1,9 +1,9 @@
 ```py
 async def delete_model(
     self,
-    session: AsyncSession, 
-    pk: int, 
-    commit: bool = False
+    session: AsyncSession,
+    pk: int,
+    commit: bool = False,
 ) -> int:
 ```
 

docs/usage/select.md

@@ -1,8 +1,6 @@
 ```py
-async def select(
-    self,
-    **kwargs
-) -> Select:
+async def select(self, **kwargs) -> Select:
+    ...
 ```
 
 此方法用于构造 SQLAlchemy

docs/usage/select_model.md

@@ -1,9 +1,5 @@
 ```py
-async def select_model(
-    self,
-    session: AsyncSession,
-    pk: int
-) -> Model | None:
+async def select_model(self, session: AsyncSession, pk: int) -> Model | None:
 ```
 
 此方法使用主键 pk 参数，详见：[主键](../advanced/primary_key.md)

docs/usage/select_model_by_column.md

@@ -1,9 +1,5 @@
 ```py
-async def select_model_by_column(
-    self,
-    session: AsyncSession, 
-    **kwargs
-) -> Model | None:
+async def select_model_by_column(self, session: AsyncSession, **kwargs) -> Model | None:
 ```
 
 此方法可结合 [高级过滤器](../advanced/filter.md) 使用

docs/usage/select_models.md

@@ -1,9 +1,5 @@
 ```py
-async def select_models(
-    self,
-    session: AsyncSession, 
-    **kwargs
-) -> Sequence[Row[Any] | RowMapping | Any]:
+async def select_models(self, session: AsyncSession, **kwargs) -> Sequence[Row[Any] | RowMapping | Any]:
 ```
 
 此方法可结合 [高级过滤器](../advanced/filter.md) 使用

docs/usage/select_models_order.md

@@ -1,10 +1,10 @@
 ```py
-async def select_models_order(
-    self,
-    session: AsyncSession,
-    sort_columns: str | list[str],
-    sort_orders: str | list[str] | None = None,
-    **kwargs
+ async def select_models_order(
+     self,
+     session: AsyncSession,
+     sort_columns: str | list[str],
+     sort_orders: str | list[str] | None = None,
+     **kwargs,
 ) -> Sequence[Row | RowMapping | Any] | None:
 ```
 

docs/usage/update_model.md

@@ -1,17 +1,20 @@
 ```py
 async def update_model(
-    self, 
+    self,
     session: AsyncSession,
     pk: int,
     obj: UpdateSchema | dict[str, Any],
-    commit: bool = False
+    commit: bool = False,
+    **kwargs,
 ) -> int:
 ```
 
 - 此方法使用主键 pk 参数，详见：[主键](../advanced/primary_key.md)
 
 - 此方法提供 `commit` 参数，详见：[提交](../advanced/commit.md)
 
+- 此方法还提供与 `create_model()` 相同用法的关键字参数
+
 ## 示例
 
 ```py title="update_model" hl_lines="23"

mkdocs.yml

@@ -9,58 +9,61 @@ nav:
   - Home: index.md
   - Installing: installing.md
   - Usage:
-      - 新增: usage/create_model.md
-      - 新增 - 多条: usage/create_models.md
-      - 查询 - 主键 ID: usage/select_model.md
-      - 查询 - 条件过滤: usage/select_model_by_column.md
-      - Select: usage/select.md
-      - Select - 排序: usage/select_order.md
-      - 查询 - 列表: usage/select_models.md
-      - 查询 - 列表排序: usage/select_models_order.md
-      - 更新 - 主键 ID: usage/update_model.md
-      - 更新 - 条件过滤: usage/update_model_by_column.md
-      - 删除 - 主键 ID: usage/delete_model.md
-      - 删除 - 条件过滤: usage/delete_model_by_column.md
+      - 新增:
+          - 单条: usage/create_model.md
+          - 多条: usage/create_models.md
+      - 查询:
+          - 主键 ID: usage/select_model.md
+          - 条件过滤: usage/select_model_by_column.md
+          - Select: usage/select.md
+          - Select 排序: usage/select_order.md
+          - 列表: usage/select_models.md
+          - 列表排序: usage/select_models_order.md
+      - 更新:
+          - 主键 ID: usage/update_model.md
+          - 高级用法: usage/update_model_by_column.md
+      - 删除:
+          - 主键 ID: usage/delete_model.md
+          - 高级用法: usage/delete_model_by_column.md
   - Advanced:
       - 主键: advanced/primary_key.md
       - 提交: advanced/commit.md
-      - 条件过滤:  advanced/filter.md
+      - 条件过滤: advanced/filter.md
   - Changelog: changelog.md
 theme:
   name: material
   font:
     code: Roboto Mono
   palette:
-    - media: "(prefers-color-scheme)"
-      primary: green
+    - media: '(prefers-color-scheme)'
       toggle:
         icon: material/brightness-auto
         name: Switch to light mode
-    - media: "(prefers-color-scheme: light)"
+    - media: '(prefers-color-scheme: light)'
       scheme: default
       primary: pink
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
+    - media: '(prefers-color-scheme: dark)'
       scheme: slate
-      primary: green
+      primary: teal
       toggle:
         icon: material/brightness-4
-        name: Switch to auto mode
+        name: Switch to system preference
   features:
     - content.code.annotate
     - content.code.select
     - navigation.instant
     - navigation.instant.progress
+    - navigation.path
     - navigation.tracking
     - navigation.tabs
     - navigation.tabs.sticky
-    - search.suggest
-    - toc.follow
-    - toc.integrate
     - navigation.top
     - navigation.footer
+    - search.suggest
+    - toc.follow
 plugins:
   - search
 markdown_extensions:

sqlalchemy_crud_plus/crud.py

@@ -54,20 +54,26 @@ async def create_model(
     async def create_models(
         self,
         session: AsyncSession,
-        obj: Iterable[CreateSchema],
+        objs: Iterable[CreateSchema],
         commit: bool = False,
+        **kwargs,
     ) -> list[Model]:
         """
         Create new instances of a model
 
         :param session: The SQLAlchemy async session.
-        :param obj: The Pydantic schema list containing data to be saved.
+        :param objs: The Pydantic schema list containing data to be saved.
         :param commit: If `True`, commits the transaction immediately. Default is `False`.
+        :param kwargs: Additional model data not included in the pydantic schema.
         :return:
         """
         ins_list = []
-        for ins in obj:
-            ins_list.append(self.model(**ins.model_dump()))
+        for obj in objs:
+            if not kwargs:
+                ins = self.model(**obj.model_dump())
+            else:
+                ins = self.model(**obj.model_dump(), **kwargs)
+            ins_list.append(ins)
         session.add_all(ins_list)
         if commit:
             await session.commit()
@@ -164,6 +170,7 @@ async def update_model(
         pk: int,
         obj: UpdateSchema | dict[str, Any],
         commit: bool = False,
+        **kwargs,
     ) -> int:
         """
         Update an instance by model's primary key
@@ -178,6 +185,8 @@ async def update_model(
             instance_data = obj
         else:
             instance_data = obj.model_dump(exclude_unset=True)
+        if kwargs:
+            instance_data.update(kwargs)
         stmt = update(self.model).where(self.primary_key == pk).values(**instance_data)
         result = await session.execute(stmt)
         if commit: