sqlobjects 1.10.0__tar.gz → 2.0.0__tar.gz

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 2.0.0 (2026-08-19)
+
+### BREAKING CHANGE
+
+- annotate().group_by().all() with non-primary-key
+grouping and group_by().aggregate() now raise QueryError; both
+previously returned silently wrong results. QuerySet.create() removed
+(never wrote to the database) — use Model.objects.create().
+
+### Feat
+
+- **rules**: stamp installed rule files with the package version
+- **query**: strict GROUP BY semantics, values-mode aggregation, manager-only hints
+- **orm**: support SQLAlchemy expressions as write values
+- **bulk**: make BulkResult a sequence and guarantee insert RETURNING order
+- **session**: add join_ambient option to ctx_session and warn on nested sessions
+- **build**: ship py.typed marker so type checkers see the package as typed
+
 ## 1.10.0 (2026-07-24)
 
 ### Feat

{sqlobjects-1.10.0/sqlobjects.egg-info → sqlobjects-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.10.0
+Version: 2.0.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/docs/rules/01-database-session-guide.md

@@ -120,14 +120,27 @@ await init_db(
 - **Don't create sessions manually** (use context managers)
 
 ```python
-# Caution: Nested sessions use separate transactions
+# DANGER: Nested ctx_session opens a SECOND physical connection
 async with ctx_session() as session1:
     user = await User.objects.using(session1).create(username="alice")
     async with ctx_session() as session2:
-        # Nesting is safe (Token-based restore), but uses a separate transaction
-        # — session1 won't see session2's uncommitted changes and vice versa
+        # ContextVar restore is safe, but session2 is a separate physical
+        # connection with its own transaction:
+        # - session1 won't see session2's uncommitted changes and vice versa
+        # - if session2 writes a row that session1 holds a lock on, session2
+        #   blocks forever while session1 sits idle-in-transaction waiting for
+        #   this coroutine to return. The database deadlock detector CANNOT
+        #   see this cycle — it manifests as request timeouts, and session1's
+        #   locks block unrelated requests until then.
         await Post.objects.using(session2).create(author_id=user.id)
 
+# Good: join the ambient session when running inside a possibly-active transaction
+async with ctx_session(join_ambient=True) as session:
+    # Reuses the outer session if one exists (no second connection);
+    # creates a new one only at the top level. Lifecycle (commit/rollback/close)
+    # belongs to the outermost owner.
+    await Post.objects.using(session).create(author_id=user.id)
+
 # Bad: No transaction control
 user = await User.objects.create(username="alice")
 # If next operation fails, user is already created

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/docs/rules/03-query-operations-guide.md

@@ -24,7 +24,7 @@ users = await User.objects.filter(
 
 # Comparison operators
 adults = await User.objects.filter(User.age >= 18).all()
-recent = await User.objects.filter(User.created_at > datetime.now() - timedelta(days=7)).all()
+recent = await User.objects.filter(User.created_at > datetime.now(timezone.utc) - timedelta(days=7)).all()
 ```
 
 ### String Operations
@@ -113,18 +113,33 @@ users = await User.objects.annotate(
 
 ### Grouping
 
+Grouped aggregation returns **one row per group**, not model instances — use
+values-mode: list the grouping columns and aggregate aliases in `.values()`.
+
 ```python
-# Group by with aggregation
+# Group by with aggregation → list[dict], one dict per group
 dept_stats = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").all()
+).group_by("department").values("department", "user_count")
+# [{"department": "sales", "user_count": 10}, ...]
 
 # Having clause (filter groups)
 large_depts = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").having(func.count() > 10).all()
+).group_by("department").having(func.count() > 10).values("department", "user_count")
+
+# Grouping by the primary key is the one case where .all() stays valid:
+# each group is exactly one model row (e.g. counting related rows per user)
+users = await User.objects.annotate(post_count=Post.id.count()) \
+    .join(Post.__table__, User.id == Post.author_id, join_type="left") \
+    .group_by(User.id).all()
 ```
 
+**Do not** call `.all()` on a query grouped by a non-primary-key column — the
+selected model columns would fall outside GROUP BY, so SQLObjects raises
+`QueryError` instead of silently corrupting the aggregation (each group would
+collapse to a single row).
+
 ### Distinct
 
 ```python
@@ -408,7 +423,7 @@ from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, IntegerColumn, BooleanColumn
 from sqlobjects import Q
 from sqlobjects.expressions import func
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -426,10 +441,10 @@ admins_or_staff = await User.objects.filter(
     Q(User.department == "admin") | Q(User.department == "staff")
 ).all()
 
-# Aggregation
+# Aggregation (one row per group — see "Grouping" section)
 dept_stats = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").all()
+).group_by("department").values("department", "user_count")
 
 # Pagination with field selection
 users = await User.objects.only(

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/docs/rules/04-crud-operations-guide.md

@@ -87,6 +87,32 @@ await User.objects.bulk_delete(user_ids, id_field="id", batch_size=1000)
 await User.objects.filter(User.is_active == False).delete()
 ```
 
+### BulkResult (return_objects=True)
+
+`bulk_create` / `bulk_update` / `bulk_delete` return a plain `int` count by default.
+With `return_objects=True` they return a **`BulkResult`**, not a list:
+
+```python
+result = await User.objects.bulk_create(users_data, return_objects=True)
+
+result.objects        # list[User] — or list[dict] when return_fields is given
+result.success_count  # rows written successfully
+result.error_count    # rows that failed
+result.total_count    # input rows (success + failed)
+result.failed_records # list[FailedRecord] with .index/.data/.error per failure
+```
+
+Key semantics:
+
+- **Sequence protocol**: `len(result)`, `for obj in result`, and `result[i]` all
+  operate on `result.objects` (the successfully returned objects).
+- **Partial failure**: `len(result)` can be less than `result.total_count`.
+  Always read `success_count` / `failed_records` when `error_count > 0`.
+- **Order guarantee**: for `bulk_create`, `result.objects` order matches the
+  input rows order.
+- **`return_fields`**: when specified, `objects` contains dicts limited to those
+  fields instead of model instances.
+
 ### Cascade on Delete
 
 Both delete entry points detect and apply cascade behavior automatically:
@@ -126,9 +152,11 @@ users_data = [
 await User.objects.bulk_create(users_data, batch_size=500)
 
 # Bulk update with match fields
+# (bulk rows must be plain values — datetime.now(timezone.utc) here, never naive
+# local time; per-row SQL expressions are not supported in bulk operations)
 mappings = [
-    {"id": 1, "status": "active", "last_seen": datetime.now()},
-    {"id": 2, "status": "inactive", "last_seen": datetime.now()},
+    {"id": 1, "status": "active", "last_seen": datetime.now(timezone.utc)},
+    {"id": 2, "status": "inactive", "last_seen": datetime.now(timezone.utc)},
 ]
 await User.objects.bulk_update(mappings, match_fields=["id"])
 
@@ -137,6 +165,68 @@ user_ids = list(range(1, 1001))
 await User.objects.bulk_delete(user_ids, id_field="id", batch_size=1000)
 ```
 
+## SQL Expressions as Write Values
+
+`create()` and `QuerySet.update()` accept SQLAlchemy expressions as values —
+they are evaluated by the database, not serialized in Python:
+
+```python
+from sqlalchemy import func, text
+
+# Database clock, not application clock
+await Task.objects.filter(Task.id == task_id).update(claimed_at=func.now())
+
+# Relative updates (atomic, no read-modify-write race)
+await User.objects.filter(User.id == user_id).update(age=User.age + 1)
+
+# SQL fragments
+await Task.objects.filter(Task.id == task_id).update(
+    not_before=text("now() + interval '60 seconds'")  # PostgreSQL
+)
+
+# Also works in create()
+task = await Task.objects.create(name="reindex", scheduled_at=func.now())
+```
+
+Notes:
+
+- After `create()` with an expression value, the in-memory instance attribute
+  holds the expression object, not the database result — re-fetch the row if
+  you need the actual stored value.
+- **Bulk operations (`bulk_create` / `bulk_update`) do not support per-row SQL
+  expressions** — they execute with driver-level parameter batching, which
+  requires plain values.
+
+### Clock Discipline
+
+Any field that participates in SQL-side time comparison (scheduling, leases,
+debounce, `not_before` checks) **must use the database clock**, never
+`datetime.now()` from the application:
+
+```python
+# Bad: naive local time — breaks when app timezone != database timezone
+await Task.objects.filter(Task.id == tid).update(not_before=datetime.now())
+
+# Good: database clock — always consistent with SQL-side now() comparisons
+await Task.objects.filter(Task.id == tid).update(not_before=func.now())
+```
+
+A naive `datetime.now()` written from an application in UTC+8 compared against
+PostgreSQL's `now()` (UTC) schedules work 8 hours into the future.
+
+Which clock to use, by scenario:
+
+| Scenario | Correct clock | Example |
+|---|---|---|
+| SQL-compared writes (scheduling, leases, `not_before`) | database clock | `update(not_before=func.now())` |
+| Creation timestamps | database clock via default | `server_default=func.now()` |
+| Instance attributes / signal handlers (need a real value in memory) | aware app clock | `self.updated_at = datetime.now(timezone.utc)` |
+| Bulk operation rows (no per-row SQL expressions) | aware app clock | `{"last_seen": datetime.now(timezone.utc)}` |
+| Read-side window comparisons (relative windows computed in Python) | aware app clock | `filter(created_at >= datetime.now(timezone.utc) - timedelta(days=7))` |
+
+Never naive `datetime.now()` — in every scenario above the naive form breaks
+as soon as the application timezone differs from UTC.
+
 ## Best Practices
 
 ### ✅ Do
@@ -352,7 +442,7 @@ await User.objects.bulk_create(users_data, batch_size=1000)
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, BooleanColumn
 from sqlobjects.session import ctx_session
-from datetime import datetime
+from datetime import datetime, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/docs/rules/05-relationships-guide.md

@@ -132,7 +132,7 @@ posts = await Post.objects.select_related(Post.author).all()
 # Good: Filtered prefetch
 users = await User.objects.prefetch_related(
     recent_posts=Post.objects.filter(
-        Post.created_at >= datetime.now() - timedelta(days=7)
+        Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
     ).order_by('-created_at')
 ).all()
 ```
@@ -350,7 +350,7 @@ posts = await Post.objects.select_related("author").defer(
 # Filter prefetched relationships
 users = await User.objects.prefetch_related(
     recent_posts=Post.objects.filter(
-        Post.created_at >= datetime.now() - timedelta(days=7)
+        Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
     ).order_by('-created_at').limit(10)
 ).all()
 ```
@@ -439,7 +439,7 @@ class Post(ObjectModel):
 ```python
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, column, foreign_key, relationship, Related
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -478,7 +478,7 @@ posts = await Post.objects.select_related("author").prefetch_related("comments",
 # Advanced prefetch with filtering
 users = await User.objects.prefetch_related(
     recent_posts=Post.objects.filter(
-        Post.created_at >= datetime.now() - timedelta(days=7)
+        Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
     ).order_by('-created_at').limit(5)
 ).all()
 

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/docs/rules/06-validation-signals-guide.md

@@ -58,7 +58,7 @@ class User(ObjectModel):
 ```python
 from sqlobjects.model import ObjectModel
 from sqlobjects.signals import SignalContext
-from datetime import datetime
+from datetime import datetime, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -69,7 +69,7 @@ class User(ObjectModel):
     # Universal save signals (always triggered)
     async def before_save(self, context: SignalContext):
         """Called before any save operation"""
-        self.updated_at = datetime.now()
+        self.updated_at = datetime.now(timezone.utc)
     
     async def after_save(self, context: SignalContext):
         """Called after any save operation"""
@@ -78,7 +78,7 @@ class User(ObjectModel):
     # Operation-specific signals (triggered based on detected operation)
     async def before_create(self, context: SignalContext):
         """Only triggered for CREATE operations"""
-        self.created_at = datetime.now()
+        self.created_at = datetime.now(timezone.utc)
     
     async def before_update(self, context: SignalContext):
         """Only triggered for UPDATE operations"""
@@ -162,7 +162,7 @@ class User(ObjectModel):
     
     # Good: Fast signal operations
     async def before_save(self, context: SignalContext):
-        self.updated_at = datetime.now()  # Fast
+        self.updated_at = datetime.now(timezone.utc)  # Fast
     
     # Good: Non-critical operations with error handling
     async def after_create(self, context: SignalContext):
@@ -198,7 +198,7 @@ async def before_save(self, context: SignalContext):
 
 # Good: Keep before_save fast, use after_save for heavy operations
 async def before_save(self, context: SignalContext):
-    self.updated_at = datetime.now()  # Fast
+    self.updated_at = datetime.now(timezone.utc)  # Fast
 
 async def after_save(self, context: SignalContext):
     asyncio.create_task(self.process_large_file())  # Background task
@@ -302,7 +302,7 @@ async def after_create(self, context: SignalContext):
 # Background tasks for non-critical operations
 async def after_save(self, context: SignalContext):
     # Critical operations (blocking)
-    self.updated_at = datetime.now()
+    self.updated_at = datetime.now(timezone.utc)
     
     # Non-critical operations (background)
     if not context.is_bulk:
@@ -390,7 +390,7 @@ from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, column, StringColumn, IntegerColumn, BooleanColumn
 from sqlobjects.signals import SignalContext
 from sqlobjects.exceptions import ValidationError
-from datetime import datetime
+from datetime import datetime, timezone
 import asyncio
 
 # Custom validators
@@ -420,10 +420,10 @@ class User(ObjectModel):
     
     # Instance signals
     async def before_save(self, context: SignalContext):
-        self.updated_at = datetime.now()
+        self.updated_at = datetime.now(timezone.utc)
     
     async def before_create(self, context: SignalContext):
-        self.created_at = datetime.now()
+        self.created_at = datetime.now(timezone.utc)
     
     async def after_create(self, context: SignalContext):
         try:

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/docs/rules/README.md

@@ -12,6 +12,31 @@ Best practices and usage patterns for SQLObjects, optimized for AI coding assist
 - **[06. Validation & Signals Guide](06-validation-signals-guide.md)** - Data validation and lifecycle hooks
 - **[07. Performance Guide](07-performance-guide.md)** - Optimization techniques and best practices
 
+## Method Ownership Matrix
+
+The single most common mistake is calling a manager-only method on a QuerySet
+(or vice versa). `Model.objects` is the **manager**; `filter()` returns a
+**QuerySet**. They own different methods:
+
+| Operation | Manager (`Model.objects`) | QuerySet (`.filter(...)`) |
+|---|---|---|
+| Create | `create()`, `get_or_create()`, `update_or_create()` | — |
+| Bulk write | `bulk_create()`, `bulk_update()`, `bulk_delete()` | — |
+| Whole-table write | `delete_all()`, `update_all(**values)` | — |
+| Filtered write | — | `update(**values)`, `delete()` |
+| Read | `get()`, `all()`, `first()`, `last()`, `in_bulk()` | `get()`, `all()`, `first()`, `last()` |
+| Refine | `filter()`, `exclude()` (returns QuerySet) | `filter()`, `exclude()`, `order_by()`, `limit()`, `offset()` |
+| Projection | `values()`, `values_list()`, `only()`, `defer()` | `values()`, `values_list()`, `only()`, `defer()` |
+| Aggregate | `count()`, `aggregate()`, `annotate()`, `group_by()`, `having()` | `count()`, `aggregate()`, `annotate()`, `group_by()`, `having()` |
+
+Rules of thumb:
+
+- `filter(...).delete_all()` / `filter(...).update_all()` **do not exist** — a
+  filtered write is `filter(...).delete()` / `filter(...).update(**values)`.
+- `bulk_*` operate on explicit row data, so they live on the manager only.
+- Calling a manager-only method on a QuerySet raises `AttributeError` with a
+  hint pointing to the correct method.
+
 ## Purpose
 
 These rules provide concise, actionable guidance for using SQLObjects effectively. Each guide includes:
@@ -57,4 +82,10 @@ sqlobjects-install-rules kiro     # For Kiro
 
 ## Version
 
-These rules are for SQLObjects 1.0+
+`sqlobjects-install-rules` stamps each installed file with the exact package
+version it was generated from — trust that stamp over this line. Version-
+sensitive behaviors to watch: grouped aggregation (`annotate` + `group_by`)
+raises `QueryError` on out-of-group column selection and returns rows via
+`.values()` since 2.0, and `aggregate()` combined with `group_by()` also
+raises `QueryError` since 2.0; earlier versions silently expanded GROUP BY
+(or dropped it entirely for `aggregate()`) and returned wrong results.

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.10.0"
+version = "2.0.0"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/sqlobjects/__init__.py

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

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/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-1.10.0 → sqlobjects-2.0.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-1.10.0 → sqlobjects-2.0.0}/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-1.10.0 → sqlobjects-2.0.0}/sqlobjects/mixins.py

@@ -266,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-1.10.0 → sqlobjects-2.0.0}/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-1.10.0 → sqlobjects-2.0.0}/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-1.10.0 → sqlobjects-2.0.0}/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-1.10.0 → sqlobjects-2.0.0}/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.
@@ -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-1.10.0 → sqlobjects-2.0.0}/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

{sqlobjects-1.10.0 → sqlobjects-2.0.0/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.10.0
+Version: 2.0.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.10.0 → sqlobjects-2.0.0}/sqlobjects.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ sqlobjects/exceptions.py
 sqlobjects/metadata.py
 sqlobjects/mixins.py
 sqlobjects/model.py
+sqlobjects/py.typed
 sqlobjects/queryset.py
 sqlobjects/session.py
 sqlobjects/signals.py