sqlobjects 2.0.1__py3-none-any.whl → 2.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. sqlobjects/__init__.py +1 -1
  2. sqlobjects/_compat.py +61 -0
  3. sqlobjects/cascade.py +22 -31
  4. sqlobjects/contrib/asgi.py +5 -3
  5. sqlobjects/database/manager.py +44 -30
  6. sqlobjects/expressions/aggregate.py +144 -83
  7. sqlobjects/expressions/scalar.py +5 -9
  8. sqlobjects/fields/__init__.py +2 -0
  9. sqlobjects/fields/core.py +5 -4
  10. sqlobjects/fields/proxies.py +78 -30
  11. sqlobjects/fields/relations/descriptors.py +4 -2
  12. sqlobjects/fields/relations/prefetch.py +62 -63
  13. sqlobjects/fields/relations/utils.py +50 -11
  14. sqlobjects/internal/results.py +1 -1
  15. sqlobjects/metadata.py +110 -37
  16. sqlobjects/mixins.py +24 -5
  17. sqlobjects/model.py +45 -72
  18. sqlobjects/objects/bulk.py +159 -245
  19. sqlobjects/objects/core.py +62 -58
  20. sqlobjects/objects/upsert.py +85 -8
  21. sqlobjects/queries/builder.py +77 -145
  22. sqlobjects/queries/dialect.py +4 -4
  23. sqlobjects/queries/executor.py +105 -209
  24. sqlobjects/queryset.py +64 -45
  25. sqlobjects/session.py +342 -38
  26. sqlobjects/signals.py +60 -33
  27. sqlobjects/sql_logging.py +107 -11
  28. sqlobjects/utils/naming.py +17 -1
  29. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/01-database-session-guide.md +54 -7
  30. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/02-model-definition-guide.md +25 -0
  31. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/03-query-operations-guide.md +47 -13
  32. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/04-crud-operations-guide.md +1 -1
  33. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/05-relationships-guide.md +48 -23
  34. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/06-validation-signals-guide.md +47 -12
  35. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/07-performance-guide.md +3 -3
  36. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/METADATA +17 -8
  37. sqlobjects-2.1.1.dist-info/RECORD +76 -0
  38. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/WHEEL +1 -1
  39. sqlobjects-2.0.1.dist-info/RECORD +0 -75
  40. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/README.md +0 -0
  41. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/entry_points.txt +0 -0
  42. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/licenses/LICENSE +0 -0
  43. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/top_level.txt +0 -0
sqlobjects/metadata.py CHANGED
@@ -1,14 +1,18 @@
1
1
  import re
2
+ from collections import Counter
2
3
  from dataclasses import dataclass, field
3
4
  from typing import TYPE_CHECKING, Any, Union, cast
4
5
 
5
6
  from sqlalchemy import CheckConstraint, ForeignKeyConstraint, Index, UniqueConstraint
6
7
  from sqlalchemy import MetaData as SqlAlchemyMetaData
8
+ from sqlalchemy.exc import CompileError
9
+ from sqlalchemy.sql.elements import conv
7
10
 
11
+ from ._compat import foreign_key_target_tokens, retarget_foreign_key
8
12
  from .fields import ColumnAttribute
9
13
  from .fields.relations import M2MTable, RelationshipDescriptor, RelationshipResolver
10
14
  from .fields.utils import get_column_from_field, is_field_definition
11
- from .utils.naming import to_snake_case
15
+ from .utils.naming import schema_name, to_snake_case
12
16
  from .utils.pattern import pluralize
13
17
 
14
18
 
@@ -29,6 +33,23 @@ _FIELD_NAME_PATTERN = re.compile(r"\b([a-zA-Z_][a-zA-Z0-9_]*)\b")
29
33
  _TEMP_INDEX_PREFIX = "__temp__idx_"
30
34
 
31
35
 
