sqlobjects 1.3.0__tar.gz → 1.5.0__tar.gz

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 1.5.0 (2026-03-16)
+
+### Feat
+
+- **cascade**: unify cascade strategy with auto-detection for Model.delete()
+
+## 1.4.0 (2026-03-11)
+
+### Feat
+
+- **session**: fix nested ctx_session() and add ASGI/FastAPI integration
+
 ## 1.3.0 (2026-03-10)
 
 ### Feat

{sqlobjects-1.3.0/sqlobjects.egg-info → sqlobjects-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.3.0
+Version: 1.5.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.3.0 → sqlobjects-1.5.0}/docs/rules/01-database-session-guide.md

@@ -71,6 +71,21 @@ async with ctx_session() as session:
 user = await User.objects.using("analytics").create(username="test")
 ```
 
+### Session Availability Check
+
+```python
+from sqlobjects.session import has_session
+
+# Check if an explicit session is active
+if has_session():
+    # Inside a ctx_session() block — use the existing session
+    pass
+
+# Check for a specific database
+if has_session("analytics"):
+    pass
+```
+
 ## Best Practices
 
 ### ✅ Do
@@ -105,11 +120,12 @@ await init_db(
 - **Don't create sessions manually** (use context managers)
 
 ```python
-# Bad: Mixing sessions
+# Caution: Nested sessions use separate transactions
 async with ctx_session() as session1:
     user = await User.objects.using(session1).create(username="alice")
     async with ctx_session() as session2:
-        # Different session - may cause issues
+        # Nesting is safe (Token-based restore), but uses a separate transaction
+        # — session1 won't see session2's uncommitted changes and vice versa
         await Post.objects.using(session2).create(author_id=user.id)
 
 # Bad: No transaction control
@@ -251,24 +267,24 @@ async def main():
         "main": {"url": "postgresql://localhost/main", "pool_size": 20},
         "analytics": {"url": "sqlite:///analytics.db"}
     }, default="main")
-    
+
     await create_tables(ObjectModel, "main")
     await create_tables(ObjectModel, "analytics")
-    
+
     # Single database transaction
     async with ctx_session() as session:
         user = await User.objects.using(session).create(
             username="alice",
             email="alice@example.com"
         )
-    
+
     # Multi-database transaction
     async with ctx_sessions("main", "analytics") as sessions:
         user = await User.objects.using(sessions["main"]).get(User.username == "alice")
         await Log.objects.using(sessions["analytics"]).create(
             message=f"User {user.username} logged in"
         )
-    
+
     # Cleanup
     await close_all_dbs()
 
@@ -276,3 +292,41 @@ async def main():
 import asyncio
 asyncio.run(main())
 ```
+
+## Web Framework Integration
+
+### ASGI Middleware
+
+Use `SessionMiddleware` for automatic request-scoped session management in any ASGI framework (FastAPI, Starlette, etc.):
+
+```python
+from fastapi import FastAPI
+from sqlobjects.contrib.asgi import SessionMiddleware
+
+app = FastAPI()
+app.add_middleware(SessionMiddleware)
+# Each request gets an auto-managed session: commit on success, rollback on error
+
+# Optional: target a specific database or use readonly mode
+app.add_middleware(SessionMiddleware, db_name="analytics", readonly=True)
+```
+
+### FastAPI Dependency Injection
+
+Use `get_db_session` for explicit session access in route handlers:
+
+```python
+from fastapi import Depends
+from sqlobjects.contrib.fastapi import get_db_session
+from sqlobjects.session import AsyncSession
+
+@app.post("/users")
+async def create_user(session: AsyncSession = Depends(get_db_session)):
+    user = await User.objects.using(session).create(username="alice")
+    return {"id": user.id}
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int, session: AsyncSession = Depends(get_db_session)):
+    user = await User.objects.using(session).get(User.id == user_id)
+    return {"username": user.username}
+```

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/docs/rules/03-query-operations-guide.md

@@ -204,6 +204,47 @@ active_users = User.objects.filter(User.is_active == True).subquery("active_user
 posts = await Post.objects.join(active_users, Post.author_id == active_users.c.id).all()
 ```
 
