sqlobjects 2.0.1__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 +106 -30
  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.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/01-database-session-guide.md +44 -5
  29. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/02-model-definition-guide.md +25 -0
  30. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/03-query-operations-guide.md +33 -4
  31. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/05-relationships-guide.md +37 -15
  32. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/06-validation-signals-guide.md +32 -0
  33. {sqlobjects-2.0.1.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.1.dist-info/RECORD +0 -75
  36. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/04-crud-operations-guide.md +0 -0
  37. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/07-performance-guide.md +0 -0
  38. {sqlobjects-2.0.1.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/README.md +0 -0
  39. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.0.dist-info}/WHEEL +0 -0
  40. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.0.dist-info}/entry_points.txt +0 -0
  41. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.0.dist-info}/licenses/LICENSE +0 -0
  42. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.0.dist-info}/top_level.txt +0 -0
@@ -4,14 +4,15 @@ This module provides the core ObjectsManager functionality including
4
4
  session management, query building, and single record operations.
5
5
  """
6
6
 
7
+ from contextlib import aclosing
7
8
  from typing import Any, Generic, Literal, overload
8
9
 
9
10
  from sqlalchemy import insert, text
10
11
 
11
- from ..exceptions import DoesNotExist, MultipleObjectsReturned
12
+ from ..exceptions import DoesNotExist, IntegrityError, MultipleObjectsReturned
12
13
  from ..queryset import QuerySet, T, TableLike
13
14
  from ..session import AsyncSession, get_session
14
- from ..signals import Operation, emit_signals
15
+ from ..signals import Operation, SignalContext
15
16
  from .bulk import BulkResult, ConflictResolution, ErrorHandling, TransactionMode
16
17
 
17
18
 
@@ -453,8 +454,9 @@ class ObjectsManager(Generic[T]):
453
454
  Yields:
454
455
  Model instances one by one
455
456
  """
456
- async for obj in self.filter().iterator(chunk_size):
457
- yield obj
457
+ async with aclosing(self.filter().iterator(chunk_size)) as stream:
458
+ async for obj in stream:
459
+ yield obj
458
460
 
459
461
  def get_item(self, key):
460
462
  """Create get_item expression that can be executed or used as subquery.
@@ -492,21 +494,25 @@ class ObjectsManager(Generic[T]):
492
494
  self._validate_field_names(**defaults)
493
495
 
494
496
  try:
495
- # Try to get existing object
496
- conditions = [self._table.c[field] == value for field, value in lookup.items()]
497
- obj = await self.filter(*conditions).get()
498
- return obj, False
497
+ return await self.filter(**lookup).get(), False
499
498
  except DoesNotExist:
500
- # Create new object with lookup fields + defaults
501
- create_data = lookup.copy()
502
- if defaults:
503
- # defaults override lookup values if there's conflict
504
- create_data.update(defaults)
505
-
506
- # Create instance and use save() method to trigger signals
507
- obj = self._model_class.from_dict(create_data, validate=False) # type: ignore[reportAttributeAccessIssue]
508
- await obj.using(self._get_session(readonly=False)).save(validate=validate)
509
- return obj, True
499
+ pass
500
+ create_data = {**lookup, **(defaults or {})}
501
+ session = self._get_session(readonly=False)
502
+ async with session.transaction() as transaction:
503
+ try:
504
+ async with await transaction.begin_nested():
505
+ obj = await self.using(transaction).create(validate=validate, **create_data)
506
+ # Keep the database origin, not an internally owned session after it closes.
507
+ obj.using(self._db_or_session or session.db_name) # type: ignore[reportAttributeAccessIssue]
508
+ return obj, True
509
+ except IntegrityError as error:
510
+ try:
511
+ obj = await self.using(transaction).filter(**lookup).get()
512
+ obj.using(self._db_or_session or session.db_name) # type: ignore[reportAttributeAccessIssue]
513
+ return obj, False
514
+ except DoesNotExist:
515
+ raise error from None
510
516
 
511
517
  async def update_or_create(
512
518
  self, defaults: dict[str, Any] | None = None, validate: bool = True, **lookup
@@ -529,29 +535,23 @@ class ObjectsManager(Generic[T]):
529
535
  if defaults:
530
536
  self._validate_field_names(**defaults)
531
537
 
532
- try:
533
- # Try to get existing object
534
- conditions = [self._table.c[field] == value for field, value in lookup.items()]
535
- obj = await self.filter(*conditions).get()
536
-
537
- # Update existing object with defaults using save() method
538
+ session = self._get_session(readonly=False)
539
+ async with session.transaction() as transaction:
540
+ manager = self.using(transaction)
541
+ try:
542
+ obj = await manager.select_for_update().filter(**lookup).get()
543
+ except DoesNotExist:
544
+ obj, created = await manager.get_or_create(defaults=defaults, validate=validate, **lookup)
545
+ if created:
546
+ obj.using(self._db_or_session or session.db_name) # type: ignore[reportAttributeAccessIssue]
547
+ return obj, True
548
+ obj = await manager.select_for_update().filter(**lookup).get()
549
+ for key, value in (defaults or {}).items():
550
+ setattr(obj, key, value)
538
551
  if defaults:
539
- for key, value in defaults.items():
540
- setattr(obj, key, value)
541
- await obj.using(self._get_session(readonly=False)).save(validate=validate) # type: ignore[reportAttributeAccessIssue]
542
-
552
+ await obj.save(validate=validate, session=transaction) # type: ignore[reportAttributeAccessIssue]
553
+ obj.using(self._db_or_session or session.db_name) # type: ignore[reportAttributeAccessIssue]
543
554
  return obj, False
544
- except DoesNotExist:
545
- # Create new object with lookup fields + defaults
546
- create_data = lookup.copy()
547
- if defaults:
548
- # defaults override lookup values if there's conflict
549
- create_data.update(defaults)
550
-
551
- # Create instance and use save() method to trigger signals
552
- obj = self._model_class.from_dict(create_data, validate=False) # type: ignore[reportAttributeAccessIssue]
553
- await obj.using(self._get_session(readonly=False)).save(validate=validate)
554
- return obj, True
555
555
 
556
556
  async def in_bulk(self, id_list: list[Any] | None = None, field_name: str = "pk") -> dict[Any, T]:
557
557
  """Get multiple objects as a dictionary mapping field values to objects.
