sqlobjects 1.9.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

sqlobjects/__init__.py

@@ -19,7 +19,7 @@ from .queryset import Q, QuerySet
 from .sql_logging import ObjectLogger, get_caller_frame
 
 
-__version__ = "0.3.0"
+__version__ = "2.0.0"
 
 __all__ = [
     # Core classes

sqlobjects/_install_rules.py

@@ -5,6 +5,16 @@ import sys
 from pathlib import Path
 
 
+def _get_package_version() -> str:
+    """Get the installed sqlobjects version."""
+    try:
+        from . import __version__
+
+        return __version__
+    except Exception:
+        return "unknown"
+
+
 def find_project_root() -> Path:
     """Find project root by looking for common markers."""
     current = Path.cwd()
@@ -73,13 +83,19 @@ def install_rules(target_name: str, target_dir: Path | None = None) -> bool:
         print(f"Error: Rules directory not found at {rules_dir}", file=sys.stderr)
         return False
 
-    # Create target directory and copy files
+    # Create target directory and copy files, stamping the package version so
+    # AI assistants reading the rules know which behaviors they document
     try:
         target_dir.mkdir(parents=True, exist_ok=True)
 
+        version = _get_package_version()
+        stamp = f"<!-- Generated for SQLObjects {version} — behaviors documented here match this version -->\n\n"
+
         copied_count = 0
         for file in rules_dir.glob("*.md"):
-            shutil.copy2(file, target_dir / file.name)
+            content = file.read_text(encoding="utf-8")
+            (target_dir / file.name).write_text(stamp + content, encoding="utf-8")
+            shutil.copystat(file, target_dir / file.name)
             copied_count += 1
 
         if copied_count > 0:

sqlobjects/exceptions.py

@@ -20,6 +20,7 @@ __all__ = [
     "ConfigurationError",
     "DeferredFieldError",
     "PrimaryKeyError",
+    "QueryError",
     "SQLError",
     "OperationalError",
     "DataError",
@@ -400,6 +401,23 @@ class PrimaryKeyError(SQLObjectsError):
         super().__init__(message)
 
 
+class QueryError(SQLObjectsError):
+    """Raised when a query is constructed in a way that cannot be executed safely.
+
+    SQLObjects raises this instead of silently rewriting the query semantics —
+    for example when annotated GROUP BY queries select columns outside the
+    grouping columns, which would degenerate every group to a single row.
+
+    Examples:
+        >>> try:
+        ...     await User.objects.annotate(cnt=func.count()).group_by("department").all()
+        ... except QueryError:
+        ...     print("Use .values()/.only() with the grouping columns instead")
+    """
+
+    pass
+
+
 class SQLError(SQLObjectsError):
     """Base class for SQLAlchemy operation errors.
 

sqlobjects/expressions/cte.py

@@ -33,7 +33,7 @@ class CTEExpression:
             >>> base = Employee.objects.filter(Employee.manager_id.is_(None)).cte("hierarchy", recursive=True)
             >>> recursive = Employee.objects.join(base, Employee.manager_id == base.c.id)
             >>> hierarchy = base.union_all(recursive)
-            >>> all_employees = await Employee.objects.with_cte(hierarchy).select_from(hierarchy).all()
+            >>> all_employees = await Employee.objects.with_cte(hierarchy).all()
     """
 
     def __init__(self, queryset: QuerySet, name: str, recursive: bool = False):

sqlobjects/expressions/terminal.py

@@ -3,8 +3,6 @@
 from datetime import date, datetime
 from typing import TYPE_CHECKING, Any, TypeVar
 
-from sqlalchemy import and_, select
-
 from .base import QueryExpression
 
 
@@ -173,23 +171,19 @@ class ValuesExpression(QueryExpression[list[dict[str, Any]]]):
 
     def get_query(self):
         """Return SQLAlchemy query object."""
-        return self._builder.build(self._builder.model_class.get_table())
+        return self._builder.build(self._builder.model_class.get_table(), values_fields=self._fields)
 
     async def execute(self) -> list[dict[str, Any]]:
         if not self._executor:
             raise RuntimeError("No executor available for values execution")
-        query = self._builder.build(self._builder.model_class.get_table())
-        result = await self._executor.execute(query, "values", fields=self._fields)
+        query = self.get_query()
+        result = await self._executor.execute(query, "values", fields=self._fields, prebuilt=True)
         if isinstance(result, list):
             return [dict(zip(self._fields, row, strict=False)) for row in result]
         return []
 
     def get_sql(self) -> str:
-        table = self._builder.model_class.get_table()
-        columns = [table.c[field] for field in self._fields if field in table.c]
-        query = select(*columns).select_from(table)
-        if hasattr(self._builder, "conditions") and self._builder.conditions:
-            query = query.where(and_(*self._builder.conditions))
+        query = self.get_query()
         return str(query.compile(compile_kwargs={"literal_binds": True}))
 
 
@@ -204,13 +198,13 @@ class ValuesListExpression(QueryExpression[list[Any] | list[tuple[Any, ...]]]):
 
     def get_query(self):
         """Return SQLAlchemy query object."""
-        return self._builder.build(self._builder.model_class.get_table())
+        return self._builder.build(self._builder.model_class.get_table(), values_fields=self._fields)
 
     async def execute(self) -> list[Any] | list[tuple[Any, ...]]:
         if not self._executor:
             raise RuntimeError("No executor available for values_list execution")
-        query = self._builder.build(self._builder.model_class.get_table())
-        result = await self._executor.execute(query, "values_list", fields=list(self._fields))
+        query = self.get_query()
+        result = await self._executor.execute(query, "values_list", fields=list(self._fields), prebuilt=True)
         if isinstance(result, list):
             if self._flat and len(self._fields) == 1:
                 return [row[0] for row in result]
@@ -218,7 +212,7 @@ class ValuesListExpression(QueryExpression[list[Any] | list[tuple[Any, ...]]]):
         return []
 
     def get_sql(self) -> str:
-        query = self._builder.build(self._builder.model_class.get_table())
+        query = self.get_query()
         return str(query.compile(compile_kwargs={"literal_binds": True}))
 
 

sqlobjects/mixins.py

@@ -136,6 +136,14 @@ class BaseMixin:
         if not hasattr(self, "_state_manager"):
             self._state_manager = _StateManager()
 
+    def get_dirty_fields(self) -> set[str]:
+        """Get fields modified since the last save or database load.
+
+        Returns:
+            Set of field names with unsaved changes
+        """
+        return self._state_manager.get_dirty_fields().copy()
+
     @classmethod
     def get_table(cls) -> Table:
         """Get SQLAlchemy Core Table definition.
@@ -258,6 +266,12 @@ class ValidationMixin(PrimaryKeyMixin):
             )
             if validators:
                 value = getattr(self, field_name, None)
+                # SQL expressions (func.now(), text(...), column arithmetic) are
+                # evaluated by the database — Python-side validators don't apply
+                from sqlalchemy.sql import ClauseElement
+
+                if isinstance(value, ClauseElement):
+                    return
                 try:
                     from .validators import validate_field_value
 

sqlobjects/objects/bulk.py

@@ -4,6 +4,7 @@ This module provides bulk operations functionality and transaction control,
 merged from the original bulk_transaction.py module.
 """
 
+from collections.abc import Iterator
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Callable, Generic, TypeVar
@@ -82,7 +83,16 @@ class FailedRecord:
 
 @dataclass
 class BulkResult(Generic[T]):
-    """Result object for bulk operations with detailed information."""
+    """Result object for bulk operations with detailed information.
+
+    Acts as a sequence over ``objects``: iteration, indexing and ``len()``
+    all operate on the successfully returned objects. Use ``total_count`` /
+    ``success_count`` / ``error_count`` for operation statistics — on partial
+    failure ``len(result)`` and ``total_count`` differ.
+
+    For insert operations the order of ``objects`` matches the order of the
+    input rows (RETURNING is sorted by parameter order).
+    """
 
     success_count: int
     error_count: int
@@ -111,8 +121,16 @@ class BulkResult(Generic[T]):
         return 0 < self.success_count < self.total_count
 
     def __len__(self) -> int:
-        """Return total count for len() support."""
-        return self.total_count
+        """Return the number of returned objects (see ``total_count`` for input size)."""
+        return len(self.objects)
+
+    def __iter__(self) -> Iterator[T | dict[str, Any]]:
+        """Iterate over the returned objects."""
+        return iter(self.objects)
+
+    def __getitem__(self, index):
+        """Index into the returned objects."""
+        return self.objects[index]
 
 
 class BulkTransactionManager:
@@ -269,7 +287,11 @@ class BulkOperationHandler:
         exec_session = session or self.session
 
         if return_columns and self.supports_returning(operation):
-            stmt_with_returning = stmt.returning(*return_columns)
+            if operation == "insert":
+                # Guarantee RETURNING row order matches input row order for executemany
+                stmt_with_returning = stmt.returning(*return_columns, sort_by_parameter_order=True)
+            else:
+                stmt_with_returning = stmt.returning(*return_columns)
             # For INSERT operations, use the data directly as parameters
             if operation == "insert" and isinstance(parameters, list):
                 result = await exec_session.execute(stmt_with_returning, parameters)

sqlobjects/queries/builder.py

@@ -11,6 +11,8 @@ from sqlalchemy import (
 )
 from sqlalchemy.sql.selectable import Subquery
 
+from ..exceptions import QueryError
+
 
 # Export classes for use in other modules
 __all__ = ["QueryBuilder"]
@@ -447,11 +449,14 @@ class QueryBuilder:
 
         return related_columns
 
-    def build(self, table):
+    def build(self, table, values_fields: tuple[str, ...] | None = None):
         """Build final SQLAlchemy query object from accumulated clauses.
 
         Args:
             table: SQLAlchemy Table object to query
+            values_fields: When given (values()/values_list() mode), select exactly
+                these fields in order. Each name must resolve to a table column,
+                an annotation alias, or an extra column alias.
 
         Returns:
             SQLAlchemy Select object ready for execution
@@ -479,8 +484,34 @@ class QueryBuilder:
         # Collect all columns to select (base table + related tables)
         columns_to_select = []
 
+        if values_fields is not None:
+            # values()/values_list() mode: select exactly the requested fields in
+            # order so result rows align with the field names positionally
+            unknown = [
+                f
+                for f in values_fields
+                if f not in table.c and f not in self.annotations and f not in self.extra_columns
+            ]
+            if unknown:
+                raise QueryError(
+                    f"Unknown field(s) in values()/values_list(): {unknown}. "
+                    "Each field must be a model column, an annotation alias, or an extra() column alias."
+                )
+            for field_name in values_fields:
+                if field_name in table.c:
+                    columns_to_select.append(table.c[field_name])
+                elif field_name in self.annotations:
+                    expr = self.annotations[field_name]
+                    resolved = expr.resolve(table) if hasattr(expr, "resolve") else expr
+                    columns_to_select.append(resolved.label(field_name))
+                else:
+                    sql = self.extra_columns[field_name]
+                    if self.extra_params:
+                        columns_to_select.append(text(sql).bindparams(**self.extra_params).label(field_name))
+                    else:
+                        columns_to_select.append(text(sql).label(field_name))
         # Handle field selection (only() method)
-        if self.selected_fields:
+        elif self.selected_fields:
             columns_to_select.extend([table.c[field] for field in self.selected_fields if field in table.c])
         elif self.deferred_fields or auto_deferred_fields:
             # For defer() or auto-deferred fields, select all fields except deferred ones
@@ -492,7 +523,7 @@ class QueryBuilder:
             columns_to_select.extend(table.c)
 
         # Add related table columns for select_related (only for select_related, not prefetch_related)
-        if self.relationships:
+        if self.relationships and values_fields is None:
             related_columns = self._get_select_related_columns(table)
             columns_to_select.extend(related_columns)
 
@@ -554,8 +585,8 @@ class QueryBuilder:
             else:
                 query = query.distinct()
 
-        # Apply annotations
-        if self.annotations:
+        # Apply annotations (values mode already selected the requested ones)
+        if self.annotations and values_fields is None:
             annotation_columns = []
             for alias, expr in self.annotations.items():
                 if hasattr(expr, "resolve"):
@@ -564,8 +595,8 @@ class QueryBuilder:
                     annotation_columns.append(expr.label(alias))
             query = query.add_columns(*annotation_columns)
 
-        # Apply extra columns
-        if self.extra_columns:
+        # Apply extra columns (values mode already selected the requested ones)
+        if self.extra_columns and values_fields is None:
             extra_cols = []
             for alias, sql in self.extra_columns.items():
                 if self.extra_params:
@@ -577,34 +608,48 @@ class QueryBuilder:
         # Apply group by
         if self.group_clauses:
             group_columns = []
+            group_names = set()
             for field in self.group_clauses:
                 if isinstance(field, str) and field in table.c:
                     group_columns.append(table.c[field])
+                    group_names.add(field)
                 elif hasattr(field, "resolve") and not isinstance(field, str):
-                    group_columns.append(field.resolve(table))
+                    resolved = field.resolve(table)
+                    group_columns.append(resolved)
+                    if getattr(resolved, "name", None):
+                        group_names.add(resolved.name)
                 else:
                     group_columns.append(field)
-
-            # For PostgreSQL compatibility, include all non-aggregated columns in GROUP BY
+                    field_name = getattr(field, "name", None)
+                    if field_name:
+                        group_names.add(field_name)
+
+            # Grouped aggregation must not select columns outside GROUP BY.
+            # Previous versions silently added the selected columns to GROUP BY
+            # "for PostgreSQL compatibility", which degenerated every group to a
+            # single row and produced wrong aggregate values. Grouping by the
+            # full primary key is exempt: every column of the table is
+            # functionally dependent on it, so one group == one model row.
             if self.annotations:
-                # Add all base table columns that are being selected
-                if self.selected_fields:
-                    for field in self.selected_fields:
-                        if field in table.c and table.c[field] not in group_columns:
-                            group_columns.append(table.c[field])
-                elif not self.deferred_fields:
-                    # If no specific fields selected and no deferred fields, add all columns
-                    for column in table.c:
-                        if column not in group_columns:
-                            group_columns.append(column)
+                pk_names = {col.name for col in table.primary_key.columns}
+                if values_fields is not None:
+                    selected_names = {f for f in values_fields if f in table.c}
+                elif self.selected_fields:
+                    selected_names = {f for f in self.selected_fields if f in table.c}
                 else:
-                    # Add non-deferred columns
-                    all_fields = set(table.columns.keys())
-                    combined_deferred = self.deferred_fields | auto_deferred_fields
-                    selected_fields = all_fields - combined_deferred
-                    for field in selected_fields:
-                        if field in table.c and table.c[field] not in group_columns:
-                            group_columns.append(table.c[field])
+                    selected_names = set(table.columns.keys()) - self.deferred_fields - auto_deferred_fields
+
+                grouped_by_pk = bool(pk_names) and pk_names <= group_names
+                extra_selected = selected_names - group_names
+                if not grouped_by_pk and extra_selected:
+                    raise QueryError(
+                        f"column(s) {sorted(extra_selected)} are selected but not in GROUP BY. "
+                        "SQLObjects no longer adds selected columns to GROUP BY silently — "
+                        "that would collapse each group to a single row and corrupt aggregates. "
+                        "Use .values(*group_fields, *aggregate_aliases) for aggregation rows, "
+                        ".only(*group_fields) to hydrate partial instances, "
+                        "or group by the primary key to aggregate per model row."
+                    )
 
             query = query.group_by(*group_columns)
 

sqlobjects/queries/executor.py

@@ -191,6 +191,10 @@ class QueryExecutor:
                 delete_query = delete_query.where(query.whereclause)
             return delete_query
         elif query_type in ("values", "values_list"):
+            if kwargs.get("prebuilt"):
+                # Query was already built with the exact requested fields
+                # (including annotations and GROUP BY) — execute as-is
+                return query
             fields = kwargs.get("fields", [])
             if fields:
                 table = from_table

sqlobjects/queryset.py

@@ -1,7 +1,7 @@
 import re
 from collections.abc import AsyncGenerator
 from datetime import date, datetime
-from typing import Any, Generic, Literal, TypeVar, Union
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeVar, Union
 
 from sqlalchemy import (
     BinaryExpression,
@@ -237,6 +237,30 @@ class QuerySet(Generic[T]):
             ordering = getattr(self._model_class, "_default_ordering", [])
             self._builder = self._builder.add_ordering(*ordering)
 
+    # Manager-only method names mapped to their QuerySet equivalent (None if no equivalent)
+    _MANAGER_ONLY_METHODS: ClassVar[dict[str, str | None]] = {
+        "delete_all": "delete()",
+        "update_all": "update(**values)",
+        "bulk_create": None,
+        "bulk_update": None,
+        "bulk_delete": None,
+        "create": None,
+        "get_or_create": None,
+        "update_or_create": None,
+        "in_bulk": None,
+    }
+
+    if not TYPE_CHECKING:
+        # Hidden from type checkers so unknown attributes still fail static
+        # analysis; at runtime it turns bare AttributeErrors on manager-only
+        # methods into a hint pointing at the correct API
+        def __getattr__(self, name: str):
+            if name in self._MANAGER_ONLY_METHODS:
+                equivalent = self._MANAGER_ONLY_METHODS[name]
+                hint = f"; for a filtered queryset use .{equivalent}" if equivalent else ""
+                raise AttributeError(f"'{name}' is defined on Model.objects (manager), not on QuerySet{hint}")
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
     @staticmethod
     def _get_field_name(field) -> str:
         """Extract field name from various field types.
@@ -762,7 +786,7 @@ class QuerySet(Generic[T]):
             hierarchy = base.union_all(recursive_part)
             all_employees = await Employee.objects.with_cte(
                 hierarchy
-            ).select_from(hierarchy).all()
+            ).all()
         """
         return CTEExpression(self, name, recursive)
 
@@ -799,20 +823,35 @@ class QuerySet(Generic[T]):
     def aggregate(self, **kwargs) -> AggregateExpression:
         """Create aggregation expression that can be executed or used as subquery.
 
+        Returns a single row aggregated over all matching rows. Incompatible
+        with group_by() — for per-group aggregation use
+        ``annotate(...).group_by(...).values(*group_fields, *aliases)``.
+
         Args:
             **kwargs: Aggregation expressions with aliases
 
         Returns:
             AggregateExpression that can be awaited or used in comparisons
 
+        Raises:
+            QueryError: If the queryset has GROUP BY clauses
+
         Examples:
             # Direct execution
             stats = await User.objects.aggregate(avg_age=User.age.avg())
 
             # Use as subquery condition
-            avg_age = User.objects.aggregate(User.age.avg())
+            avg_age = User.objects.aggregate(avg_age=User.age.avg())
             older_users = await User.objects.filter(User.age > avg_age).all()
         """
+        if self._builder.group_clauses:
+            from .exceptions import QueryError
+
+            raise QueryError(
+                "aggregate() returns a single row and ignores GROUP BY. "
+                "Use .annotate(...).group_by(...).values(*group_fields, *aggregate_aliases) "
+                "for per-group aggregation."
+            )
         return AggregateExpression(self._builder, kwargs, self._executor)
 
     def count(self) -> CountExpression:
@@ -1199,19 +1238,6 @@ class QuerySet(Generic[T]):
     # Data Operations Methods - Create, update, and delete data
     # ========================================
 
-    async def create(self, validate: bool = True, **kwargs) -> T:
-        """Create new object with given field values."""
-        # Create instance for validation
-        instance = self._model_class.from_dict(kwargs, validate=validate)  # type: ignore[reportAttributeAccessIssue]
-        if validate and hasattr(instance, "validate_all"):
-            validate_method = getattr(instance, "validate_all", None)
-            if validate_method:
-                validate_method()
-
-        # Actual insertion would be implemented here
-        # For now, return the created instance (simplified)
-        return instance
-
     @emit_signals(Operation.UPDATE, is_bulk=True)
     async def update(self, **values) -> int:
         """Perform bulk update on objects matching query conditions."""

sqlobjects/session.py

@@ -1,4 +1,5 @@
 import contextvars
+import logging
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from typing import Any
@@ -13,6 +14,8 @@ from .exceptions import convert_sqlalchemy_error
 
 __all__ = ["AsyncSession", "ctx_session", "ctx_sessions", "get_session", "has_session"]
 
+logger = logging.getLogger("sqlobjects.session")
+
 # Explicit session management (highest priority)
 _explicit_sessions: contextvars.ContextVar[dict[str, "AsyncSession"]] = contextvars.ContextVar("explicit_sessions")
 
@@ -298,7 +301,7 @@ class _SessionContextManager:
 
 
 @asynccontextmanager
-async def ctx_session(db_name: str | None = None) -> AsyncGenerator[AsyncSession, None]:
+async def ctx_session(db_name: str | None = None, *, join_ambient: bool = False) -> AsyncGenerator[AsyncSession, None]:
     """Get async context manager for single database transactional session.
 
     Creates a transactional session with manual commit control (auto_commit=False).
@@ -306,11 +309,31 @@ async def ctx_session(db_name: str | None = None) -> AsyncGenerator[AsyncSession
 
     Args:
         db_name: Database name (uses default database if None)
+        join_ambient: If True and an explicit session already exists in the current
+            context, reuse it instead of creating a new one. The ambient session's
+            lifecycle (commit/rollback/close) stays with its outer owner; exceptions
+            propagate to the owner for rollback. This avoids a second physical
+            connection whose row locks would deadlock against the outer transaction
+            in a way the database deadlock detector cannot see.
 
     Yields:
         AsyncSession: Transactional session with manual commit control
     """
     name = db_name or get_default()
+
+    if join_ambient and has_session(name):
+        yield get_session(name, readonly=False)
+        return
+
+    if has_session(name):
+        logger.warning(
+            "ctx_session(%r) is creating a new session while an ambient session already exists "
+            "in this context. The two sessions use separate physical connections; writes to rows "
+            "locked by the outer transaction will block undetectably. "
+            "Pass join_ambient=True to reuse the ambient session.",
+            name,
+        )
+
     session = AsyncSession(name, readonly=False, auto_commit=False)
 
     # Set as explicit session in context, save token for nested restore