dclassql 0.1.6__tar.gz → 0.2.0__tar.gz

{dclassql-0.1.6 → dclassql-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dclassql
-Version: 0.1.6
+Version: 0.2.0
 Summary: A type-safe ORM generator for Python, creating fully type-hinted database clients from plain dataclass definitions.
 Keywords: orm,codegen,sqlite,dataclass,typed
 Author: myuanz

{dclassql-0.1.6 → dclassql-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dclassql"
-version = "0.1.6"
+version = "0.2.0"
 description = "A type-safe ORM generator for Python, creating fully type-hinted database clients from plain dataclass definitions."
 readme = "README.md"
 authors = [

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/__init__.py

@@ -1,10 +1,12 @@
-from .model_inspector import DataSourceConfig
+from .asdict import asdict
 from .db_pool import BaseDBPool, save_local
+from .model_inspector import DataSourceConfig
 from .push import db_push
 from .runtime.backends.lazy import eager
-from .asdict import asdict
+from .runtime.sql_recorder import record_sql
 from .unwarp import unwarp, unwarp_or, unwarp_or_raise
 
+
 class _MissingClient:
     def __init__(self, *args: object, **kwargs: object) -> None:
         raise RuntimeError(
@@ -28,4 +30,5 @@ __all__ = [
     'BaseDBPool',
     'save_local',
     'DataSourceConfig',
+    'record_sql',
 ]

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/client.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Literal, Mapping, Sequence, NotRequired
+from typing import Any, Literal, Mapping, Sequence, NotRequired, overload
 from typing_extensions import TypedDict
 
 from dclassql import DataSourceConfig
@@ -55,6 +55,7 @@ class StringFilter(TypedDict, total=False, closed=True):
 
 TAddressIncludeCol = Literal['user']
 TAddressSortableCol = Literal['id', 'location', 'user_id']
+TAddressDistinctCol = Literal['id', 'location', 'user_id']
 
 @dataclass(slots=True, kw_only=True)
 class AddressInsert:
@@ -168,21 +169,32 @@ class AddressTable(TableProtocol):
     def insert_many(self, data: Sequence[AddressInsert | AddressInsertDict], *, batch_size: int | None = None) -> list[Address]:
         return self._backend.insert_many(self, data, batch_size=batch_size)
 
-    def find_many(self, *, where: AddressWhereDict | None = None, include: AddressIncludeDict | None = None, order_by: AddressOrderByDict | None = None, take: int | None = None, skip: int | None = None) -> list[Address]:
+    def find_many(self, *, where: AddressWhereDict | None = None, include: AddressIncludeDict | None = None, order_by: AddressOrderByDict | None = None, distinct: TAddressDistinctCol | Sequence[TAddressDistinctCol] | None = None, take: int | None = None, skip: int | None = None) -> list[Address]:
         return self._backend.find_many(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             take=take, skip=skip
         )
 
-    def find_first(self, *, where: AddressWhereDict | None = None, include: AddressIncludeDict | None = None, order_by: AddressOrderByDict | None = None, skip: int | None = None) -> Address | None:
+    def find_first(self, *, where: AddressWhereDict | None = None, include: AddressIncludeDict | None = None, order_by: AddressOrderByDict | None = None, distinct: TAddressDistinctCol | Sequence[TAddressDistinctCol] | None = None, skip: int | None = None) -> Address | None:
         return self._backend.find_first(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             skip=skip
         )
+
+    def delete(self, *, where: AddressWhereDict, include: AddressIncludeDict | None = None) -> Address | None:
+        return self._backend.delete(self, where=where, include=include)
+
+    @overload
+    def delete_many(self, *, where: AddressWhereDict | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def delete_many(self, *, where: AddressWhereDict | None = None, return_records: Literal[True]) -> list[Address]: ...
+    def delete_many(self, *, where: AddressWhereDict | None = None, return_records: Literal[False, True] = False) -> int | list[Address]:
+        return self._backend.delete_many(self, where=where, return_records=return_records)
 TBirthDayIncludeCol = Literal['user']
 TBirthDaySortableCol = Literal['user_id', 'date']
+TBirthDayDistinctCol = Literal['user_id', 'date']
 
 @dataclass(slots=True, kw_only=True)
 class BirthDayInsert:
@@ -286,21 +298,32 @@ class BirthDayTable(TableProtocol):
     def insert_many(self, data: Sequence[BirthDayInsert | BirthDayInsertDict], *, batch_size: int | None = None) -> list[BirthDay]:
         return self._backend.insert_many(self, data, batch_size=batch_size)
 
-    def find_many(self, *, where: BirthDayWhereDict | None = None, include: BirthDayIncludeDict | None = None, order_by: BirthDayOrderByDict | None = None, take: int | None = None, skip: int | None = None) -> list[BirthDay]:
+    def find_many(self, *, where: BirthDayWhereDict | None = None, include: BirthDayIncludeDict | None = None, order_by: BirthDayOrderByDict | None = None, distinct: TBirthDayDistinctCol | Sequence[TBirthDayDistinctCol] | None = None, take: int | None = None, skip: int | None = None) -> list[BirthDay]:
         return self._backend.find_many(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             take=take, skip=skip
         )
 
-    def find_first(self, *, where: BirthDayWhereDict | None = None, include: BirthDayIncludeDict | None = None, order_by: BirthDayOrderByDict | None = None, skip: int | None = None) -> BirthDay | None:
+    def find_first(self, *, where: BirthDayWhereDict | None = None, include: BirthDayIncludeDict | None = None, order_by: BirthDayOrderByDict | None = None, distinct: TBirthDayDistinctCol | Sequence[TBirthDayDistinctCol] | None = None, skip: int | None = None) -> BirthDay | None:
         return self._backend.find_first(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             skip=skip
         )
+
+    def delete(self, *, where: BirthDayWhereDict, include: BirthDayIncludeDict | None = None) -> BirthDay | None:
+        return self._backend.delete(self, where=where, include=include)
+
+    @overload
+    def delete_many(self, *, where: BirthDayWhereDict | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def delete_many(self, *, where: BirthDayWhereDict | None = None, return_records: Literal[True]) -> list[BirthDay]: ...
+    def delete_many(self, *, where: BirthDayWhereDict | None = None, return_records: Literal[False, True] = False) -> int | list[BirthDay]:
+        return self._backend.delete_many(self, where=where, return_records=return_records)
 TBookIncludeCol = Literal['users']
 TBookSortableCol = Literal['id', 'name']
+TBookDistinctCol = Literal['id', 'name']
 
 @dataclass(slots=True, kw_only=True)
 class BookInsert:
@@ -398,21 +421,32 @@ class BookTable(TableProtocol):
     def insert_many(self, data: Sequence[BookInsert | BookInsertDict], *, batch_size: int | None = None) -> list[Book]:
         return self._backend.insert_many(self, data, batch_size=batch_size)
 
-    def find_many(self, *, where: BookWhereDict | None = None, include: BookIncludeDict | None = None, order_by: BookOrderByDict | None = None, take: int | None = None, skip: int | None = None) -> list[Book]:
+    def find_many(self, *, where: BookWhereDict | None = None, include: BookIncludeDict | None = None, order_by: BookOrderByDict | None = None, distinct: TBookDistinctCol | Sequence[TBookDistinctCol] | None = None, take: int | None = None, skip: int | None = None) -> list[Book]:
         return self._backend.find_many(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             take=take, skip=skip
         )
 
-    def find_first(self, *, where: BookWhereDict | None = None, include: BookIncludeDict | None = None, order_by: BookOrderByDict | None = None, skip: int | None = None) -> Book | None:
+    def find_first(self, *, where: BookWhereDict | None = None, include: BookIncludeDict | None = None, order_by: BookOrderByDict | None = None, distinct: TBookDistinctCol | Sequence[TBookDistinctCol] | None = None, skip: int | None = None) -> Book | None:
         return self._backend.find_first(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             skip=skip
         )
+
+    def delete(self, *, where: BookWhereDict, include: BookIncludeDict | None = None) -> Book | None:
+        return self._backend.delete(self, where=where, include=include)
+
+    @overload
+    def delete_many(self, *, where: BookWhereDict | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def delete_many(self, *, where: BookWhereDict | None = None, return_records: Literal[True]) -> list[Book]: ...
+    def delete_many(self, *, where: BookWhereDict | None = None, return_records: Literal[False, True] = False) -> int | list[Book]:
+        return self._backend.delete_many(self, where=where, return_records=return_records)
 TUserIncludeCol = Literal['addresses', 'birthday', 'books']
 TUserSortableCol = Literal['id', 'name', 'email', 'last_login']
+TUserDistinctCol = Literal['id', 'name', 'email', 'last_login']
 
 @dataclass(slots=True, kw_only=True)
 class UserInsert:
@@ -551,21 +585,32 @@ class UserTable(TableProtocol):
     def insert_many(self, data: Sequence[UserInsert | UserInsertDict], *, batch_size: int | None = None) -> list[User]:
         return self._backend.insert_many(self, data, batch_size=batch_size)
 
-    def find_many(self, *, where: UserWhereDict | None = None, include: UserIncludeDict | None = None, order_by: UserOrderByDict | None = None, take: int | None = None, skip: int | None = None) -> list[User]:
+    def find_many(self, *, where: UserWhereDict | None = None, include: UserIncludeDict | None = None, order_by: UserOrderByDict | None = None, distinct: TUserDistinctCol | Sequence[TUserDistinctCol] | None = None, take: int | None = None, skip: int | None = None) -> list[User]:
         return self._backend.find_many(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             take=take, skip=skip
         )
 
-    def find_first(self, *, where: UserWhereDict | None = None, include: UserIncludeDict | None = None, order_by: UserOrderByDict | None = None, skip: int | None = None) -> User | None:
+    def find_first(self, *, where: UserWhereDict | None = None, include: UserIncludeDict | None = None, order_by: UserOrderByDict | None = None, distinct: TUserDistinctCol | Sequence[TUserDistinctCol] | None = None, skip: int | None = None) -> User | None:
         return self._backend.find_first(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             skip=skip
         )
+
+    def delete(self, *, where: UserWhereDict, include: UserIncludeDict | None = None) -> User | None:
+        return self._backend.delete(self, where=where, include=include)
+
+    @overload
+    def delete_many(self, *, where: UserWhereDict | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def delete_many(self, *, where: UserWhereDict | None = None, return_records: Literal[True]) -> list[User]: ...
+    def delete_many(self, *, where: UserWhereDict | None = None, return_records: Literal[False, True] = False) -> int | list[User]:
+        return self._backend.delete_many(self, where=where, return_records=return_records)
 TUserBookIncludeCol = Literal['book', 'user']
 TUserBookSortableCol = Literal['user_id', 'book_id', 'created_at']
+TUserBookDistinctCol = Literal['user_id', 'book_id', 'created_at']
 
 @dataclass(slots=True, kw_only=True)
 class UserBookInsert:
@@ -695,19 +740,29 @@ class UserBookTable(TableProtocol):
     def insert_many(self, data: Sequence[UserBookInsert | UserBookInsertDict], *, batch_size: int | None = None) -> list[UserBook]:
         return self._backend.insert_many(self, data, batch_size=batch_size)
 
-    def find_many(self, *, where: UserBookWhereDict | None = None, include: UserBookIncludeDict | None = None, order_by: UserBookOrderByDict | None = None, take: int | None = None, skip: int | None = None) -> list[UserBook]:
+    def find_many(self, *, where: UserBookWhereDict | None = None, include: UserBookIncludeDict | None = None, order_by: UserBookOrderByDict | None = None, distinct: TUserBookDistinctCol | Sequence[TUserBookDistinctCol] | None = None, take: int | None = None, skip: int | None = None) -> list[UserBook]:
         return self._backend.find_many(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             take=take, skip=skip
         )
 
-    def find_first(self, *, where: UserBookWhereDict | None = None, include: UserBookIncludeDict | None = None, order_by: UserBookOrderByDict | None = None, skip: int | None = None) -> UserBook | None:
+    def find_first(self, *, where: UserBookWhereDict | None = None, include: UserBookIncludeDict | None = None, order_by: UserBookOrderByDict | None = None, distinct: TUserBookDistinctCol | Sequence[TUserBookDistinctCol] | None = None, skip: int | None = None) -> UserBook | None:
         return self._backend.find_first(
             self, 
-            where=where, include=include, order_by=order_by, 
+            where=where, include=include, order_by=order_by, distinct=distinct,
             skip=skip
         )
+
+    def delete(self, *, where: UserBookWhereDict, include: UserBookIncludeDict | None = None) -> UserBook | None:
+        return self._backend.delete(self, where=where, include=include)
+
+    @overload
+    def delete_many(self, *, where: UserBookWhereDict | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def delete_many(self, *, where: UserBookWhereDict | None = None, return_records: Literal[True]) -> list[UserBook]: ...
+    def delete_many(self, *, where: UserBookWhereDict | None = None, return_records: Literal[False, True] = False) -> int | list[UserBook]:
+        return self._backend.delete_many(self, where=where, return_records=return_records)
 class Client(BaseDBPool):
     _echo_sql: bool = False
     datasources = {
@@ -749,6 +804,7 @@ __all__ = (
     "Client",
     "TAddressIncludeCol",
     "TAddressSortableCol",
+    "TAddressDistinctCol",
     "AddressIncludeDict",
     "AddressOrderByDict",
     "AddressDict",
@@ -759,6 +815,7 @@ __all__ = (
     "AddressUserRelationFilter",
     "TBirthDayIncludeCol",
     "TBirthDaySortableCol",
+    "TBirthDayDistinctCol",
     "BirthDayIncludeDict",
     "BirthDayOrderByDict",
     "BirthDayDict",
@@ -769,6 +826,7 @@ __all__ = (
     "BirthDayUserRelationFilter",
     "TBookIncludeCol",
     "TBookSortableCol",
+    "TBookDistinctCol",
     "BookIncludeDict",
     "BookOrderByDict",
     "BookDict",
@@ -779,6 +837,7 @@ __all__ = (
     "BookUsersRelationFilter",
     "TUserIncludeCol",
     "TUserSortableCol",
+    "TUserDistinctCol",
     "UserIncludeDict",
     "UserOrderByDict",
     "UserDict",
@@ -791,6 +850,7 @@ __all__ = (
     "UserBooksRelationFilter",
     "TUserBookIncludeCol",
     "TUserBookSortableCol",
+    "TUserBookDistinctCol",
     "UserBookIncludeDict",
     "UserBookOrderByDict",
     "UserBookDict",

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/codegen.py

@@ -100,6 +100,12 @@ class ScalarFilterRender:
     fields: tuple[TypedDictFieldSpec, ...]
 
 
+@dataclass(slots=True)
+class UpsertWhereRender:
+    name: str
+    fields: tuple[TypedDictFieldSpec, ...]
+
+
 @dataclass(slots=True)
 class ModelRenderContext:
     name: str
@@ -107,6 +113,8 @@ class ModelRenderContext:
     table_name_literal: str
     insert_fields: tuple[InsertFieldSpec, ...]
     typed_dict_fields: tuple[TypedDictFieldSpec, ...]
+    update_fields: tuple[TypedDictFieldSpec, ...]
+    upsert_where_dicts: tuple["UpsertWhereRender", ...]
     dict_fields: tuple[TypedDictFieldSpec, ...]
     where_fields: tuple[WhereFieldSpec, ...]
     relation_filters: tuple[RelationFilterRender, ...]
@@ -116,6 +124,7 @@ class ModelRenderContext:
     primary_key_literal: str
     indexes_literal: str
     unique_indexes_literal: str
+    primary_value_types: tuple[str, ...]
     row_assignments: tuple[RowAssignmentRender, ...]
     default_factories: tuple[DefaultFactoryRender, ...]
     model_info: ModelInfo
@@ -222,8 +231,11 @@ def _build_model_context(
 
     insert_fields: list[InsertFieldSpec] = []
     typed_dict_fields: list[TypedDictFieldSpec] = []
+    update_fields: list[TypedDictFieldSpec] = []
+    upsert_where_dicts: list[UpsertWhereRender] = []
     dict_field_map: dict[str, str] = {}
     enum_type_map: dict[str, type[Enum] | None] = {}
+    column_lookup: dict[str, ColumnInfo] = {col.name: col for col in info.columns}
     for col in info.columns:
         annotation = _format_insert_annotation(col, renderer)
         default_fragment = _render_default_fragment(name, col)
@@ -248,6 +260,27 @@ def _build_model_context(
         enum_type = _resolve_enum_class(col.python_type)
         enum_type_map[col.name] = enum_type
 
+        update_fields.append(TypedDictFieldSpec(name=col.name, annotation=renderer.render(col.python_type)))
+
+    if info.primary_key:
+        pk_fields: list[TypedDictFieldSpec] = []
+        for pk_col in info.primary_key:
+            col_info = column_lookup.get(pk_col)
+            annotation = renderer.render(col_info.python_type) if col_info else "object"
+            pk_fields.append(TypedDictFieldSpec(name=pk_col, annotation=annotation))
+        upsert_where_dicts.append(UpsertWhereRender(name=f"{name}UpsertWherePK", fields=tuple(pk_fields)))
+
+    if info.unique_indexes:
+        for idx, unique_cols in enumerate(info.unique_indexes, start=1):
+            unique_fields: list[TypedDictFieldSpec] = []
+            for col_name in unique_cols:
+                col_info = column_lookup.get(col_name)
+                annotation = renderer.render(col_info.python_type) if col_info else "object"
+                unique_fields.append(TypedDictFieldSpec(name=col_name, annotation=annotation))
+            upsert_where_dicts.append(
+                UpsertWhereRender(name=f"{name}UpsertWhereUnique{idx}", fields=tuple(unique_fields))
+            )
+
     where_fields: list[WhereFieldSpec] = []
     for col in info.columns:
         annotation = renderer.render(col.python_type)
@@ -334,6 +367,13 @@ def _build_model_context(
     )
 
     row_assignments, default_factories = _build_row_assignment_context(info, enum_type_map)
+    primary_value_types: list[str] = []
+    for column_name in info.primary_key:
+        column = column_lookup.get(column_name)
+        if column is None:
+            primary_value_types.append("object")
+            continue
+        primary_value_types.append(renderer.render(column.python_type))
 
     relation_lookup = {relation.name: relation for relation in info.relations}
     dataclass_fields = fields(info.model)
@@ -362,6 +402,8 @@ def _build_model_context(
         table_name_literal=repr(name),
         insert_fields=tuple(insert_fields),
         typed_dict_fields=tuple(typed_dict_fields),
+        update_fields=tuple(update_fields),
+        upsert_where_dicts=tuple(upsert_where_dicts),
         dict_fields=tuple(dict_fields),
         where_fields=tuple(where_fields),
         relation_filters=tuple(relation_filters),
@@ -371,6 +413,7 @@ def _build_model_context(
         primary_key_literal=_tuple_literal(info.primary_key),
         indexes_literal=indexes_literal,
         unique_indexes_literal=unique_indexes_literal,
+        primary_value_types=tuple(primary_value_types),
         row_assignments=tuple(row_assignments),
         default_factories=tuple(default_factories),
         model_info=info,
@@ -436,6 +479,8 @@ def _collect_exports(model_contexts: Sequence[ModelRenderContext]) -> list[str]:
                 f"{name}Dict",
                 f"{name}Insert",
                 f"{name}InsertDict",
+                f"{name}UpdateDict",
+                f"{name}UpsertWhereDict",
                 f"{name}WhereDict",
                 f"{name}Table",
             ]

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/runtime/backends/base.py

@@ -2,16 +2,17 @@ from __future__ import annotations
 
 import sys
 from abc import ABC, abstractmethod
-from typing import Any, Mapping, Sequence, cast
+from typing import Any, Literal, Mapping, Sequence, cast, overload
 from weakref import ReferenceType, ref
 
 from pypika import Query, Table
 from pypika.enums import Order
-from pypika.terms import Criterion, Parameter
 from pypika.queries import QueryBuilder
+from pypika.terms import Criterion, Parameter
 from pypika.utils import format_quotes
 
-from dclassql.typing import IncludeT, InsertT, ModelT, OrderByT, WhereT
+from dclassql.runtime.sql_recorder import push_sql
+from dclassql.typing import IncludeT, InsertT, ModelT, OrderByT, UpsertWhereT, WhereT
 
 from .lazy import ensure_lazy_state, finalize_lazy_state, reset_lazy_backref
 from .protocols import BackendProtocol, RelationSpec, TableProtocol
@@ -67,6 +68,118 @@ class BackendBase(BackendProtocol, ABC):
         _ = batch_size  # 基础实现不做批量优化
         return [self.insert(table, item) for item in data]
 
+    def update(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT,
+        include: Mapping[str, bool] | None = None,
+    ) -> ModelT:
+        payload = table.serialize_update(data)
+        if not payload:
+            raise ValueError("Update payload cannot be empty")
+
+        sql_table = self.table_cls(table.model.__name__)
+        update_query: QueryBuilder = self.query_cls.update(sql_table)
+        params: list[Any] = []
+        for column, value in payload.items():
+            update_query = update_query.set(sql_table.field(column), self.new_parameter())
+            params.append(value)
+
+        criterion, where_params = self._compile_where(table, sql_table, where)
+        if criterion is not None:
+            update_query = update_query.where(criterion)
+            params.extend(where_params)
+
+        sql = self._render_query(update_query)
+        returning_columns = [spec.name for spec in table.column_specs]
+        sql_with_returning = self._append_returning(sql, returning_columns)
+
+        rows = self.query_raw(sql_with_returning, params, auto_commit=True)
+        if len(rows) != 1:
+            raise RuntimeError(f"update() expected exactly 1 row, got {len(rows)}")
+
+        row = rows[0]
+        include_map = include or {}
+        instance = self._materialize_instance(table, row, include_map)
+        identity_key = self._identity_key(table, row)
+        if identity_key is not None:
+            self._identity_map.pop(identity_key, None)
+        self._invalidate_backrefs(table, instance)
+        return instance
+
+    def upsert(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: UpsertWhereT,
+        update: Mapping[str, object],
+        insert: InsertT | Mapping[str, object],
+        include: Mapping[str, bool] | None = None,
+    ) -> ModelT:
+        where_payload = dict(where)
+        conflict_targets: list[tuple[str, ...]] = []
+        if table.primary_key:
+            conflict_targets.append(tuple(table.primary_key))
+        conflict_targets.extend(tuple(idx) for idx in getattr(table, "unique_indexes", ()))
+        if not conflict_targets:
+            raise ValueError("upsert requires primary key or unique index")
+
+        where_keys = set(where_payload.keys())
+        conflict_target: tuple[str, ...] | None = None
+        for target in conflict_targets:
+            if set(target) == where_keys:
+                conflict_target = target
+                break
+        if conflict_target is None:
+            raise ValueError("Upsert where must exactly match primary key or unique index")
+
+        insert_payload = table.serialize_insert(insert)
+        for column in conflict_target:
+            if column not in insert_payload:
+                insert_payload[column] = where_payload[column]
+        if not insert_payload:
+            raise ValueError("Upsert insert payload cannot be empty")
+
+        update_payload = table.serialize_update(update)
+        if not update_payload:
+            raise ValueError("Upsert update payload cannot be empty")
+
+        sql_table = self.table_cls(table.model.__name__)
+        insert_columns = list(insert_payload.keys())
+        params: list[Any] = [insert_payload[column] for column in insert_columns]
+
+        insert_query: QueryBuilder = (
+            self.query_cls.into(sql_table)
+            .columns(*insert_columns)
+            .insert(*(self.new_parameter() for _ in insert_columns))
+        )
+        sql_base = self._render_query(insert_query).rstrip().removesuffix(";")
+
+        conflict_target_sql = ", ".join(self.escape_identifier(col) for col in conflict_target)
+        update_assignments: list[str] = []
+        for column, value in update_payload.items():
+            update_assignments.append(f"{self.escape_identifier(column)} = {self.parameter_token}")
+            params.append(value)
+        update_clause = ", ".join(update_assignments)
+
+        sql = f"{sql_base} ON CONFLICT ({conflict_target_sql}) DO UPDATE SET {update_clause}"
+        returning_columns = [spec.name for spec in table.column_specs]
+        sql_with_returning = self._append_returning(sql, returning_columns)
+        rows = self.query_raw(sql_with_returning, params, auto_commit=True)
+        if len(rows) != 1:
+            raise RuntimeError(f"upsert() expected exactly 1 row, got {len(rows)}")
+
+        row = rows[0]
+        include_map = include or {}
+        instance = self._materialize_instance(table, row, include_map)
+        identity_key = self._identity_key(table, row)
+        if identity_key is not None:
+            self._identity_map.pop(identity_key, None)
+        self._invalidate_backrefs(table, instance)
+        return instance
+
     def find_many(
         self,
         table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
@@ -80,7 +193,33 @@ class BackendBase(BackendProtocol, ABC):
     ) -> list[ModelT]:
         sql_table = self.table_cls(table.model.__name__)
         distinct_columns = self._normalize_distinct(table, distinct)
-        select_query = self.query_cls.from_(sql_table).select(
+        select_query, params = self._build_select_query(table, sql_table, where, order_by)
+
+        if skip is not None and not distinct_columns:
+            select_query = select_query.offset(skip)
+        if take is not None and not distinct_columns:
+            select_query = select_query.limit(take)
+
+        sql = self._render_query(select_query)
+        rows = self.query_raw(sql, params)
+        row_list = list(rows)
+        if distinct_columns:
+            row_list = self._deduplicate_rows(row_list, distinct_columns)
+            if skip:
+                row_list = row_list[skip:]
+            if take is not None:
+                row_list = row_list[:take]
+        include_map = include or {}
+        return [self._materialize_instance(table, row, include_map) for row in row_list]
+
+    def _build_select_query(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        sql_table: Table,
+        where: WhereT | None,
+        order_by: Mapping[str, str] | None,
+    ) -> tuple[QueryBuilder, list[Any]]:
+        select_query: QueryBuilder = self.query_cls.from_(sql_table).select(
             *[sql_table.field(spec.name) for spec in table.column_specs]
         )
         params: list[Any] = []
@@ -100,22 +239,7 @@ class BackendBase(BackendProtocol, ABC):
                     raise ValueError("order_by direction must be 'asc' or 'desc'")
                 select_query = select_query.orderby(sql_table.field(column), order=Order[direction_lower])
 
-        if skip is not None and not distinct_columns:
-            select_query = select_query.offset(skip)
-        if take is not None and not distinct_columns:
-            select_query = select_query.limit(take)
-
-        sql = self._render_query(select_query)
-        rows = self.query_raw(sql, params)
-        row_list = list(rows)
-        if distinct_columns:
-            row_list = self._deduplicate_rows(row_list, distinct_columns)
-            if skip:
-                row_list = row_list[skip:]
-            if take is not None:
-                row_list = row_list[:take]
-        include_map = include or {}
-        return [self._materialize_instance(table, row, include_map) for row in row_list]
+        return select_query, params
 
     def find_first(
         self,
@@ -138,6 +262,157 @@ class BackendBase(BackendProtocol, ABC):
         )
         return results[0] if results else None
 
+    def delete(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT,
+        include: Mapping[str, bool] | None = None,
+    ) -> ModelT | None:
+        sql_table = self.table_cls(table.model.__name__)
+        delete_query: QueryBuilder = self.query_cls.from_(sql_table).delete()
+        criterion, params = self._compile_where(table, sql_table, where)
+        if criterion is None:
+            raise ValueError("delete() requires a where clause")
+        delete_query = delete_query.where(criterion)
+        sql = self._render_query(delete_query)
+        returning_columns = [spec.name for spec in table.column_specs]
+        sql_with_returning = self._append_returning(sql, returning_columns)
+        rows = self.query_raw(sql_with_returning, params, auto_commit=True)
+        if not rows:
+            return None
+        if len(rows) != 1:
+            raise RuntimeError(f"delete() expected exactly 1 row, got {len(rows)}")
+
+        row = rows[0]
+        include_map = include or {}
+        instance = self._materialize_instance(table, row, include_map)
+        identity_key = self._identity_key(table, row)
+        if identity_key is not None:
+            self._identity_map.pop(identity_key, None)
+        self._invalidate_backrefs(table, instance)
+        return instance
+
+    @overload
+    def delete_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT | None = None,
+        return_records: Literal[False] = False,
+    ) -> int: ...
+
+    @overload
+    def delete_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT | None = None,
+        return_records: Literal[True],
+    ) -> list[ModelT]: ...
+
+    def delete_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT | None = None,
+        return_records: Literal[False, True] = False,
+    ) -> int | list[ModelT]:
+        sql_table = self.table_cls(table.model.__name__)
+        delete_query: QueryBuilder = self.query_cls.from_(sql_table).delete()
+        params: list[Any] = []
+
+        if where:
+            criterion, where_params = self._compile_where(table, sql_table, where)
+            if criterion is not None:
+                delete_query = delete_query.where(criterion)
+                params.extend(where_params)
+
+        sql = self._render_query(delete_query)
+
+        if return_records:
+            returning_columns = [spec.name for spec in table.column_specs]
+            sql_with_returning = self._append_returning(sql, returning_columns)
+            rows = self.query_raw(sql_with_returning, params, auto_commit=True)
+            include_map: Mapping[str, bool] = {}
+            results: list[ModelT] = []
+            for row in rows:
+                identity_key = self._identity_key(table, row)
+                if identity_key is not None:
+                    self._identity_map.pop(identity_key, None)
+                instance = self._materialize_instance(table, row, include_map)
+                results.append(instance)
+            return results
+
+        affected = self.execute_raw(sql, params, auto_commit=True)
+        self._purge_identity_map(table.model)
+        return affected
+
+    @overload
+    def update_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT | None = None,
+        return_records: Literal[False] = False,
+    ) -> int: ...
+
+    @overload
+    def update_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT | None = None,
+        return_records: Literal[True],
+    ) -> list[ModelT]: ...
+
+    def update_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT | None = None,
+        return_records: Literal[False, True] = False,
+    ) -> int | list[ModelT]:
+        payload = table.serialize_update(data)
+        if not payload:
+            raise ValueError("Update payload cannot be empty")
+
+        sql_table = self.table_cls(table.model.__name__)
+        update_query: QueryBuilder = self.query_cls.update(sql_table)
+        params: list[Any] = []
+        for column, value in payload.items():
+            update_query = update_query.set(sql_table.field(column), self.new_parameter())
+            params.append(value)
+
+        if where:
+            criterion, where_params = self._compile_where(table, sql_table, where)
+            if criterion is not None:
+                update_query = update_query.where(criterion)
+                params.extend(where_params)
+
+        sql = self._render_query(update_query)
+
+        if return_records:
+            returning_columns = [spec.name for spec in table.column_specs]
+            sql_with_returning = self._append_returning(sql, returning_columns)
+            rows = self.query_raw(sql_with_returning, params, auto_commit=True)
+            include_map: Mapping[str, bool] = {}
+            results: list[ModelT] = []
+            for row in rows:
+                identity_key = self._identity_key(table, row)
+                if identity_key is not None:
+                    self._identity_map.pop(identity_key, None)
+                instance = self._materialize_instance(table, row, include_map)
+                results.append(instance)
+            return results
+
+        affected = self.execute_raw(sql, params, auto_commit=True)
+        self._purge_identity_map(table.model)
+        return affected
+
     def _fetch_single(
         self,
         table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
@@ -273,6 +548,11 @@ class BackendBase(BackendProtocol, ABC):
     def _clear_identity_map(self) -> None:
         self._identity_map.clear()
 
+    def _purge_identity_map(self, model: type[Any]) -> None:
+        stale_keys = [key for key in self._identity_map if key[0] is model]
+        for key in stale_keys:
+            self._identity_map.pop(key, None)
+
     def _render_query(self, query: QueryBuilder) -> str:
         return query.get_sql(quote_char=self.quote_char) + ';'
 
@@ -302,13 +582,8 @@ class BackendBase(BackendProtocol, ABC):
         return criterion, compiler.params
 
     def _log_sql(self, sql: str, params: Sequence[object] | None) -> None:
-        if not self._echo_sql:
-            return
-        if params is None:
-            display_params = []
-        else:
-            display_params = list(params)
-        print(f"[dclassql] SQL: {sql} | params={display_params}")
+        params_seq = list(params) if params is not None else []
+        push_sql(sql, params_seq, echo=self._echo_sql)
 
     def _normalize_distinct(
         self,

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/runtime/backends/protocols.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
 import sqlite3
-from typing import Callable, Literal, Mapping, Protocol, Sequence, runtime_checkable
+from typing import Callable, Literal, Mapping, Protocol, Sequence, overload, runtime_checkable
 
 from pypika import Query, Table
 from pypika.terms import Parameter
 
 from dclassql.model_inspector import DataSourceConfig
-from dclassql.typing import IncludeT, InsertT, ModelT, OrderByT, WhereT
+from dclassql.typing import IncludeT, InsertT, ModelT, OrderByT, WhereT, UpsertWhereT
 
 from .metadata import ColumnSpec, ForeignKeySpec, RelationSpec
 
@@ -26,10 +26,13 @@ class TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT](Protocol):
 
     @classmethod
     def serialize_insert(cls, data: InsertT | Mapping[str, object]) -> dict[str, object]: ...
+    @classmethod
+    def serialize_update(cls, data: Mapping[str, object]) -> dict[str, object]: ...
 
     @classmethod
     def deserialize_row(cls, row: Mapping[str, object]) -> ModelT: ...
     primary_key: tuple[str, ...]
+    def primary_values(self, instance: ModelT) -> tuple[object, ...]: ...
     indexes: tuple[tuple[str, ...], ...]
     unique_indexes: tuple[tuple[str, ...], ...]
     foreign_keys: tuple[ForeignKeySpec, ...]
@@ -49,6 +52,23 @@ class BackendProtocol(Protocol):
         table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
         data: InsertT | Mapping[str, object],
     ) -> ModelT: ...
+    def update(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT,
+        include: IncludeT | None = None,
+    ) -> ModelT: ...
+    def upsert(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: UpsertWhereT,
+        update: Mapping[str, object],
+        insert: InsertT | Mapping[str, object],
+        include: IncludeT | None = None,
+    ) -> ModelT: ...
 
     def insert_many(
         self,
@@ -57,6 +77,24 @@ class BackendProtocol(Protocol):
         *,
         batch_size: int | None = None,
     ) -> list[ModelT]: ...
+    @overload
+    def update_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT | None = None,
+        return_records: Literal[False] = False,
+    ) -> int: ...
+    @overload
+    def update_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        data: Mapping[str, object],
+        where: WhereT | None = None,
+        return_records: Literal[True],
+    ) -> list[ModelT]: ...
 
     def find_many(
         self,
@@ -81,6 +119,32 @@ class BackendProtocol(Protocol):
         skip: int | None = None,
     ) -> ModelT | None: ...
 
+    def delete(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT,
+        include: IncludeT | None = None,
+    ) -> ModelT | None: ...
+
+    @overload
+    def delete_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT | None = None,
+        return_records: Literal[False] = False,
+    ) -> int: ...
+
+    @overload
+    def delete_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT | None = None,
+        return_records: Literal[True],
+    ) -> list[ModelT]: ...
+
     def query_raw(self, sql: str, params: Sequence[object] | None = None, auto_commit: bool = False) -> Sequence[dict[str, object]]: ...
 
     def execute_raw(self, sql: str, params: Sequence[object] | None = None, auto_commit: bool = True) -> int: ...

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/runtime/backends/sqlite.py

@@ -4,7 +4,9 @@ import sqlite3
 import threading
 from typing import Any, Literal, Mapping, Sequence, overload
 
+from pypika import analytics as an
 from pypika.dialects import SQLLiteQuery
+from pypika.enums import Order
 from pypika.queries import QueryBuilder
 
 from dclassql.typing import IncludeT, InsertT, ModelT, OrderByT, WhereT
@@ -118,6 +120,70 @@ class SQLiteBackend(BackendBase):
         result = self._execute_sql(connection, sql, params, fetch=False, auto_commit=auto_commit)
         return result
 
+    def find_many(
+        self,
+        table: TableProtocol[ModelT, InsertT, WhereT, IncludeT, OrderByT],
+        *,
+        where: WhereT | None = None,
+        include: Mapping[str, bool] | None = None,
+        order_by: Mapping[str, str] | None = None,
+        distinct: Sequence[str] | str | None = None,
+        take: int | None = None,
+        skip: int | None = None,
+    ) -> list[ModelT]:
+        distinct_columns = self._normalize_distinct(table, distinct)
+        if not distinct_columns:
+            return super().find_many(
+                table,
+                where=where,
+                include=include,
+                order_by=order_by,
+                distinct=distinct,
+                take=take,
+                skip=skip,
+            )
+
+        sql_table = self.table_cls(table.model.__name__)
+        # 基础查询不带 order_by，方便后续在窗口与外层统一处理
+        base_query, params = self._build_select_query(table, sql_table, where, None)
+
+        partition_fields = [sql_table.field(col) for col in distinct_columns]
+        order_pairs: list[tuple[Any, Order]] = []
+        if order_by:
+            for col, direction in order_by.items():
+                direction_lower = direction.lower()
+                if direction_lower not in {"asc", "desc"}:
+                    raise ValueError("order_by direction must be 'asc' or 'desc'")
+                order_pairs.append((sql_table.field(col), Order[direction_lower]))
+        else:
+            for col in distinct_columns:
+                order_pairs.append((sql_table.field(col), Order.asc))
+
+        row_number = an.RowNumber().over(*partition_fields)
+        for field, ord_ in order_pairs:
+            row_number = row_number.orderby(field, order=ord_)
+        row_number = row_number.as_("rn")
+        inner_query = base_query.select(row_number)
+        sub = inner_query.as_("__d")
+        outer_query: QueryBuilder = self.query_cls.from_(sub).select(sub.star).where(sub.rn == 1)
+
+        if order_by:
+            for col, direction in order_by.items():
+                direction_lower = direction.lower()
+                outer_query = outer_query.orderby(getattr(sub, col), order=Order[direction_lower])
+
+        if take is not None:
+            outer_query = outer_query.limit(take)
+            if skip is not None:
+                outer_query = outer_query.offset(skip)
+        elif skip is not None:
+            outer_query = outer_query.limit(-1).offset(skip)
+
+        sql = outer_query.get_sql(quote_char=self.quote_char) + ";"
+        rows = self.query_raw(sql, params)
+        include_map = include or {}
+        return [self._materialize_instance(table, row, include_map) for row in rows]
+
 
     @overload
     def _execute_sql(

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/runtime/backends/where_compiler.py

@@ -167,9 +167,11 @@ class WhereCompiler:
         if operator == "NOT":
             if isinstance(operand, ABCMapping):
                 compiled = self._compile_filter(field, operand)
-            else:
-                compiled = self._compile_direct(field, operand)
-            return compiled.negate() if compiled is not None else None
+                return compiled.negate() if compiled is not None else None
+            if operand is None:
+                return field.isnull().negate()
+            bound = self._bind_value(operand)
+            return (field != bound) | field.isnull()
         raise ValueError(f"Unsupported filter operator '{operator}'")
 
     def _apply_like(self, field: Field, pattern: str) -> Criterion:

dclassql-0.2.0/src/dclassql/runtime/sql_recorder.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import contextvars
+from contextlib import contextmanager
+from typing import Any, Iterator, Sequence
+
+_current_recorder: contextvars.ContextVar[tuple[list[tuple[str, tuple[Any, ...]]], bool] | None] = (
+    contextvars.ContextVar("_current_recorder", default=None)
+)
+
+
+def record_sql(echo: bool = False):
+    """
+    记录当前上下文执行的 SQL.
+    example:
+    ```python
+    with record_sql() as sqls:
+        client.user.find_first(id=1)
+    print(sqls)  # [('SELECT ...', (1,))]
+    ```
+    """
+
+    @contextmanager
+    def _manager() -> Iterator[list[tuple[str, tuple[Any, ...]]]]:
+        token = None
+        records: list[tuple[str, tuple[Any, ...]]] = []
+        try:
+            token = _current_recorder.set((records, echo))
+            yield records
+        finally:
+            if token is not None:
+                _current_recorder.reset(token)
+
+    return _manager()
+
+
+def push_sql(sql: str, params: Sequence[Any], *, echo: bool) -> None:
+    recorder = _current_recorder.get()
+    rec_echo = False
+    if recorder is not None:
+        rec_list, rec_echo = recorder
+        rec_list.append((sql, tuple(params)))
+    if rec_echo or echo:
+        print(f"[dclassql] SQL: {sql} | params={list(params)}")

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/templates/partials/imports.jinja

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Literal, Mapping, Sequence, NotRequired
+from typing import Any, Literal, Mapping, Sequence, NotRequired, overload
 from typing_extensions import TypedDict
 
 from dclassql import DataSourceConfig

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/templates/partials/model_section.jinja

@@ -11,17 +11,24 @@
 {%- set sortable_alias = 'T' ~ name ~ 'SortableCol' -%}
 {%- set include_relations = info.relations | sort(attribute='name', case_sensitive=True) -%}
 {%- set sortable_columns = info.columns -%}
+{%- set update_dict_class = name ~ 'UpdateDict' -%}
+{%- set upsert_where_alias = name ~ 'UpsertWhereDict' -%}
+{%- set upsert_update_class = update_dict_class -%}
+{%- set upsert_insert_class = insert_class -%}
+{%- set upsert_insert_dict_class = insert_dict_class -%}
 
 {% set backend_signature = 'BackendProtocol' %}
 
 {% if include_relations %}
-{{ include_alias }} = Literal[{% for relation in include_relations %}'{{ relation.name }}'{% if not loop.last %}, {% endif %}{% endfor %}]
+{% set include_names = include_relations | map(attribute='name') | list %}
+{{ include_alias }} = Literal[{{ include_names | map('tojson') | join(', ') }}]
 {% else %}
 {{ include_alias }} = Literal[()]
 {% endif %}
 {% if sortable_columns %}
-{{ sortable_alias }} = Literal[{% for column in sortable_columns %}'{{ column.name }}'{% if not loop.last %}, {% endif %}{% endfor %}]
-{{ distinct_alias }} = Literal[{% for column in sortable_columns %}'{{ column.name }}'{% if not loop.last %}, {% endif %}{% endfor %}]
+{% set col_names = sortable_columns | map(attribute='name') | list %}
+{{ sortable_alias }} = Literal[{{ col_names | map('tojson') | join(', ') }}]
+{{ distinct_alias }} = Literal[{{ col_names | map('tojson') | join(', ') }}]
 {% else %}
 {{ sortable_alias }} = Literal[()]
 {{ distinct_alias }} = Literal[()]
@@ -37,6 +44,20 @@ class {{ name }}Dict(TypedDict, closed=True):
 class {{ insert_dict_class }}(TypedDict, closed=True):
 {{ macros.typed_dict_fields(model.typed_dict_fields)|indent(4, True) }}
 
+class {{ update_dict_class }}(TypedDict, total=False, closed=True):
+{{ macros.typed_dict_fields(model.update_fields)|indent(4, True) }}
+
+{% for upsert_dict in model.upsert_where_dicts %}
+class {{ upsert_dict.name }}(TypedDict, closed=True):
+{{ macros.typed_dict_fields(upsert_dict.fields)|indent(4, True) }}
+
+{% endfor %}
+{% if model.upsert_where_dicts|length == 1 %}
+{{ upsert_where_alias }} = {{ model.upsert_where_dicts[0].name }}
+{% else %}
+{{ upsert_where_alias }} = {{ model.upsert_where_dicts | map(attribute='name') | join(' | ') }}
+{% endif %}
+
 {% for relation_filter in model.relation_filters %}
 class {{ relation_filter.name }}(TypedDict, total=False, closed=True):
 {{ macros.typed_dict_fields(relation_filter.fields)|indent(4, True) }}
@@ -67,7 +88,9 @@ class {{ table_class }}(TableProtocol):
     datasource = {{ model.datasource_expr }}
 {{ macros.column_specs(model.column_specs)|indent(4, True) }}
     column_specs_by_name: Mapping[str, ColumnSpec] = MappingProxyType({spec.name: spec for spec in column_specs})
-    primary_key: tuple[str, ...] = {{ model.primary_key_literal }}
+{% set pk_types = ['str'] * (model.model_info.primary_key | length) %}
+    primary_key: tuple[{{ pk_types | join(', ') }}] = {{ model.primary_key_literal }}
+
     indexes: tuple[tuple[str, ...], ...] = {{ model.indexes_literal }}
     unique_indexes: tuple[tuple[str, ...], ...] = {{ model.unique_indexes_literal }}
 {{ macros.foreign_keys(model.foreign_keys)|indent(4, True) }}
@@ -75,6 +98,12 @@ class {{ table_class }}(TableProtocol):
 {% if model.default_factories %}
 {% for factory in model.default_factories %}    {{ factory.var_name }} = {{ factory.expression }}
 {% endfor %}{% endif %}
+    def primary_values(self, instance: {{ name }}) -> tuple[{{ model.primary_value_types | join(', ') }}]:
+        return (
+            {% for pk in model.model_info.primary_key %}
+            instance.{{ pk }},
+            {% endfor %}
+        )
 
     @classmethod
     def serialize_insert(cls, data: {{ insert_class }} | Mapping[str, object]) -> dict[str, object]:
@@ -91,6 +120,12 @@ class {{ table_class }}(TableProtocol):
 {% endfor %}            }
         raise TypeError("Unsupported insert payload type for {{ name }}")
 
+    @classmethod
+    def serialize_update(cls, data: Mapping[str, object]) -> dict[str, object]:
+        if not isinstance(data, Mapping):
+            raise TypeError("Update payload must be a mapping")
+        return cls.serialize_insert(data)
+
     @classmethod
     def deserialize_row(cls, row: Mapping[str, object]) -> {{ name }}:
         instance = {{ name }}.__new__({{ name }})  # type: ignore[call-arg]
@@ -109,6 +144,26 @@ class {{ table_class }}(TableProtocol):
     def insert_many(self, data: Sequence[{{ insert_class }} | {{ insert_dict_class }}], *, batch_size: int | None = None) -> list[{{ name }}]:
         return self._backend.insert_many(self, data, batch_size=batch_size)
 
+    def update(self, *, data: {{ update_dict_class }}, where: {{ where_dict_class }}, include: {{ include_dict_class }} | None = None) -> {{ name }}:
+        return self._backend.update(self, data=data, where=where, include=include)
+
+    @overload
+    def update_many(self, *, data: {{ update_dict_class }}, where: {{ where_dict_class }} | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def update_many(self, *, data: {{ update_dict_class }}, where: {{ where_dict_class }} | None = None, return_records: Literal[True]) -> list[{{ name }}]: ...
+    def update_many(self, *, data: {{ update_dict_class }}, where: {{ where_dict_class }} | None = None, return_records: Literal[False, True] = False) -> int | list[{{ name }}]:
+        return self._backend.update_many(self, data=data, where=where, return_records=return_records)
+
+    def upsert(
+        self,
+        *,
+        where: {{ upsert_where_alias }},
+        update: {{ upsert_update_class }},
+        insert: {{ upsert_insert_class }} | {{ upsert_insert_dict_class }},
+        include: {{ include_dict_class }} | None = None,
+    ) -> {{ name }}:
+        return self._backend.upsert(self, where=where, update=update, insert=insert, include=include)
+
     def find_many(self, *, where: {{ where_dict_class }} | None = None, include: {{ include_dict_class }} | None = None, order_by: {{ order_by_dict_class }} | None = None, distinct: {{ distinct_alias }} | Sequence[{{ distinct_alias }}] | None = None, take: int | None = None, skip: int | None = None) -> list[{{ name }}]:
         return self._backend.find_many(
             self, 
@@ -122,3 +177,13 @@ class {{ table_class }}(TableProtocol):
             where=where, include=include, order_by=order_by, distinct=distinct,
             skip=skip
         )
+
+    def delete(self, *, where: {{ where_dict_class }}, include: {{ include_dict_class }} | None = None) -> {{ name }} | None:
+        return self._backend.delete(self, where=where, include=include)
+
+    @overload
+    def delete_many(self, *, where: {{ where_dict_class }} | None = None, return_records: Literal[False] = False) -> int: ...
+    @overload
+    def delete_many(self, *, where: {{ where_dict_class }} | None = None, return_records: Literal[True]) -> list[{{ name }}]: ...
+    def delete_many(self, *, where: {{ where_dict_class }} | None = None, return_records: Literal[False, True] = False) -> int | list[{{ name }}]:
+        return self._backend.delete_many(self, where=where, return_records=return_records)

{dclassql-0.1.6 → dclassql-0.2.0}/src/dclassql/typing.py

@@ -5,3 +5,4 @@ InsertT  = TypeVar("InsertT", default=Mapping[str, object])
 WhereT   = TypeVar("WhereT",  bound=Mapping[str, object], default=Mapping[str, object])
 IncludeT = TypeVar("IncludeT", bound=Mapping[str, bool], default=Mapping[str, bool])
 OrderByT = TypeVar("OrderByT", bound=Mapping[str, Literal['asc','desc']], default=Mapping[str, Literal['asc','desc']])
+UpsertWhereT = TypeVar("UpsertWhereT", bound=Mapping[str, object], default=Mapping[str, object])