36
+ def _assign_schema_names(generated: list[tuple[Any, str, str]], explicit_names: set[str]) -> None:
37
+ """Name generated objects without changing caller-supplied names."""
38
+ counts = Counter(schema_name(name) for _, name, _ in generated)
39
+ used = explicit_names | set(counts)
40
+ for item, full_name, signature in sorted(generated, key=lambda entry: (entry[1], entry[2])):
41
+ name = schema_name(full_name)
42
+ if counts[name] > 1 or name in explicit_names:
43
+ attempt = 0
44
+ while True:
45
+ name = schema_name(full_name, disambiguator=f"{signature}:{attempt}")
46
+ if name not in used:
47
+ break
48
+ attempt += 1
49
+ item.name = conv(name)
50
+ used.add(name)
51
+
52
+
32
53
  @dataclass
33
54
  class _RawModelConfig:
34
55
  """Raw model configuration with optional fields for parsing phase."""
@@ -314,7 +335,11 @@ class ModelProcessor(type):
314
335
  # Check if this directly inherits from ObjectModel
315
336
  direct_objectmodel_bases = [base for base in bases if base.__name__ == "ObjectModel"]
316
337
 
317
- if direct_objectmodel_bases:
338
+ if "__registry__" in namespace:
339
+ registry = namespace["__registry__"]
340
+ if not isinstance(registry, ModelRegistry):
341
+ raise TypeError("__registry__ must be a ModelRegistry instance")
342
+ elif direct_objectmodel_bases:
318
343
  # Direct ObjectModel inheritance - use ObjectModel's shared registry
319
344
  objectmodel_base = direct_objectmodel_bases[0]
320
345
  if not hasattr(objectmodel_base, "__registry__"):
@@ -448,11 +473,9 @@ class ModelProcessor(type):
448
473
 
449
474
  # Collect indexes
450
475
  if getattr(column, "unique", False) and not getattr(column, "primary_key", False):
451
- index_name = f"idx_{table_name}_{name}"
452
- indexes.append(Index(index_name, name, unique=True))
476
+ indexes.append(index(None, name, unique=True))
453
477
  elif getattr(column, "index", False) and not getattr(column, "primary_key", False):
454
- index_name = f"idx_{table_name}_{name}"
455
- indexes.append(Index(index_name, name))
478
+ indexes.append(index(None, name))
456
479
 
457
480
  # Collect validators
458
481
  column_info = getattr(column, "info", None)
@@ -592,59 +615,104 @@ class ModelProcessor(type):
592
615
 
593
616
  @classmethod
594
617
  def _post_process_table_indexes(mcs, table, table_name: str) -> None:
595
- def col_sig(idx):
596
- return tuple(sorted(col.name for col in idx.columns)) if idx.columns else None
618
+ def expression_sig(idx):
619
+ # Index.columns loses expression structure and repeated columns.
620
+ # Preserve expression order, sort direction, collation and literals.
621
+ # Expression keys also select PostgreSQL operator classes.
622
+ return tuple(
623
+ (
624
+ str(expr.compile(compile_kwargs={"literal_binds": True, "include_table": False})),
625
+ getattr(expr, "key", None),
626
+ )
627
+ for expr in idx.expressions
628
+ )
597
629
 
598
630
  def dialect_sig(idx):
599
631
  # Dialect kwargs (postgresql_where / postgresql_using / mysql_using, etc.)
600
632
  # are part of an index's identity: same columns with different partial
601
633
  # predicates or access methods are distinct indexes, not duplicates.
602
- # Values may be str or SQLAlchemy expressions, so compare via str().
634
+ # Include literal values when comparing SQLAlchemy predicates.
603
635
  # dialect_kwargs only holds explicitly passed args, not dialect defaults.
604
636
  kwargs = getattr(idx, "dialect_kwargs", None) or {}
605
- return tuple(sorted((k, str(v)) for k, v in kwargs.items() if v is not None))
637
+
638
+ def render(value):
639
+ if not hasattr(value, "compile"):
640
+ return str(value)
641
+ try:
642
+ return str(value.compile(compile_kwargs={"literal_binds": True}))
643
+ except CompileError:
644
+ # Literal values of some types (JSON, custom types) have no
645
+ # generic renderer. Treat the predicate as unique rather than
646
+ # failing model definition or proving a false equivalence.
647
+ return f"<unrenderable {type(value).__name__} {id(value):#x}>"
648
+
649
+ return tuple(sorted((k, render(v)) for k, v in kwargs.items() if v is not None))
606
650
 
607
651
  def is_partial(idx):