+### Window Functions
+
+```python
+from sqlobjects.expressions import func
+
+# Window functions are used via annotate() + func.xxx().over()
+users = await User.objects.annotate(
+    row_num=func.row_number().over(order_by=[User.created_at])
+).all()
+
+# Ranking with partitions
+users = await User.objects.annotate(
+    dept_rank=func.rank().over(
+        partition_by=[User.department],
+        order_by=[(User.salary, 'desc')]
+    )
+).all()
+
+# LAG/LEAD for adjacent row access
+users = await User.objects.annotate(
+    prev_salary=func.lag(User.salary, 1).over(order_by=[User.created_at])
+).all()
+
+# Available: row_number(), rank(), dense_rank(), percent_rank(),
+#            ntile(n), lag(), lead(), first_value(), last_value(), nth_value()
+```
+
+### CTE (Common Table Expressions)
+
+```python
+# Basic CTE: define a reusable named subquery
+adults = User.objects.filter(User.age >= 18).cte("adults")
+result = await User.objects.with_cte(adults).filter(adults.c.age < 30).all()
+
+# Recursive CTE: hierarchical queries
+base = Employee.objects.filter(Employee.manager_id.is_(None)).cte("hierarchy", recursive=True)
+recursive_part = Employee.objects.join(base, Employee.manager_id == base.c.id)
+hierarchy = base.union_all(recursive_part)
+all_employees = await Employee.objects.with_cte(hierarchy).select_from(hierarchy).all()
+```
+
 ### Manual Joins
 
 ```python

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/docs/rules/05-relationships-guide.md

@@ -19,7 +19,9 @@ from sqlobjects.fields import Column, StringColumn, foreign_key, relationship, R
 # One-to-Many (Foreign Key)
 class Post(ObjectModel):
     title: Column[str] = StringColumn(length=200)
-    author_id: Column[int] = foreign_key("users.id")
+    # Both class name and table name are supported:
+    author_id: Column[int] = foreign_key("User.id")    # class name (auto-resolved)
+    # author_id: Column[int] = foreign_key("users.id") # table name (also works)
     author: Related["User"] = relationship("User", back_populates="posts")
 
 class User(ObjectModel):

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.3.0"
+version = "1.5.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.3.0 → sqlobjects-1.5.0}/sqlobjects/cascade.py

@@ -28,6 +28,7 @@ __all__ = [
     "normalize_onupdate",
     "normalize_cascade",
     "has_cascade_delete_relations",
+    "has_delete_signals",
 ]
 
 
@@ -130,6 +131,30 @@ def has_cascade_delete_relations(model_class) -> bool:
     return False
 
 
+def has_delete_signals(model_class) -> bool:
+    """Check if model class has delete signal handlers defined.
+
+    Args:
+        model_class: Model class to check
+
+    Returns:
+        True if model has before_delete/after_delete handlers, False otherwise
+    """
+    from .signals import SignalMixin
+
+    if not issubclass(model_class, SignalMixin):
+        return False
+
+    for method_name in ("before_delete", "after_delete"):
+        method = getattr(model_class, method_name, None)
+        if method is None:
+            continue
+        # Must be defined on the model itself, not inherited from SignalMixin
+        if method_name in model_class.__dict__:
+            return True
+    return False
+
+
 def normalize_cascade(cascade: CascadeType) -> str:
     """Normalize cascade parameter to SQLAlchemy string format."""
     if cascade is None:
@@ -344,7 +369,7 @@ class CascadeExecutor:
         return instance
 
     async def execute_delete_operation(
-        self, target, cascade_strategy: str = "full", session: "AsyncSession | None" = None
+        self, target, cascade_strategy: str = "auto", session: "AsyncSession | None" = None
     ) -> int:
         """Execute delete operation with cascade handling."""
         if session is None:
@@ -355,7 +380,8 @@ class CascadeExecutor:
             return await self._execute_queryset_delete(target, cascade_strategy, session)
 
         # Handle single instance deletion
-        await self._delete_related_objects(target, session)
+        if has_cascade_delete_relations(target.__class__):
+            await self._delete_related_objects(target, session)
         await target._delete_internal(session=session)  # noqa
         return 1
 
@@ -478,6 +504,15 @@ class CascadeExecutor:
 
     async def _execute_queryset_delete(self, queryset, cascade_strategy: str, session: "AsyncSession") -> int:
         """Execute QuerySet delete with different cascade strategies."""
+        if cascade_strategy == "auto":
+            model_class = queryset._model_class
+            if has_delete_signals(model_class):
+                cascade_strategy = "full"
+            elif has_cascade_delete_relations(model_class):
+                cascade_strategy = "fast"
+            else:
+                cascade_strategy = "none"
+
         if cascade_strategy == "full":
             return await self._delete_with_full_cascade(queryset, session)
         elif cascade_strategy == "fast":

sqlobjects-1.5.0/sqlobjects/contrib/asgi.py

@@ -0,0 +1,63 @@
+"""ASGI middleware for request-scoped SQLObjects session management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..database.manager import get_default
+from ..session import AsyncSession, _SessionContextManager
+
+
+class SessionMiddleware:
+    """ASGI middleware that provides a request-scoped database session.
+
+    Automatically creates an AsyncSession for each HTTP/WebSocket request,
+    sets it in the ContextVar so that model operations use it, and commits
+    on success or rolls back on failure.
+
+    Usage with FastAPI::
+
+        from fastapi import FastAPI
+        from sqlobjects.contrib.asgi import SessionMiddleware
+
+        app = FastAPI()
+        app.add_middleware(SessionMiddleware)
+
+    Usage with Starlette::
+
+        from starlette.applications import Starlette
+        from sqlobjects.contrib.asgi import SessionMiddleware
+
+        app = Starlette()
+        app.add_middleware(SessionMiddleware)
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        db_name: str | None = None,
+        readonly: bool = False,
+    ) -> None:
+        self.app = app
+        self.db_name = db_name
+        self.readonly = readonly
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        name = self.db_name or get_default()
+        session = AsyncSession(name, readonly=self.readonly, auto_commit=False)
+        token = _SessionContextManager.set_session(session, name)
+        try:
+            await self.app(scope, receive, send)
+            if not self.readonly:
+                await session.commit()
+        except Exception:
+            if not self.readonly:
+                await session.rollback()
+            raise
+        finally:
+            await session.close()
+            _SessionContextManager.reset_session(token)

sqlobjects-1.5.0/sqlobjects/contrib/fastapi.py

@@ -0,0 +1,26 @@
+"""FastAPI dependency for SQLObjects session management."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from ..session import AsyncSession, ctx_session
+
+
+async def get_db_session(db_name: str | None = None) -> AsyncGenerator[AsyncSession, None]:
+    """FastAPI dependency that yields a transactional session.
+
+    Usage::
+
+        from fastapi import Depends
+        from sqlobjects.contrib.fastapi import get_db_session
+        from sqlobjects.session import AsyncSession
+
+
+        @app.post("/users")
+        async def create_user(session: AsyncSession = Depends(get_db_session)):
+            user = await User.objects.using(session).create(name="Alice")
+            return {"id": user.id}
+    """
+    async with ctx_session(db_name) as session:
+        yield session

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/sqlobjects/model.py

@@ -278,11 +278,14 @@ class ModelMixin(DataConversionMixin, SignalMixin):
         return await self._save_internal(validate=validate, session=session)
 
     @emit_signals(Operation.DELETE)
-    async def delete(self, cascade: bool = True):
+    async def delete(self, cascade: bool | None = None):
         """Delete this model instance from the database with cascade support.
 
         Args:
-            cascade: Whether to handle cascade deletion (default: True)
+            cascade: Whether to handle cascade deletion.
+                None (default): auto-detect based on model relationships
+                True: force cascade handling
+                False: skip cascade, direct delete
 
         Raises:
             PrimaryKeyError: If instance has no primary key values or delete fails
@@ -292,6 +295,10 @@ class ModelMixin(DataConversionMixin, SignalMixin):
 
         session = self.get_session()
 
+        # Auto-detect cascade need when not explicitly specified
+        if cascade is None:
+            cascade = self._has_on_delete_relations()
+
         # Use cascade executor for cascade operations
         if cascade:
             executor = CascadeExecutor()

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/sqlobjects/queryset.py

@@ -1221,12 +1221,13 @@ class QuerySet(Generic[T]):
         return await executor.execute_update_operation(self, values)
 
     @emit_signals(Operation.DELETE, is_bulk=True)
-    async def delete(self, cascade: str = "full") -> int:
+    async def delete(self, cascade: str = "auto") -> int:
         """Perform bulk delete on objects matching query conditions.
 
         Args:
             cascade: Cascade deletion strategy
-                - "full" (default): Complete cascade deletion with full ORM functionality
+                - "auto" (default): Automatically choose based on model relationships
+                - "full": Complete cascade deletion with full ORM functionality
                 - "fast": Fast cascade deletion with minimal ORM processing
                 - "none": Direct SQL deletion without ORM cascade processing
 

{sqlobjects-1.3.0 → sqlobjects-1.5.0}/sqlobjects/session.py

@@ -259,8 +259,14 @@ class _SessionContextManager:
         return AsyncSession(name, readonly, auto_commit)
 
     @classmethod
-    def set_session(cls, session: AsyncSession, db_name: str | None = None) -> None:
-        """Set active session in current context."""
+    def set_session(
+        cls, session: AsyncSession, db_name: str | None = None
+    ) -> contextvars.Token[dict[str, "AsyncSession"]]:
+        """Set active session in current context.
+
+        Returns a Token that can be used with reset_session() to restore the
+        previous ContextVar state, enabling correct nested ctx_session() behavior.
+        """
         name = db_name or get_default()
         try:
             current_sessions = _explicit_sessions.get({})
@@ -268,7 +274,12 @@ class _SessionContextManager:
             current_sessions = {}
         new_sessions = current_sessions.copy()
         new_sessions[name] = session
-        _explicit_sessions.set(new_sessions)
+        return _explicit_sessions.set(new_sessions)
+
+    @classmethod
+    def reset_session(cls, token: contextvars.Token[dict[str, "AsyncSession"]]) -> None:
+        """Restore ContextVar to a previous state using a token from set_session()."""
+        _explicit_sessions.reset(token)
 
     @classmethod
     def clear_session(cls, db_name: str | None = None) -> None:
@@ -302,8 +313,8 @@ async def ctx_session(db_name: str | None = None) -> AsyncGenerator[AsyncSession
     name = db_name or get_default()
     session = AsyncSession(name, readonly=False, auto_commit=False)
 
-    # Set as explicit session in context
-    _SessionContextManager.set_session(session, name)
+    # Set as explicit session in context, save token for nested restore
+    token = _SessionContextManager.set_session(session, name)
 
     try:
         yield session
@@ -316,7 +327,7 @@ async def ctx_session(db_name: str | None = None) -> AsyncGenerator[AsyncSession
     finally:
         # Cleanup
         await session.close()
-        _SessionContextManager.clear_session(name)
+        _SessionContextManager.reset_session(token)
 
 
 @asynccontextmanager
@@ -336,13 +347,14 @@ async def ctx_sessions(*db_names: str) -> AsyncGenerator[dict[str, AsyncSession]
         raise ValueError("At least one database name must be provided")
 
     sessions: dict[str, AsyncSession] = {}
+    tokens: list[contextvars.Token[dict[str, AsyncSession]]] = []
 
     try:
         # Create sessions for all
         for db_name in db_names:
             session = AsyncSession(db_name, readonly=False, auto_commit=False)
             sessions[db_name] = session
-            _SessionContextManager.set_session(session, db_name)
+            tokens.append(_SessionContextManager.set_session(session, db_name))
 
         yield sessions
 
@@ -358,9 +370,11 @@ async def ctx_sessions(*db_names: str) -> AsyncGenerator[dict[str, AsyncSession]
 
     finally:
         # Cleanup all sessions
-        for db_name, session in sessions.items():
+        for session in sessions.values():
             await session.close()
-            _SessionContextManager.clear_session(db_name)
+        # Reset tokens in reverse order
+        for token in reversed(tokens):
+            _SessionContextManager.reset_session(token)
 
 
 def get_session(

{sqlobjects-1.3.0 → sqlobjects-1.5.0/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.3.0
+Version: 1.5.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.3.0 → sqlobjects-1.5.0}/sqlobjects.egg-info/SOURCES.txt

@@ -27,6 +27,9 @@ sqlobjects.egg-info/dependency_links.txt
 sqlobjects.egg-info/entry_points.txt
 sqlobjects.egg-info/requires.txt
 sqlobjects.egg-info/top_level.txt
+sqlobjects/contrib/__init__.py
+sqlobjects/contrib/asgi.py
+sqlobjects/contrib/fastapi.py
 sqlobjects/database/__init__.py
 sqlobjects/database/config.py
 sqlobjects/database/manager.py