Add base code files (#1)

* Add the base code

* Add test code

* Update README.md

Author: wu-clan

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pdm-python
+.pdm-build/
+.venv
+venv/
+.idea/
+dist/

.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.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.4.0
+    hooks:
+      - id: ruff
+        args:
+          - '--fix'
+      - id: ruff-format
+
+  - repo: https://github.com/pdm-project/pdm
+    rev: 2.12.2
+    hooks:
+      - id: pdm-export
+        args:
+          - -o
+          - 'requirements.txt'
+          - '--without-hashes'
+        files: ^pdm.lock$
+      - id: pdm-lock-check

README.md

@@ -0,0 +1,46 @@
+# sqlalchemy-crud-plus
+
+基于 SQLAlChemy2 模型的异步 CRUD 操作
+
+## 下载
+
+```shell
+pip install sqlalchemy-crud-plus
+```
+
+## TODO
+
+- [ ] ...
+
+## Use
+
+以下仅为简易示例
+
+```python
+from sqlalchemy.orm import declarative_base
+from sqlalchemy_crud_plus import CRUDPlus
+
+Base = declarative_base()
+
+
+class ModelIns(Base):
+    # your sqlalchemy model
+    pass
+
+
+class CRUDIns(CRUDPlus[ModelIns]):
+    # your controller service
+    pass
+
+
+# singleton
+ins_dao = CRUDIns(ModelIns)
+```
+
+## 互动
+
+[WeChat / QQ](https://github.com/wu-clan)
+
+## 赞助
+
+如果此项目能够帮助到你，你可以赞助作者一些咖啡豆表示鼓励：[:coffee: Sponsor :coffee:](https://wu-clan.github.io/sponsor/)

pdm.lock

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+pre-commit run --all-files --verbose --show-diff-on-failure

pre-commit.sh

@@ -0,0 +1,60 @@
+[project]
+name = "sqlalchemy-crud-plus"
+description = "Asynchronous CRUD Operation based on SQLAlChemy2 Model"
+dynamic = [
+    "version",
+]
+authors = [
+    { name = "Wu Clan", email = "jianhengwu0407@gmail.com" },
+]
+dependencies = [
+    "sqlalchemy>=2.0.0",
+    "pydantic>=2.0",
+]
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT" }
+
+[tool.pdm.dev-dependencies]
+lint = [
+    "ruff>=0.4.0",
+    "pre-commit>=3.5.0",
+]
+test = [
+    "pytest>=8.1.1",
+    "aiosqlite>=0.20.0",
+    "pytest-asyncio>=0.23.6",
+]
+
+[tool.ruff]
+line-length = 120
+unsafe-fixes = true
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I"
+]
+preview = true
+ignore-init-module-imports = true
+
+[tool.ruff.lint.isort]
+lines-between-types = 1
+order-by-type = true
+
+[tool.ruff.format]
+quote-style = "single"
+docstring-code-format = true
+
+[tool.pdm]
+distribution = true
+version = { source = "file", path = "sqlalchemy_crud_plus/__init__.py" }
+
+[tool.pdm.scripts]
+lint = "pre-commit run --all-files"
+
+[build-system]
+requires = ["pdm-backend"]
+build-backend = "pdm.backend"

pyproject.toml

@@ -0,0 +1,29 @@
+# This file is @generated by PDM.
+# Please do not edit it manually.
+
+aiosqlite==0.20.0
+annotated-types==0.6.0
+cfgv==3.4.0
+colorama==0.4.6; sys_platform == "win32"
+distlib==0.3.8
+exceptiongroup==1.2.1; python_version < "3.11"
+filelock==3.13.4
+greenlet==3.0.3; platform_machine == "win32" or platform_machine == "WIN32" or platform_machine == "AMD64" or platform_machine == "amd64" or platform_machine == "x86_64" or platform_machine == "ppc64le" or platform_machine == "aarch64"
+identify==2.5.35
+iniconfig==2.0.0
+nodeenv==1.8.0
+packaging==24.0
+platformdirs==4.2.0
+pluggy==1.5.0
+pre-commit==3.5.0
+pydantic==2.7.0
+pydantic-core==2.18.1
+pytest==8.1.1
+pytest-asyncio==0.23.6
+pyyaml==6.0.1
+ruff==0.4.0
+setuptools==69.5.1
+sqlalchemy==2.0.29
+tomli==2.0.1; python_version < "3.11"
+typing-extensions==4.10.0
+virtualenv==20.25.3

requirements.txt

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+from .crud import CRUDPlus as CRUDPlus
+from .errors import ModelColumnError as ModelColumnError
+
+__version__ = 'v0.0.1'

sqlalchemy_crud_plus/__init__.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+from typing import Any, Generic, Sequence, Type, TypeVar
+
+from pydantic import BaseModel
+from sqlalchemy import Row, RowMapping, select
+from sqlalchemy import delete as sa_delete
+from sqlalchemy import update as sa_update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sqlalchemy_crud_plus.errors import ModelColumnError
+
+_Model = TypeVar('_Model')
+_CreateSchema = TypeVar('_CreateSchema', bound=BaseModel)
+_UpdateSchema = TypeVar('_UpdateSchema', bound=BaseModel)
+
+
+class CRUDPlus(Generic[_Model]):
+    def __init__(self, model: Type[_Model]):
+        self.model = model
+
+    async def create_model(self, session: AsyncSession, obj: _CreateSchema, **kwargs) -> None:
+        """
+        Create a new instance of a model
+
+        :param session:
+        :param obj:
+        :param kwargs:
+        :return:
+        """
+        if kwargs:
+            instance = self.model(**obj.model_dump(), **kwargs)
+        else:
+            instance = self.model(**obj.model_dump())
+        session.add(instance)
+
+    async def select_model_by_id(self, session: AsyncSession, pk: int) -> _Model | None:
+        """
+        Query by ID
+
+        :param session:
+        :param pk:
+        :return:
+        """
+        query = await session.execute(select(self.model).where(self.model.id == pk))
+        return query.scalars().first()
+
+    async def select_model_by_column(self, session: AsyncSession, column: str, column_value: Any) -> _Model | None:
+        """
+        Query by column
+
+        :param session:
+        :param column:
+        :param column_value:
+        :return:
+        """
+        if hasattr(self.model, column):
+            model_column = getattr(self.model, column)
+            query = await session.execute(select(self.model).where(model_column == column_value))  # type: ignore
+            return query.scalars().first()
+        else:
+            raise ModelColumnError('Model column not found')
+
+    async def select_models(self, session: AsyncSession) -> Sequence[Row | RowMapping | Any] | None:
+        """
+        Query all rows
+
+        :param session:
+        :return:
+        """
+        query = await session.execute(select(self.model))
+        return query.scalars().all()
+
+    async def update_model(self, session: AsyncSession, pk: int, obj: _UpdateSchema | dict[str, Any], **kwargs) -> int:
+        """
+        Update an instance of a model
+
+        :param session:
+        :param pk:
+        :param obj:
+        :param kwargs:
+        :return:
+        """
+        if isinstance(obj, dict):
+            instance_data = obj
+        else:
+            instance_data = obj.model_dump(exclude_unset=True)
+        if kwargs:
+            instance_data.update(kwargs)
+        result = await session.execute(sa_update(self.model).where(self.model.id == pk).values(**instance_data))
+        return result.rowcount  # type: ignore
+
+    async def delete_model(self, session: AsyncSession, pk: int, **kwargs) -> int:
+        """
+        Delete an instance of a model
+
+        :param session:
+        :param pk:
+        :param kwargs:
+        :return:
+        """
+        if not kwargs:
+            result = await session.execute(sa_delete(self.model).where(self.model.id == pk))
+        else:
+            result = await session.execute(sa_update(self.model).where(self.model.id == pk).values(**kwargs))
+        return result.rowcount  # type: ignore

sqlalchemy_crud_plus/crud.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+
+class SQLAlchemyCRUDPlusException(Exception):
+    def __init__(self, msg: str) -> None:
+        self.msg = msg
+
+    def __str__(self) -> str:
+        return self.msg
+
+
+class ModelColumnError(SQLAlchemyCRUDPlusException):
+    """Error raised when an SCP column is invalid."""
+
+    def __init__(self, msg: str) -> None:
+        super().__init__(msg)