Add deleted time column for logical deletion (#60)

* Add deleted time column for logical deletion

* Update testcases

Author: wu-clan

docs/getting-started/quick-start.md

@@ -64,17 +64,17 @@ class Post(Base):
 
 ```python
 from pydantic import BaseModel
-from typing import Optional
+
 
 class UserCreate(BaseModel):
     name: str
     email: str
     is_active: bool = True
 
 class UserUpdate(BaseModel):
-    name: Optional[str] = None
-    email: Optional[str] = None
-    is_active: Optional[bool] = None
+    name: str | None = None
+    email: str | None = None
+    is_active: str | None = None
 
 class PostCreate(BaseModel):
     title: str

docs/usage/crud.md

@@ -199,6 +199,14 @@ deleted_count = await user_crud.delete_model_by_column(
     allow_multiple=True,
     created_at__lt=datetime.now() - timedelta(days=30)
 )
+
+# 逻辑删除（软删除）
+deleted_count = await user_crud.delete_model_by_column(
+    session,
+    logical_deletion=True,  # 启用逻辑删除
+    allow_multiple=False,
+    id=1
+)
 ```
 
 ## 事务控制

sqlalchemy_crud_plus/crud.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-from __future__ import annotations
-
+from datetime import datetime, timezone
 from typing import Any, Generic, Sequence
 
 from sqlalchemy import (
@@ -36,6 +35,7 @@
 class CRUDPlus(Generic[Model]):
     def __init__(self, model: type[Model]):
         self.model = model
+        self.model_column_names = [column.key for column in model.__table__.columns]
         self.primary_key = self._get_primary_key()
 
     def _get_primary_key(self) -> Column | list[Column]:
@@ -602,7 +602,9 @@ async def delete_model_by_column(
         session: AsyncSession,
         allow_multiple: bool = False,
         logical_deletion: bool = False,
-        deleted_flag_column: str = 'del_flag',
+        deleted_flag_column: str = 'is_deleted',
+        deleted_at_column: str = 'deleted_at',
+        deleted_at_factory: datetime = datetime.now(timezone.utc),
         flush: bool = False,
         commit: bool = False,
         **kwargs,
@@ -614,13 +616,15 @@ async def delete_model_by_column(
         :param allow_multiple: If `True`, allows deleting multiple records that match the filters
         :param logical_deletion: If `True`, enable logical deletion instead of physical deletion
         :param deleted_flag_column: Column name for logical deletion flag
+        :param deleted_at_column: Column name for delete time，automatic judgment
+        :param deleted_at_factory: The delete time column datetime factory function
         :param flush: If `True`, flush all object changes to the database
         :param commit: If `True`, commits the transaction immediately
         :param kwargs: Filter expressions using field__operator=value syntax
         :return:
         """
         if logical_deletion:
-            if not hasattr(self.model, deleted_flag_column):
+            if deleted_flag_column not in self.model_column_names:
                 raise ModelColumnError(f'Column {deleted_flag_column} is not found in {self.model}')
 
         filters = parse_filters(self.model, **kwargs)
@@ -633,8 +637,13 @@ 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}
+
+        if deleted_at_column in self.model_column_names:
+            data[deleted_at_column] = deleted_at_factory
+
         stmt = (
-            update(self.model).where(*filters).values(**{deleted_flag_column: True})
+            update(self.model).where(*filters).values(**data)
             if logical_deletion
             else delete(self.model).where(*filters)
         )

tests/conftest.py

@@ -11,7 +11,7 @@
 from sqlalchemy_crud_plus import CRUDPlus
 from tests.models.basic import Base, Ins, InsPks
 from tests.models.relations import RelationBase, RelCategory, RelPost, RelProfile, RelRole, RelUser, user_role
-from tests.schemas.relations import RelPostCreate, RelProfileCreate, RelRoleCreate, RelUserCreate
+from tests.schemas.relations import CreateRelPost, CreateRelProfile, CreateRelRole, CreateRelUser
 
 _async_engine = create_async_engine('sqlite+aiosqlite:///:memory:', future=True, echo=False)
 _async_db_session = async_sessionmaker(_async_engine, autoflush=False, expire_on_commit=False)
@@ -45,16 +45,16 @@ async def async_db_session() -> AsyncGenerator[AsyncSession, None]:
 
 
 @pytest_asyncio.fixture
-async def populated_db(async_db_session: AsyncSession, crud_ins: CRUDPlus[Ins]) -> list[Ins]:
+async def sample_ins(async_db_session: AsyncSession, crud_ins: CRUDPlus[Ins]) -> list[Ins]:
     """Provide a database populated with test data."""
     async with async_db_session.begin():
-        test_data = [Ins(name=f'item_{i}', del_flag=(i % 2 == 0)) for i in range(1, 11)]
+        test_data = [Ins(name=f'item_{i}', is_deleted=(i % 2 == 0)) for i in range(1, 11)]
         async_db_session.add_all(test_data)
         return test_data
 
 
 @pytest_asyncio.fixture
-async def populated_db_pks(async_db_session: AsyncSession) -> dict[str, list[InsPks]]:
+async def sample_ins_pks(async_db_session: AsyncSession) -> dict[str, list[InsPks]]:
     """Provide a database populated with composite key test data."""
     async with async_db_session.begin():
         men_data = [InsPks(id=i, name=f'man_{i}', sex='men') for i in range(1, 4)]
@@ -103,7 +103,7 @@ async def rel_sample_users(async_db_session: AsyncSession) -> list[RelUser]:
     async with async_db_session.begin():
         users = []
         for i in range(1, 4):
-            user_data = RelUserCreate(name=f'user_{i}')
+            user_data = CreateRelUser(name=f'user_{i}')
             user = RelUser(**user_data.model_dump())
             async_db_session.add(user)
             users.append(user)
@@ -116,7 +116,7 @@ async def rel_sample_profiles(async_db_session: AsyncSession, rel_sample_users:
     async with async_db_session.begin():
         profiles = []
         for i, user in enumerate(rel_sample_users[:2]):
-            profile_data = RelProfileCreate(bio=f'Bio for {user.name}')
+            profile_data = CreateRelProfile(bio=f'Bio for {user.name}')
             profile = RelProfile(user_id=user.id, **profile_data.model_dump())
             async_db_session.add(profile)
             profiles.append(profile)
@@ -147,7 +147,7 @@ async def rel_sample_posts(
     async with async_db_session.begin():
         posts = []
         for i in range(6):
-            post_data = RelPostCreate(
+            post_data = CreateRelPost(
                 title=f'Post {i + 1}',
                 category_id=rel_sample_categories[i % len(rel_sample_categories)].id if i < 4 else None,
             )
@@ -163,7 +163,7 @@ async def rel_sample_roles(async_db_session: AsyncSession) -> list[RelRole]:
     async with async_db_session.begin():
         roles = []
         for role_name in ['admin', 'editor']:
-            role_data = RelRoleCreate(name=role_name)
+            role_data = CreateRelRole(name=role_name)
             role = RelRole(**role_data.model_dump())
             async_db_session.add(role)
             roles.append(role)

tests/models/basic.py

@@ -17,7 +17,7 @@ class Ins(Base):
 
     id: Mapped[int] = mapped_column(init=False, primary_key=True, index=True, autoincrement=True)
     name: Mapped[str] = mapped_column(String(64))
-    del_flag: Mapped[bool] = mapped_column(default=False)
+    is_deleted: Mapped[bool] = mapped_column(default=False)
     created_time: Mapped[datetime] = mapped_column(init=False, default_factory=datetime.now)
     updated_time: Mapped[datetime | None] = mapped_column(init=False, onupdate=datetime.now)
 
@@ -28,6 +28,6 @@ class InsPks(Base):
     id: Mapped[int] = mapped_column(primary_key=True, index=True)
     name: Mapped[str] = mapped_column(String(64))
     sex: Mapped[str] = mapped_column(String(16), primary_key=True, index=True)
-    del_flag: Mapped[bool] = mapped_column(default=False)
+    is_deleted: Mapped[bool] = mapped_column(default=False)
     created_time: Mapped[datetime] = mapped_column(init=False, default_factory=datetime.now)
     updated_time: Mapped[datetime | None] = mapped_column(init=False, onupdate=datetime.now)

tests/schemas/basic.py

@@ -1,25 +1,23 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-from typing import Optional
-
 from pydantic import BaseModel
 
 
-class InsCreate(BaseModel):
+class CreateIns(BaseModel):
     name: str
-    del_flag: bool = False
+    is_deleted: bool = False
 
 
-class InsUpdate(BaseModel):
-    name: Optional[str] = None
-    del_flag: Optional[bool] = None
+class UpdateIns(BaseModel):
+    name: str | None = None
+    is_deleted: bool | None = None
 
 
-class InsPksCreate(BaseModel):
+class CreateInsPks(BaseModel):
     id: int
     name: str
     sex: str
 
 
-class InsPksUpdate(BaseModel):
-    name: Optional[str] = None
+class UpdateInsPks(BaseModel):
+    name: str | None = None

tests/schemas/relations.py

@@ -3,74 +3,74 @@
 from pydantic import BaseModel, ConfigDict
 
 
-class RelUserCreate(BaseModel):
+class CreateRelUser(BaseModel):
     name: str
 
 
-class RelProfileCreate(BaseModel):
+class CreateRelProfile(BaseModel):
     bio: str
 
 
-class RelCategoryCreate(BaseModel):
+class CreateRelCategory(BaseModel):
     name: str
     parent_id: int | None = None
 
 
-class RelPostCreate(BaseModel):
+class CreateRelPost(BaseModel):
     title: str
     category_id: int | None = None
 
 
-class RelRoleCreate(BaseModel):
+class CreateRelRole(BaseModel):
     name: str
 
 
-class RelUserUpdate(BaseModel):
+class UpdateRelUser(BaseModel):
     name: str | None = None
 
 
-class RelProfileUpdate(BaseModel):
+class UpdateRelProfile(BaseModel):
     bio: str | None = None
 
 
-class RelCategoryUpdate(BaseModel):
+class UpdateRelCategory(BaseModel):
     name: str | None = None
     parent_id: int | None = None
 
 
-class RelPostUpdate(BaseModel):
+class UpdateRelPost(BaseModel):
     title: str | None = None
     category_id: int | None = None
 
 
-class RelRoleUpdate(BaseModel):
+class UpdateRelRole(BaseModel):
     name: str | None = None
 
 
-class RelUserResponse(BaseModel):
+class RelUserDetail(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
     name: str
 
 
-class RelProfileResponse(BaseModel):
+class RelProfileDetail(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
     user_id: int
     bio: str
 
 
-class RelCategoryResponse(BaseModel):
+class RelCategoryDetail(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
     name: str
     parent_id: int | None
 
 
-class RelPostResponse(BaseModel):
+class RelPostDetail(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
@@ -79,7 +79,7 @@ class RelPostResponse(BaseModel):
     category_id: int | None
 
 
-class RelRoleResponse(BaseModel):
+class RelRoleDetail(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int

tests/test_composite_keys.py

@@ -7,12 +7,12 @@
 from sqlalchemy_crud_plus import CRUDPlus
 from sqlalchemy_crud_plus.errors import CompositePrimaryKeysError
 from tests.models.basic import InsPks
-from tests.schemas.basic import InsPksCreate, InsPksUpdate
+from tests.schemas.basic import CreateInsPks, UpdateInsPks
 
 
 @pytest.mark.asyncio
 async def test_composite_key_create_model(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
-    data = InsPksCreate(id=100, name='test_user', sex='test')
+    data = CreateInsPks(id=100, name='test_user', sex='test')
     result = await crud_ins_pks.create_model(async_db_session, data, commit=True)
 
     assert result.id == 100
@@ -22,7 +22,7 @@ async def test_composite_key_create_model(async_db_session: AsyncSession, crud_i
 
 @pytest.mark.asyncio
 async def test_composite_key_select_model(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
-    data = InsPksCreate(id=101, name='select_test', sex='test')
+    data = CreateInsPks(id=101, name='select_test', sex='test')
     await crud_ins_pks.create_model(async_db_session, data, commit=True)
 
     result = await crud_ins_pks.select_model(async_db_session, (101, 'test'))
@@ -35,19 +35,19 @@ async def test_composite_key_select_model(async_db_session: AsyncSession, crud_i
 
 @pytest.mark.asyncio
 async def test_composite_key_update_model(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
-    data = InsPksCreate(id=102, name='update_test', sex='test')
+    data = CreateInsPks(id=102, name='update_test', sex='test')
     await crud_ins_pks.create_model(async_db_session, data, commit=True)
 
     updated_count = await crud_ins_pks.update_model(
-        async_db_session, (102, 'test'), InsPksUpdate(name='updated_name'), commit=True
+        async_db_session, (102, 'test'), UpdateInsPks(name='updated_name'), commit=True
     )
 
     assert updated_count == 1
 
 
 @pytest.mark.asyncio
 async def test_composite_key_delete_model(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
-    data = InsPksCreate(id=103, name='delete_test', sex='test')
+    data = CreateInsPks(id=103, name='delete_test', sex='test')
     await crud_ins_pks.create_model(async_db_session, data, commit=True)
 
     deleted_count = await crud_ins_pks.delete_model(async_db_session, (103, 'test'), commit=True)
@@ -57,7 +57,7 @@ async def test_composite_key_delete_model(async_db_session: AsyncSession, crud_i
 
 @pytest.mark.asyncio
 async def test_composite_key_create_models(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
-    data = [InsPksCreate(id=200, name='batch_1', sex='test1'), InsPksCreate(id=201, name='batch_2', sex='test2')]
+    data = [CreateInsPks(id=200, name='batch_1', sex='test1'), CreateInsPks(id=201, name='batch_2', sex='test2')]
 
     results = await crud_ins_pks.create_models(async_db_session, data, commit=True)
 
@@ -69,9 +69,9 @@ async def test_composite_key_create_models(async_db_session: AsyncSession, crud_
 @pytest.mark.asyncio
 async def test_composite_key_count(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
     data = [
-        InsPksCreate(id=300, name='count_1', sex='count_test'),
-        InsPksCreate(id=301, name='count_2', sex='count_test'),
-        InsPksCreate(id=302, name='count_3', sex='count_test'),
+        CreateInsPks(id=300, name='count_1', sex='count_test'),
+        CreateInsPks(id=301, name='count_2', sex='count_test'),
+        CreateInsPks(id=302, name='count_3', sex='count_test'),
     ]
     await crud_ins_pks.create_models(async_db_session, data, commit=True)
 
@@ -82,7 +82,7 @@ async def test_composite_key_count(async_db_session: AsyncSession, crud_ins_pks:
 
 @pytest.mark.asyncio
 async def test_composite_key_exists(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
-    data = InsPksCreate(id=400, name='exists_test', sex='exists')
+    data = CreateInsPks(id=400, name='exists_test', sex='exists')
     await crud_ins_pks.create_model(async_db_session, data, commit=True)
 
     exists = await crud_ins_pks.exists(async_db_session, id=400, sex='exists')
@@ -93,8 +93,8 @@ async def test_composite_key_exists(async_db_session: AsyncSession, crud_ins_pks
 @pytest.mark.asyncio
 async def test_composite_key_select_models(async_db_session: AsyncSession, crud_ins_pks: CRUDPlus[InsPks]):
     data = [
-        InsPksCreate(id=500, name='select_1', sex='select_test'),
-        InsPksCreate(id=501, name='select_2', sex='select_test'),
+        CreateInsPks(id=500, name='select_1', sex='select_test'),
+        CreateInsPks(id=501, name='select_2', sex='select_test'),
     ]
     await crud_ins_pks.create_models(async_db_session, data, commit=True)