sqlobjects 2.0.0__py3-none-any.whl → 2.1.0__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 (42) hide show
  1. sqlobjects/__init__.py +1 -1
  2. sqlobjects/cascade.py +22 -31
  3. sqlobjects/contrib/asgi.py +5 -3
  4. sqlobjects/database/manager.py +44 -30
  5. sqlobjects/expressions/aggregate.py +144 -83
  6. sqlobjects/expressions/scalar.py +5 -9
  7. sqlobjects/fields/__init__.py +2 -0
  8. sqlobjects/fields/core.py +3 -2
  9. sqlobjects/fields/proxies.py +78 -30
  10. sqlobjects/fields/relations/descriptors.py +4 -2
  11. sqlobjects/fields/relations/prefetch.py +62 -63
  12. sqlobjects/fields/relations/utils.py +50 -11
  13. sqlobjects/internal/results.py +1 -1
  14. sqlobjects/metadata.py +124 -29
  15. sqlobjects/mixins.py +24 -5
  16. sqlobjects/model.py +45 -72
  17. sqlobjects/objects/bulk.py +159 -245
  18. sqlobjects/objects/core.py +62 -58
  19. sqlobjects/objects/upsert.py +85 -8
  20. sqlobjects/queries/builder.py +77 -145
  21. sqlobjects/queries/dialect.py +4 -4
  22. sqlobjects/queries/executor.py +105 -209
  23. sqlobjects/queryset.py +64 -45
  24. sqlobjects/session.py +342 -38
  25. sqlobjects/signals.py +60 -33
  26. sqlobjects/sql_logging.py +100 -11
  27. sqlobjects/utils/naming.py +17 -1
  28. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/01-database-session-guide.md +44 -5
  29. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/02-model-definition-guide.md +25 -0
  30. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/03-query-operations-guide.md +33 -4
  31. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/05-relationships-guide.md +37 -15
  32. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/06-validation-signals-guide.md +32 -0
  33. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/METADATA +9 -2
  34. sqlobjects-2.1.0.dist-info/RECORD +75 -0
  35. sqlobjects-2.0.0.dist-info/RECORD +0 -75
  36. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/04-crud-operations-guide.md +0 -0
  37. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/07-performance-guide.md +0 -0
  38. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/README.md +0 -0
  39. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/WHEEL +0 -0
  40. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/entry_points.txt +0 -0
  41. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/licenses/LICENSE +0 -0
  42. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/top_level.txt +0 -0
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):