608
- return any(k.endswith("_where") for k, _ in dialect_sig(idx))
652
+ return any(k.endswith("_where") and value is not None for k, value in idx.dialect_kwargs.items())
609
653
 
610
- full_sig_map: dict[tuple, list] = {} # (cols, unique, dialect_sig) -> indexes
611
- col_map: dict[tuple, list] = {} # cols -> indexes
654
+ full_sig_map: dict[tuple, list] = {} # (expressions, unique, options) -> indexes
655
+ shape_map: dict[tuple, list] = {} # (expressions, options) -> indexes
612
656
 
613
657
  for idx in list(table.indexes):
614
- cs = col_sig(idx)
615
- if cs is None:
658
+ # Conditional DDL can produce different schemas per dialect or
659
+ # callback result. Keep it intact instead of evaluating callbacks.
660
+ if getattr(idx, "_ddl_if", None) is not None:
616
661
  continue
617
- full_sig_map.setdefault((cs, getattr(idx, "unique", False), dialect_sig(idx)), []).append(idx)
618
- col_map.setdefault(cs, []).append(idx)
662
+ try:
663
+ expressions, options = expression_sig(idx), dialect_sig(idx)
664
+ except CompileError:
665
+ # Backend-only/custom expressions may have no generic compiler.
666
+ # Failing to prove equivalence must never remove an index.
667
+ continue
668
+ if not expressions:
669
+ continue
670
+ full_sig_map.setdefault((expressions, idx.unique, options), []).append(idx)
671
+ shape_map.setdefault((expressions, options), []).append(idx)
619
672
 
620
673
  to_remove: set = set()
621
674
 
622
- # Remove exact duplicates (same columns, unique flag, and dialect kwargs):
623
- # prefer explicit names over SQLAlchemy auto-generated "ix_*". Sort by name
675
+ # Remove exact duplicates (same expressions, unique flag, and options):
676
+ # prefer explicit names over generated names. Sort by name
624
677
  # so the kept index is deterministic regardless of set iteration order.
625
678
  for indexes in full_sig_map.values():
626
679
  if len(indexes) > 1:
627
680
  explicit = sorted(
628
- (i for i in indexes if not (i.name and i.name.startswith("ix_"))),
681
+ (
682
+ i
683
+ for i in indexes
684
+ if not (isinstance(i.name, conv) or (i.name and i.name.startswith(_TEMP_INDEX_PREFIX)))
685
+ ),
629
686
  key=lambda i: i.name or "",
630
687
  )
631
688
  keep = explicit[0] if explicit else sorted(indexes, key=lambda i: i.name or "")[0]
632
689
  to_remove.update(i for i in indexes if i is not keep)
633
690
 
634
- # Remove full-table non-unique when a full-table unique exists on same columns.
691
+ # A full-table unique index can replace a plain index only when its
692
+ # ordered expressions AND options match (including access method/INCLUDE).
635
693
  # Partial indexes (unique or not) never participate: a partial unique index
636
694
  # only covers rows matching its predicate and cannot replace a full index.
637
- for indexes in col_map.values():
695
+ for indexes in shape_map.values():
638
696
  if any(getattr(i, "unique", False) and not is_partial(i) for i in indexes):
639
697
  to_remove.update(i for i in indexes if not getattr(i, "unique", False) and not is_partial(i))
640
698
 
641
699
  for idx in to_remove:
642
700
  table.indexes.discard(idx)
643
701
 
644
- # Normalize temp names after dedup
702
+ # Normalize generated names after dedup. Explicit names and SQLAlchemy
703
+ # naming conventions retain control over their own identifiers.
704
+ generated = []
705
+ explicit_names = {str(cst.name) for cst in table.constraints if cst.name is not None}
645
706
  for idx in table.indexes:
646
707
  if idx.name and idx.name.startswith(_TEMP_INDEX_PREFIX) and idx.columns:
647
- idx.name = f"idx_{table_name}_{'_'.join(col.name for col in idx.columns)}"
708
+ name = f"idx_{table_name}_{'_'.join(col.name for col in idx.columns)}"
709
+ else:
710
+ if idx.name is not None:
711
+ explicit_names.add(str(idx.name))
712
+ continue
713
+ signature = repr((tuple(str(expr) for expr in idx.expressions), idx.unique, dialect_sig(idx)))
714
+ generated.append((idx, name, signature))
715
+ _assign_schema_names(generated, explicit_names)
648
716
 