@@ -577,7 +577,6 @@ class ObjectsManager(Generic[T]):
577
577
  objects = await queryset.all()
578
578
  return {getattr(obj, actual_field): obj for obj in objects}
579
579
 
580
- @emit_signals(Operation.SAVE)
581
580
  async def create(self, validate: bool = True, **kwargs) -> T:
582
581
  """Create a new object with the given field values.
583
582
 
@@ -588,23 +587,31 @@ class ObjectsManager(Generic[T]):
588
587
  Returns:
589
588
  Created model instance
590
589
  """
591
- try:
592
- obj = self._model_class.from_dict(kwargs, validate=False) # type: ignore[reportAttributeAccessIssue]
593
- # Execute database operation directly, don't call obj.save() to avoid duplicate signals
590
+ obj = self._model_class.from_dict(kwargs, validate=False) # type: ignore[reportAttributeAccessIssue]
591
+ session = self._get_session(readonly=False)
592
+ async with session.transaction() as transaction:
593
+ context = SignalContext(
594
+ Operation.SAVE, transaction, self._model_class, instance=obj, actual_operation=Operation.CREATE
595
+ )
596
+ await obj._emit_signal("before", context)
594
597
  if validate:
595
598
  obj.validate_all_fields()
596
-
597
- stmt = insert(self._table).values(**obj._get_all_data()) # noqa
598
- session = self._get_session(readonly=False)
599
- result = await session.execute(stmt)
600
-
601
- # Set primary key values from result
602
- if result.inserted_primary_key:
603
- obj._set_primary_key_values(result.inserted_primary_key) # noqa
604
-
605
- return obj
606
- except Exception as e:
607
- raise RuntimeError(f"Failed to create {self._model_class.__name__}: {e}") from e
599
+ # create() always INSERTs, even when a primary key was supplied.
600
+ stmt = insert(self._table).values(**obj._get_all_data())
601
+ if transaction.bind.dialect.insert_returning:
602
+ result = await transaction.execute(stmt.returning(*self._table.columns))
603
+ for name, value in result.one()._mapping.items():
604
+ setattr(obj, name, value)
605
+ else:
606
+ result = await transaction.execute(stmt)
607
+ if result.inserted_primary_key:
608
+ obj._set_primary_key_values(result.inserted_primary_key)
609
+ obj._state_manager.mark_from_database(True)
610
+ obj._state_manager._set("persisted_pk", obj._get_primary_key_values())
611
+ obj._state_manager.clear_dirty_fields()
612
+ obj.using(self._db_or_session or transaction.db_name)
613
+ await obj._emit_signal("after", context)
614
+ return obj
608
615
 