649
717
  @classmethod
650
718
  def _post_process_table_constraints(mcs, table, table_name: str) -> None:
@@ -654,6 +722,8 @@ class ModelProcessor(type):
654
722
  table: SQLAlchemy Table instance
655
723
  table_name: Database table name
656
724
  """
725
+ generated = []
726
+ explicit_names = {str(item.name) for item in [*table.constraints, *table.indexes] if item.name is not None}
657
727
  for cst in table.constraints:
658
728
  if cst.name is None:
659
729
  if isinstance(cst, CheckConstraint):
@@ -661,12 +731,14 @@ class ModelProcessor(type):
661
731
  field_matches = _FIELD_NAME_PATTERN.findall(str(cst.sqltext))
662
732
  if field_matches:
663
733
  field_part = "_".join(field_matches[:2])
664
- cst.name = f"ck_{table_name}_{field_part}"
734
+ name = f"ck_{table_name}_{field_part}"
665
735
  else:
666
- cst.name = f"ck_{table_name}_constraint"
736
+ name = f"ck_{table_name}_constraint"
737
+ signature = str(cst.sqltext.compile(compile_kwargs={"literal_binds": True}))
667
738
  elif isinstance(cst, UniqueConstraint) and hasattr(cst, "columns"):
668
739
  field_names = "_".join(col.name for col in cst.columns)
669
- cst.name = f"uq_{table_name}_{field_names}"
740
+ name = f"uq_{table_name}_{field_names}"
741
+ signature = field_names
670
742
  elif isinstance(cst, ForeignKeyConstraint) and hasattr(cst, "columns"):
671
743
  # Handle foreign key constraints
672
744
  field_names = "_".join(col.name for col in cst.columns)
@@ -675,12 +747,17 @@ class ModelProcessor(type):
675
747
  try:
676
748
  ref_table = cst.elements[0].column.table.name
677
749
  ref_columns = "_".join(elem.column.name for elem in cst.elements)
678
- cst.name = f"fk_{table_name}_{field_names}_{ref_table}_{ref_columns}"
750
+ name = f"fk_{table_name}_{field_names}_{ref_table}_{ref_columns}"
679
751
  except Exception:
680
752
  # Fallback if reference cannot be resolved yet
681
- cst.name = f"fk_{table_name}_{field_names}"
753
+ name = f"fk_{table_name}_{field_names}"
682
754
  else:
683
- cst.name = f"fk_{table_name}_{field_names}"
755
+ name = f"fk_{table_name}_{field_names}"
756
+ signature = repr(tuple(elem.target_fullname for elem in cst.elements))
757
+ else:
758
+ continue
759
+ generated.append((cst, name, signature))
760
+ _assign_schema_names(generated, explicit_names)
684
761
 
685
762
  @classmethod
686
763
  def _apply_dataclass_functionality(mcs, cls: Any) -> Any:
@@ -878,7 +955,7 @@ class ModelProcessor(type):
878
955
  def _resolve_class_foreign_keys(mcs, registry):
879
956
  """延迟解析外键引用:优先按类名匹配,匹配不到则视为表名。
880
957
 
881
- foreign_key("User.id") 传入时原样交给 SQLAlchemy(_colspec="User.id")。
958
+ foreign_key("User.id") 传入时原样交给 SQLAlchemy(目标为 "User.id")。
882
959
  每次新模型注册后,此方法遍历所有 FK:
883
960
  1. 取出 info["_fk_ref"](即 "." 前的那段,如 "User")
884
961
  2. 尝试在 registry 中按类名查找模型
@@ -899,13 +976,9 @@ class ModelProcessor(type):
899
976
  continue
900
977
  # Found matching model — rewrite _colspec to actual table name
901
978
  actual_table = model.__table__.name
902
- schema, tname, colname = fk._column_tokens
979
+ _, tname, _ = foreign_key_target_tokens(fk)
903
980
  if tname != actual_table:
904
- if schema:
905
- fk._colspec = f"{schema}.{actual_table}.{colname}"
906
- else:
907
- fk._colspec = f"{actual_table}.{colname}"
908
- fk.__dict__.pop("_column_tokens", None)
981
+ retarget_foreign_key(fk, actual_table)
909
982
  fk_info["_fk_resolved"] = True
910
983
 
911
984
  @classmethod
sqlobjects/mixins.py CHANGED
@@ -167,13 +167,13 @@ class BaseMixin:
167
167
  class SessionMixin(BaseMixin):
168
168
  """Session management - Layer 1."""
169
169
 
170
- def get_session(self) -> AsyncSession:
170
+ def get_session(self, readonly: bool = True) -> AsyncSession:
171
171
  """Get the effective session for database operations.
172
172
 
173
173
  Returns:
174
174
  AsyncSession instance for database operations
175
175
  """
176
- return get_session(self._state_manager.get_bound_session())
176
+ return get_session(self._state_manager.get_bound_session(), readonly=readonly)
177
177
 
178
178
  def using(self, db_or_session: str | AsyncSession):
179
179
  """Return self bound to specific database/connection.
@@ -419,7 +419,7 @@ class DeferredLoadingMixin(ValidationMixin):
419
419
  Loaded relationship data
420
420
  """
421
421
  proxy = getattr(self, field_name)
422
- return await proxy.fetch()
422
+ return await proxy.fetch() if hasattr(proxy, "fetch") else proxy
423
423
 
424
424
  async def load_relations(self, *field_names: str) -> dict[str, Any]:
425
425
  """Load multiple relationship fields.
@@ -527,7 +527,7 @@ class FieldCacheMixin(DeferredLoadingMixin):
527
527
  field_cache = model_class._get_field_cache() # noqa
528
528
 
529
529
  # Handle deferred fields
530
- deferred_fields = field_cache.get("deferred_fields", set())
530
+ deferred_fields = self._deferred_fields
531
531
  if isinstance(deferred_fields, set) and name in deferred_fields:
532
532
  if (
533
533
  name in self._deferred_fields
@@ -587,6 +587,7 @@ class DataConversionMixin(FieldCacheMixin):
587
587
  ManyToManyRelation,
588
588
  OneToManyRelation,
589
589
  RelatedObject,
590
+ RelatedQuerySet,
590
591
  )
591
592
 
592
593
  all_fields = set(self._get_field_names())
@@ -622,7 +623,7 @@ class DataConversionMixin(FieldCacheMixin):
622
623
  try:
623
624
  rel_value = getattr(self, rel_name)
624
625
  # Skip proxy objects if not loaded
625
- if isinstance(rel_value, (RelatedObject, OneToManyRelation, ManyToManyRelation)):
626
+ if isinstance(rel_value, (RelatedObject, OneToManyRelation, ManyToManyRelation, RelatedQuerySet)):
626
627
  if safe_access:
627
628
  continue # Skip unloaded relationship proxies
628
629
  # Handle loaded relationship data
@@ -656,6 +657,24 @@ class DataConversionMixin(FieldCacheMixin):
656
657
 
657
658
  return result
658
659
 
660
+ @classmethod
661
+ def _from_database(cls, data: dict[str, Any], db_or_session=None):
662
+ """Hydrate stored values without applying Python construction defaults."""
663
+ instance = cls.__new__(cls)
664
+ BaseMixin.__init__(instance)
665
+ fields = set(cls._get_field_names())
666
+ for name, value in data.items():
667
+ if name in fields:
668
+ setattr(instance, name, value)
669
+ instance._state_manager.set_deferred_fields(fields - data.keys())
670
+ instance._state_manager.mark_from_database(True)
671
+ instance._state_manager.set_bound_session(db_or_session)
672
+ instance._state_manager._set(
673
+ "persisted_pk", {col.name: data[col.name] for col in cls.get_table().primary_key if col.name in data}
674
+ )
675
+ instance._state_manager.clear_dirty_fields()
676
+ return instance
677
+
659
678
  @classmethod
660
679
  def from_dict(cls, data: dict[str, Any], validate: bool = True):
661
680
  """Create model instance from dictionary with validation.
sqlobjects/model.py CHANGED
@@ -3,7 +3,7 @@ from typing import TypeVar
3
3
  from sqlalchemy import and_, insert, select, update
4
4
 
5
5
  from .cascade import CascadeExecutor
6
- from .exceptions import PrimaryKeyError
6
+ from .exceptions import DoesNotExist, PrimaryKeyError
7
7
  from .internal import SQLOperations
8
8
  from .metadata import ModelProcessor
9
9
  from .mixins import DataConversionMixin
@@ -133,7 +133,7 @@ class ModelMixin(DataConversionMixin, SignalMixin):
133
133
 
134
134
  Returns:
135
135
  Dictionary mapping dirty field names to their current values,
136
- or all field data if no dirty fields are tracked
136
+ only fields changed since the last database load or save
137
137
  """
138
138
  from .fields.proxies import (
139
139
  DeferredObject,
@@ -143,8 +143,6 @@ class ModelMixin(DataConversionMixin, SignalMixin):
143
143
  )
144
144
 
145
145
  dirty_fields = self._state_manager.get_dirty_fields()
146
- if not dirty_fields:
147
- return self._get_all_data()
148
146
 
149
147
  data = {}
150
148
  for name in dirty_fields:
@@ -167,77 +165,49 @@ class ModelMixin(DataConversionMixin, SignalMixin):
167
165
  setattr(self, col.name, pk_values[i])
168
166
 
169
167
  async def _save_internal(self, validate: bool = True, session=None):
170
- """Internal save operation using UPSERT with fallback to query-then-save.
171
-
172
- This method contains the core save logic that can be reused by both
173
- the public save() method and the cascade executor without triggering
174
- additional cascades or signals.
175
-
176
- Args:
177
- validate: Whether to run validation before saving
178
- session: Database session to use (gets current session if None)
179
-
180
- Returns:
181
- Self for method chaining
182
-
183
- Raises:
184
- PrimaryKeyError: If save operation fails
185
- ValidationError: If validation fails and validate=True
186
- """
168
+ """Insert new objects and update persisted objects without overwriting unloaded fields."""
187
169
  if session is None:
188
- session = self.get_session()
170
+ session = self.get_session(readonly=False)
189
171
  table = self.get_table()
190
-
172
+ persisted = self.is_from_database()
173
+ data = self._get_dirty_data() if persisted else self._get_all_data()
174
+ data = {name: value for name, value in data.items() if name in table.c}
191
175
  if validate:
192
- self.validate_all_fields()
193
-
194
- data = self._get_all_data()
195
-
196
- # Try UPSERT using UpsertHandler
197
- try:
198
- from .objects.upsert import ConflictResolution, UpsertHandler
199
-
200
- handler = UpsertHandler(session)
201
- pk_columns = [col.name for col in table.primary_key.columns]
202
-
203
- stmt = handler.get_upsert_statement(
204
- table=table,
205
- values=[data],
206
- conflict_resolution=ConflictResolution.UPDATE,
207
- match_fields=pk_columns,
208
- )
209
-
210
- result = await session.execute(stmt)
211
- if result.inserted_primary_key:
212
- self._set_primary_key_values(result.inserted_primary_key)
213
- self._state_manager.clear_dirty_fields()
214
- return self
215
-
216
- except (ValueError, Exception):
217
- # Fallback for unsupported databases or UPSERT failures
218
- pass
219
-
220
- # Fallback: query database to determine INSERT or UPDATE
221
- try:
222
- pk_conditions = self._build_pk_conditions()
223
- existing = await session.execute(select(table).where(and_(*pk_conditions)))
224
-
225
- if existing.first():
226
- # Record exists, perform UPDATE
227
- update_data = self._get_dirty_data()
228
- if update_data:
229
- stmt = update(table).where(and_(*pk_conditions)).values(**update_data)
230
- await session.execute(stmt)
176
+ self.validate_all_fields(list(data))
177
+ data = self._get_dirty_data() if persisted else self._get_all_data()
178
+ data = {name: value for name, value in data.items() if name in table.c}
179
+
180
+ # Preserve detached-object save semantics without treating every save as an upsert.
181
+ pk = self._state_manager._get("persisted_pk", None) if persisted else None
182
+ if not persisted and self._has_primary_key_values():
183
+ pk = self._get_primary_key_values()
184
+ existing = await session.execute(select(table).where(*(table.c[k] == v for k, v in pk.items())))
185
+ persisted = existing.first() is not None
186
+ if persisted:
187
+ pk = pk or self._get_primary_key_values()
188
+ if not pk or any(value is None for value in pk.values()):
189
+ raise PrimaryKeyError("Cannot save a persisted instance without primary key values")
190
+ if data:
191
+ result = await session.execute(
192
+ update(table).where(*(table.c[k] == v for k, v in pk.items())).values(**data)
193
+ )
194
+ if result.supports_sane_rowcount() and result.rowcount == 0:
195
+ raise DoesNotExist(f"{type(self).__name__} no longer exists")
196
+ else:
197
+ stmt = insert(table).values(**data)
198
+ if session.bind.dialect.insert_returning:
199
+ result = await session.execute(stmt.returning(*table.columns))
200
+ for name, value in result.one()._mapping.items():
201
+ setattr(self, name, value)
231
202
  else:
232
- # Record does not exist, perform INSERT
233
- stmt = insert(table).values(**data)
234
203
  result = await session.execute(stmt)
235
204
  if result.inserted_primary_key:
236
205
  self._set_primary_key_values(result.inserted_primary_key)
237
- except Exception as e:
238
- raise PrimaryKeyError(f"Save operation failed: {e}") from e
239
206
 
240
- # Clear dirty fields after successful save
207
+ self._state_manager.mark_from_database(True)
208
+ self._state_manager._set("persisted_pk", self._get_primary_key_values())
209
+ if self._state_manager.get_bound_session() is None:
210
+ self.using(session.db_name)
241
211
  self._state_manager.clear_dirty_fields()
242
212
  return self
243
213
 
@@ -263,7 +233,7 @@ class ModelMixin(DataConversionMixin, SignalMixin):
263
233
  ValidationError: If validation fails and validate=True
264
234
  """
265
235
  if session is None:
266
- session = self.get_session()
236
+ session = self.get_session(readonly=False)
267
237
 
268
238
  # Determine if cascade should be used
269
239
  if cascade is None:
@@ -293,7 +263,7 @@ class ModelMixin(DataConversionMixin, SignalMixin):
293
263
  if not self._has_primary_key_values():
294
264
  raise PrimaryKeyError("Cannot delete instance without primary key values")
295
265
 
296
- session = self.get_session()
266
+ session = self.get_session(readonly=False)
297
267
 
298
268
  # Auto-detect cascade need when not explicitly specified
299
269
  if cascade is None:
@@ -315,7 +285,7 @@ class ModelMixin(DataConversionMixin, SignalMixin):
315
285
  instance-level signals.
316
286
  """
317
287
  if session is None:
318
- session = self.get_session()
288
+ session = self.get_session(readonly=False)
319
289
 
320
290
  table = self.get_table()
321
291
  pk_conditions = self._build_pk_conditions()
@@ -332,7 +302,7 @@ class ModelMixin(DataConversionMixin, SignalMixin):
332
302
  session: Database session to use
333
303
  """
334
304
  if session is None:
335
- session = self.get_session()
305
+ session = self.get_session(readonly=False)
336
306
 
337
307
  table = self.get_table()
338
308
  pk_conditions = self._build_pk_conditions()
@@ -457,8 +427,11 @@ class ModelMixin(DataConversionMixin, SignalMixin):
457
427
  # Handle relationship field assignments
458
428
  if hasattr(self, "_get_relationship_fields") and name in self._get_relationship_fields():
459
429
  self._handle_relationship_assignment(name, value)
460
- elif not name.startswith("_") and hasattr(self, "_state_manager"):
430
+ elif not name.startswith("_") and hasattr(self, "_state_manager") and name in self._get_field_names():
461
431
  self._state_manager.add_dirty_field(name)
432
+ self._state_manager.clear_cache_entry(name)
433
+ if name in self._state_manager.get_deferred_fields():
434
+ self._state_manager.add_loaded_deferred_field(name)
462
435
  super().__setattr__(name, value)
463
436
 
464
437
  def _handle_relationship_assignment(self, field_name: str, value):