609
616
  # QuerySet shortcut methods
610
617
 
@@ -778,7 +785,6 @@ class ObjectsManager(Generic[T]):
778
785
  conflict_fields: list[str] | None = None,
779
786
  ) -> BulkResult[dict[str, Any]]: ...
780
787
 
781
- @emit_signals(Operation.SAVE, is_bulk=True)
782
788
  async def bulk_create(
783
789
  self,
784
790
  objects: list[dict[str, Any]],
@@ -865,7 +871,6 @@ class ObjectsManager(Generic[T]):
865
871
  conflict_fields: list[str] | None = None,
866
872
  ) -> BulkResult[dict[str, Any]]: ...
867
873
 
868
- @emit_signals(Operation.SAVE, is_bulk=True)
869
874
  async def bulk_update(
870
875
  self,
871
876
  mappings: list[dict[str, Any]],
@@ -948,7 +953,6 @@ class ObjectsManager(Generic[T]):
948
953
  on_error: ErrorHandling = ErrorHandling.FAIL_FAST,
949
954
  ) -> BulkResult[dict[str, Any]]: ...
950
955
 
951
- @emit_signals(Operation.DELETE, is_bulk=True)
952
956
  async def bulk_delete(
953
957
  self,
954
958
  ids: list[Any],
@@ -50,11 +50,61 @@ class UpsertHandler:
50
50
  # Use DialectHandler to generate statement
51
51
  return self.dialect.get_upsert_statement(
52
52
  table=table,
53
- data=values[0],
53
+ data=values[0] if len(values) == 1 else values,
54
54
  conflict_fields=match_fields or [],
55
55
  update_fields=update_fields,
56
56
  )
57
57
 
58
+ async def _match_returned_rows(
59
+ self,
60
+ table: sa.Table,
61
+ values: list[dict[str, Any]],
62
+ match_fields: list[str],
63
+ returned: list[dict[str, Any]],
64
+ ) -> list[dict[str, Any]]:
65
+ """Restore input order for multi-row RETURNING without trusting input values.
66
+
67
+ The database may normalize conflict-key values (string to integer,
68
+ Decimal scale, timezone, case-insensitive collations, UUID objects), so a
69
+ returned row does not always equal the raw input key. Rows that cannot be
70
+ matched in Python are resolved by asking the database, and only accepted
71
+ when they are among the rows this statement actually returned.
72
+ """
73
+ by_key: dict[tuple, dict[str, Any]] = {}
74
+ for row in returned:
75
+ by_key.setdefault(tuple(row[f] for f in match_fields), row)
76
+ pk_columns = [col.name for col in table.primary_key]
77
+
78
+ def identity(row: dict[str, Any]) -> tuple:
79
+ return tuple(row[c] for c in pk_columns) if pk_columns else tuple(sorted(row.items()))
80
+
81
+ ordered: list[dict[str, Any] | None] = []
82
+ unmatched: list[int] = []
83
+ for index, value in enumerate(values):
84
+ row = by_key.pop(tuple(value[f] for f in match_fields), None)
85
+ ordered.append(row)
86
+ if row is None:
87
+ unmatched.append(index)
88
+
89
+ # Every returned row was matched, or nothing is left to attribute.
90
+ if unmatched and by_key:
91
+ remaining = {identity(row) for row in by_key.values()}
92
+ for index in unmatched:
93
+ if not remaining:
94
+ break
95
+ value = values[index]
96
+ stored = await self.session.execute(
97
+ sa.select(table).where(*(table.c[f] == value[f] for f in match_fields))
98
+ )
99
+ row = stored.one_or_none()
100
+ if row is None:
101
+ continue
102
+ data = dict(row._mapping)
103
+ if identity(data) in remaining:
104
+ remaining.discard(identity(data))
105
+ ordered[index] = data
106
+ return [row for row in ordered if row is not None]
107
+
58
108
  async def execute_upsert_with_returning(
59
109
  self,
60
110
  table: sa.Table,
@@ -65,14 +115,41 @@ class UpsertHandler:
65
115
  """Execute UPSERT and return affected rows."""
66
116
  if not values:
67
117
  return []
118
+ match_fields = match_fields or []
68
119
 
69
- stmt = self.get_upsert_statement(table, values, conflict_resolution, match_fields)
70
-
71
- if self.dialect.supports_returning():
120
+ # A matching key lets us restore input order after a multi-row RETURNING.
121
+ can_match = bool(match_fields) and all(
122
+ all(field in value and value[field] is not None for field in match_fields) for value in values
123
+ )
124
+ if (
125
+ self.dialect.supports_returning()
126
+ and can_match
127
+ and len({tuple(v[f] for f in match_fields) for v in values}) == len(values)
128
+ ):
129
+ stmt = self.get_upsert_statement(table, values, conflict_resolution, match_fields)
72
130
  stmt = stmt.returning(*table.columns) # noqa
73
131
  result = await self.session.execute(stmt)
74
- return [dict(row._mapping) for row in result.fetchall()] # noqa
75
- else:
76
- # For databases without RETURNING support
132
+ return await self._match_returned_rows(table, values, match_fields, [dict(r._mapping) for r in result])
133
+
134
+ rows = []
135
+ for value in values:
136
+ stmt = self.get_upsert_statement(table, [value], conflict_resolution, match_fields)
137
+ if self.dialect.supports_returning():
138
+ result = await self.session.execute(stmt.returning(*table.columns))
139
+ rows.extend(dict(row._mapping) for row in result.fetchall())
140
+ continue
77
141
  result = await self.session.execute(stmt)
78
- return values[: result.rowcount] if result.rowcount and result.rowcount > 0 else []
142
+ if result.rowcount <= 0:
143
+ continue
144
+ # Fetch actual stored values; affected-row counts are not input offsets.
145
+ keys: dict[str, Any] = {field: value[field] for field in match_fields if field in value}
146
+ if not keys:
147
+ primary_key = result.inserted_primary_key
148
+ if primary_key is not None:
149
+ keys = dict(zip((col.name for col in table.primary_key), primary_key, strict=True))
150
+ if not keys or any(v is None for v in keys.values()):
151
+ raise ValueError("UPSERT without RETURNING requires conflict fields or a generated primary key")
152
+ stored = await self.session.execute(sa.select(table).where(*(table.c[k] == v for k, v in keys.items())))
153
+ row = stored.one()
154
+ rows.append(dict(row._mapping))
155
+ return rows
@@ -41,6 +41,7 @@ class QueryBuilder:
41
41
  self.selected_fields: set[str] = set()
42
42
  self.deferred_fields: set[str] = set()
43
43
  self.distinct_fields: list[str] = []
44
+ self.is_distinct = False
44
45
  self.annotations: dict[str, Any] = {}
45
46
  self.group_clauses: list[Any] = []
46
47
  self.having_conditions: list[Any] = []
@@ -212,6 +213,7 @@ class QueryBuilder:
212
213
  """
213
214
  new_builder = self.copy()
214
215
  new_builder.distinct_fields = list(fields)
216
+ new_builder.is_distinct = True
215
217
  return new_builder
216
218
 
217
219
  def add_annotations(self, **kwargs):
@@ -325,129 +327,54 @@ class QueryBuilder:
325
327
  new_builder.is_reversed = True
326
328
  return new_builder
327
329
 
328
- def _find_foreign_key_column(self, table, relation_name):
329
- """Find foreign key column for relation."""
330
- fk_column_name = f"{relation_name}_id"
331
- if fk_column_name in table.c and table.c[fk_column_name].foreign_keys:
332
- return table.c[fk_column_name]
333
- return None
334
-
335
- def _find_table_by_model_name(self, metadata, model_name):
336
- """Find table by model name."""
337
- # Try pluralized form first
338
- table_name = f"{model_name}s"
339
- if table_name in metadata.tables:
340
- return metadata.tables[table_name]
341
- # Try exact name
342
- if model_name in metadata.tables:
343
- return metadata.tables[model_name]
344
- return None
345
-
346
- def _find_reverse_foreign_key(self, target_table, source_table):
347
- """Find reverse foreign key."""
348
- source_table_name = source_table.name
349
- if source_table_name.endswith("s"):
350
- source_table_name = source_table_name[:-1]
351
- source_fk_name = f"{source_table_name}_id"
352
- if source_fk_name in target_table.c and target_table.c[source_fk_name].foreign_keys:
353
- return target_table.c[source_fk_name]
354
- return None
355
-
356
- def _get_referenced_table(self, fk_column, metadata):
357
- """Get referenced table from foreign key."""
358
- fk = list(fk_column.foreign_keys)[0]
359
- return fk.column.table
360
-
361
- def _apply_select_related_joins(self, query, base_table):
362
- """Apply JOIN clauses for select_related relationships."""
363
- metadata = base_table.metadata
364
-
365
- for relationship_path in self.relationships:
366
- try:
367
- path_parts = relationship_path.split("__")
368
- current_table = base_table
369
-
370
- for relation_name in path_parts:
371
- # Try forward relationship first
372
- fk_column = self._find_foreign_key_column(current_table, relation_name)
373
-
374
- if fk_column is not None:
375
- # Forward relationship
376
- referenced_table = self._get_referenced_table(fk_column, metadata)
377
- join_condition = fk_column == referenced_table.c.id
378
- query = query.outerjoin(referenced_table, join_condition)
379
- current_table = referenced_table
380
- else:
381
- # Try reverse relationship
382
- target_table = self._find_table_by_model_name(metadata, relation_name)
383
- if target_table is not None:
384
- reverse_fk = self._find_reverse_foreign_key(target_table, current_table)
385
- if reverse_fk is not None:
386
- join_condition = current_table.c.id == reverse_fk
387
- query = query.outerjoin(target_table, join_condition)
388
- current_table = target_table
389
- continue
390
-
391
- # No valid relationship found
392
- available_relations = [
393
- col.name[:-3] for col in current_table.c if col.name.endswith("_id") and col.foreign_keys
394
- ]
395
- raise ValueError(
396
- f"Invalid relationship '{relation_name}' in path '{relationship_path}'. "
397
- f"Available relationships: {available_relations}"
330
+ def _select_related_plan(self, base_table):
331
+ """Resolve each relationship once and allocate an alias per path."""
332
+ from ..fields.relations.utils import RelationshipAnalyzer
333
+
334
+ plan = {}
335
+ for path in sorted(self.relationships):
336
+ model, source = self.model_class, base_table
337
+ parts = path.split("__")
338
+ for index, name in enumerate(parts):
339
+ prefix = "__".join(parts[: index + 1])
340
+ if prefix in plan:
341
+ target, info, _ = plan[prefix]
342
+ else:
343
+ info = RelationshipAnalyzer.analyze_relationship(model, name)
344
+ if not info:
345
+ raise ValueError(f"Invalid relationship '{name}' on {model.__name__}")
346
+ if info["type"] not in ("many_to_one", "one_to_one"):
347
+ raise QueryError(
348
+ f"select_related requires a single-valued relationship; use prefetch_related for '{path}'"
398
349
  )
399
-
400
- except ValueError:
401
- raise
402
- except Exception as e:
403
- raise ValueError(f"Error processing relationship '{relationship_path}': {e}") from e
404
-
405
- return query
406
-
407
- def _get_next_table_in_path(self, current_table, relation_name, metadata):
408
- """Get next table in relationship path."""
409
- # Try forward relationship
410
- fk_column = self._find_foreign_key_column(current_table, relation_name)
411
- if fk_column:
412
- return self._get_referenced_table(fk_column, metadata)
413
-
414
- # Try reverse relationship
415
- target_table = self._find_table_by_model_name(metadata, relation_name)
416
- if target_table and self._find_reverse_foreign_key(target_table, current_table):
417
- return target_table
418
-
419
- return None
420
-
421
- def _get_select_related_columns(self, base_table):
422
- """Get columns from related tables for select_related."""
423
- related_columns = []
424
- metadata = base_table.metadata
425
-
426
- for relationship_path in self.relationships:
427
- try:
428
- path_parts = relationship_path.split("__")
429
- current_table = base_table
430
-
431
- for i, relation_name in enumerate(path_parts):
432
- # Get next table
433
- next_table = self._get_next_table_in_path(current_table, relation_name, metadata)
434
- if next_table is None:
435
- break
436
-
437
- # Build path prefix for unique aliases
438
- path_prefix = "__".join(path_parts[: i + 1])
439
-
440
- # Add columns with unique aliases
441
- for column in next_table.c:
442
- alias = f"{path_prefix}__{column.name}"
443
- related_columns.append(column.label(alias))
444
-
445
- current_table = next_table
446
-
447
- except Exception:
448
- continue
449
-
450
- return related_columns
350
+ target = info["related_model"].get_table().alias(f"sr_{prefix}")
351
+ local, remote = (
352
+ (info["foreign_key_fields"], info["ref_fields"])
353
+ if info["type"] == "many_to_one"
354
+ else (info["ref_fields"], info["foreign_key_fields"])
355
+ )
356
+ condition = and_(
357
+ *(source.c[left] == target.c[right] for left, right in zip(local, remote, strict=True))
358
+ )
359
+ plan[prefix] = (target, info, condition)
360
+ model, source = info["related_model"], target
361
+ return plan
362
+
363
+ def _get_select_related_columns(self, plan):
364
+ columns = []
365
+ for path, (target, info, _) in plan.items():
366
+ selected = {name[len(path) + 2 :] for name in self.selected_fields if name.startswith(path + "__")}
367
+ primary_keys = {col.name for col in info["related_model"].get_table().primary_key}
368
+ auto_deferred = info["related_model"]._get_field_cache().get("deferred_fields", set())
369
+ for col in target.c:
370
+ label = f"{path}__{col.name}"
371
+ if col.name not in primary_keys:
372
+ if label in self.deferred_fields or (selected and col.name not in selected):
373
+ continue
374
+ if col.name in auto_deferred and col.name not in selected:
375
+ continue
376
+ columns.append(col.label(label))
377
+ return columns
451
378
 
452
379
  def build(self, table, values_fields: tuple[str, ...] | None = None):
453
380
  """Build final SQLAlchemy query object from accumulated clauses.
@@ -481,6 +408,8 @@ class QueryBuilder:
481
408
  except Exception: # noqa
482
409
  pass
483
410
 
411
+ select_plan = self._select_related_plan(table) if self.relationships else {}
412
+
484
413
  # Collect all columns to select (base table + related tables)
485
414
  columns_to_select = []
486
415
 
@@ -512,23 +441,28 @@ class QueryBuilder:
512
441
  columns_to_select.append(text(sql).label(field_name))
513
442
  # Handle field selection (only() method)
514
443
  elif self.selected_fields:
515
- columns_to_select.extend([table.c[field] for field in self.selected_fields if field in table.c])
444
+ selected = self.selected_fields - self.deferred_fields
445
+ if not self.group_clauses:
446
+ selected.update(col.name for col in table.primary_key)
447
+ columns_to_select.extend(table.c[field] for field in table.c.keys() if field in selected)
516
448
  elif self.deferred_fields or auto_deferred_fields:
517
449
  # For defer() or auto-deferred fields, select all fields except deferred ones
518
450
  all_fields = set(table.columns.keys())
519
451
  combined_deferred = self.deferred_fields | auto_deferred_fields
520
452
  selected_fields = all_fields - combined_deferred
453
+ if not self.group_clauses:
454
+ selected_fields.update(col.name for col in table.primary_key)
521
455
  columns_to_select.extend([table.c[field] for field in selected_fields if field in table.c])
522
456
  else:
523
457
  columns_to_select.extend(table.c)
524
458
 
525
459
  # Add related table columns for select_related (only for select_related, not prefetch_related)
526
460
  if self.relationships and values_fields is None:
527
- related_columns = self._get_select_related_columns(table)
461
+ related_columns = self._get_select_related_columns(select_plan)
528
462
  columns_to_select.extend(related_columns)
529
463
 
530
464
  # Create the base query
531
- query = select(*columns_to_select) if columns_to_select else select(table)
465
+ query = (select(*columns_to_select) if columns_to_select else select(table)).select_from(table)
532
466
 
533
467
  # Add CTEs to query
534
468
  if cte_objects:
@@ -543,8 +477,9 @@ class QueryBuilder:
543
477
  query = query.join(join_table, join_condition)
544
478
 
545
479
  # Apply select_related joins (only for select_related, not prefetch_related)
546
- if self.relationships:
547
- query = self._apply_select_related_joins(query, table)
480
+ if select_plan:
481
+ for target, _, condition in select_plan.values():
482
+ query = query.outerjoin(target, condition)
548
483
 
549
484
  # Apply conditions
550
485
  if self.conditions:
@@ -578,12 +513,11 @@ class QueryBuilder:
578
513
  query = query.where(and_(*extra_conditions))
579
514
 
580
515
  # Apply distinct
581
- if self.distinct_fields:
582
- columns = [table.c[field] for field in self.distinct_fields if field in table.c]
583
- if columns:
584
- query = query.distinct(*columns)
585
- else:
586
- query = query.distinct()
516
+ if self.is_distinct:
517
+ unknown = [field for field in self.distinct_fields if field not in table.c]
518
+ if unknown:
519
+ raise QueryError(f"Unknown DISTINCT field(s): {unknown}")
520
+ query = query.distinct(*(table.c[field] for field in self.distinct_fields))
587
521
 
588
522
  # Apply annotations (values mode already selected the requested ones)
589
523
  if self.annotations and values_fields is None:
@@ -668,19 +602,16 @@ class QueryBuilder:
668
602
  order_clauses = []
669
603
  for field in self.ordering:
670
604
  if isinstance(field, str):
671
- if field.startswith("-"):
672
- field_name = field[1:]
673
- if field_name in table.c:
674
- if self.is_reversed:
675
- order_clauses.append(asc(table.c[field_name]))
676
- else:
677
- order_clauses.append(desc(table.c[field_name]))
605
+ descending = field.startswith("-")
606
+ field_name = field[1:] if descending else field
607
+ if field_name in table.c:
608
+ order_column = table.c[field_name]
609
+ elif field_name in self.annotations:
610
+ expr = self.annotations[field_name]
611
+ order_column = expr.resolve(table) if hasattr(expr, "resolve") else expr
678
612
  else:
679
- if field in table.c:
680
- if self.is_reversed:
681
- order_clauses.append(desc(table.c[field]))
682
- else:
683
- order_clauses.append(asc(table.c[field]))
613
+ continue
614
+ order_clauses.append(desc(order_column) if descending != self.is_reversed else asc(order_column))
684
615
  elif hasattr(field, "resolve"):
685
616
  order_clauses.append(field.resolve(table))
686
617
  else:
@@ -725,6 +656,7 @@ class QueryBuilder:
725
656
  new_builder.selected_fields = self.selected_fields.copy()
726
657
  new_builder.deferred_fields = self.deferred_fields.copy()
727
658
  new_builder.distinct_fields = self.distinct_fields.copy()
659
+ new_builder.is_distinct = self.is_distinct
728
660
  new_builder.annotations = self.annotations.copy()
729
661
  new_builder.group_clauses = self.group_clauses.copy()
730
662
  new_builder.having_conditions = self.having_conditions.copy()
@@ -24,7 +24,7 @@ class BaseDialect(ABC):
24
24
  def get_upsert_statement(
25
25
  self,
26
26
  table: sa.Table,
27
- data: dict[str, Any],
27
+ data: dict[str, Any] | list[dict[str, Any]],
28
28
  conflict_fields: list[str],
29
29
  update_fields: list[str],
30
30
  ) -> sa.sql.Insert:
@@ -66,7 +66,7 @@ class PostgreSQLDialect(BaseDialect):
66
66
  def get_upsert_statement(
67
67
  self,
68
68
  table: sa.Table,
69
- data: dict[str, Any],
69
+ data: dict[str, Any] | list[dict[str, Any]],
70
70
  conflict_fields: list[str],
71
71
  update_fields: list[str],
72
72
  ) -> sa.sql.Insert:
@@ -120,7 +120,7 @@ class MySQLDialect(BaseDialect):
120
120
  def get_upsert_statement(
121
121
  self,
122
122
  table: sa.Table,
123
- data: dict[str, Any],
123
+ data: dict[str, Any] | list[dict[str, Any]],
124
124
  conflict_fields: list[str],
125
125
  update_fields: list[str],
126
126
  ) -> sa.sql.Insert:
@@ -163,7 +163,7 @@ class SQLiteDialect(BaseDialect):
163
163
  def get_upsert_statement(
164
164
  self,
165
165
  table: sa.Table,
166
- data: dict[str, Any],
166
+ data: dict[str, Any] | list[dict[str, Any]],
167
167
  conflict_fields: list[str],
168
168
  update_fields: list[str],
169
169
  ) -> sa.sql.Insert: