sqlobjects 1.2.5__tar.gz → 1.4.0__tar.gz

{sqlobjects-1.2.5 → sqlobjects-1.4.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 1.4.0 (2026-03-11)
+
+### Feat
+
+- **session**: fix nested ctx_session() and add ASGI/FastAPI integration
+
+## 1.3.0 (2026-03-10)
+
+### Feat
+
+- **fields**: support class name reference in foreign_key() with delayed matching
+
 ## 1.2.5 (2026-03-06)
 
 ### Fix

{sqlobjects-1.2.5/sqlobjects.egg-info → sqlobjects-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.2.5
+Version: 1.4.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.2.5 → sqlobjects-1.4.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.2.5 → sqlobjects-1.4.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.2.5 → sqlobjects-1.4.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.2.5 → sqlobjects-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.2.5"
+version = "1.4.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.4.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.4.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.2.5 → sqlobjects-1.4.0}/sqlobjects/fields/functions.py

@@ -8,6 +8,22 @@ from .core import Column, column
 from .shortcuts import ComputedColumn, IdentityColumn
 
 
+def _extract_table_or_class_name(reference: str) -> str | None:
+    """从 'X.col' 或 'schema.X.col' 中提取 X（可能是表名或类名）。
+
+    Returns:
+        X 部分，用于后续延迟匹配；格式不合法时返回 None
+    """
+    parts = reference.split(".")
+    if len(parts) == 2:
+        # "X.col"
+        return parts[0]
+    if len(parts) == 3:
+        # "schema.X.col"
+        return parts[1]
+    return None
+
+
 def identity(
     *,
     start: int = 1,
@@ -76,7 +92,10 @@ def foreign_key(
     """Create foreign key column with database constraint behavior.
 
     Args:
-        reference: Foreign key reference in format "table.column"
+        reference: Foreign key reference in format "X.column" where X can be either
+            a model class name (e.g. "User.id", "UserProfile.id") or a database table
+            name (e.g. "users.id"). Class names are automatically resolved to table
+            names via delayed matching. Schema is also supported: "schema.X.column".
         type: Column type, "auto" for automatic type inference
         nullable: Whether column can be null
         ondelete: Database constraint behavior when referenced object is deleted
@@ -89,12 +108,15 @@ def foreign_key(
         Column descriptor with foreign key constraint
 
     Examples:
-        # Basic usage with auto type inference
+        # Using class name (resolved automatically)
+        author_id: Column[int] = foreign_key("User.id")
+
+        # Using table name directly (also works)
         author_id: Column[int] = foreign_key("users.id")
 
         # Complete constraint configuration
         author_id: Column[int] = foreign_key(
-            "users.id",
+            "User.id",
             ondelete="CASCADE",
             onupdate="CASCADE",
             nullable=False
@@ -102,7 +124,7 @@ def foreign_key(
 
         # Deferred constraint for circular references
         parent_id: Column[int] = foreign_key(
-            "categories.id",
+            "Category.id",
             deferrable=True,
             initially="DEFERRED"
         )
@@ -122,9 +144,16 @@ def foreign_key(
         fk_kwargs["deferrable"] = True
         fk_kwargs["initially"] = initially
 
-    # Create ForeignKey constraint
+    # Reference is passed directly to SQLAlchemy; delayed matching in
+    # ModelProcessor._resolve_class_foreign_keys will correct the table
+    # name if the first segment turns out to be a class name.
     fk_constraint = ForeignKey(reference, **fk_kwargs)
 
+    # Store the table-or-class segment for delayed resolution
+    table_or_class = _extract_table_or_class_name(reference)
+    if table_or_class:
+        fk_constraint.info["_fk_ref"] = table_or_class
+
     # Use existing column() function with foreign key
     return column(
         type=type,

{sqlobjects-1.2.5 → sqlobjects-1.4.0}/sqlobjects/metadata.py

@@ -368,6 +368,9 @@ class ModelProcessor(type):
             # Auto-register model to ModelRegistry
             registry.register_model(cast(type["ObjectModel"], cls))
 
+            # Resolve class name foreign key references to actual table names
+            mcs._resolve_class_foreign_keys(registry)
+
             # Process pending M2M tables
             registry.process_pending_m2m()
 
@@ -851,6 +854,40 @@ class ModelProcessor(type):
 
         cls.__eq__ = __eq__
 
+    @classmethod
+    def _resolve_class_foreign_keys(mcs, registry):
+        """延迟解析外键引用：优先按类名匹配，匹配不到则视为表名。
+
+        foreign_key("User.id") 传入时原样交给 SQLAlchemy（_colspec="User.id"）。
+        每次新模型注册后，此方法遍历所有 FK：
+        1. 取出 info["_fk_ref"]（即 "." 前的那段，如 "User"）
+        2. 尝试在 registry 中按类名查找模型
+        3. 找到 → 替换 _colspec 为实际表名，标记 _resolved
+        4. 找不到 → 保留原样（视为已经是表名）
+        """
+        for table in registry.tables.values():
+            for col in table.columns:
+                for fk in col.foreign_keys:
+                    fk_info = fk.info
+                    if fk_info.get("_fk_resolved"):
+                        continue
+                    ref_name = fk_info.get("_fk_ref")
+                    if not ref_name:
+                        continue
+                    model = registry.get_model(ref_name)
+                    if not model or not hasattr(model, "__table__"):
+                        continue
+                    # Found matching model — rewrite _colspec to actual table name
+                    actual_table = model.__table__.name
+                    schema, tname, colname = fk._column_tokens
+                    if tname != actual_table:
+                        if schema:
+                            fk._colspec = f"{schema}.{actual_table}.{colname}"
+                        else:
+                            fk._colspec = f"{actual_table}.{colname}"
+                        fk.__dict__.pop("_column_tokens", None)
+                    fk_info["_fk_resolved"] = True
+
     @classmethod
     def _bind_column_attributes_to_table(mcs, cls: Any, table) -> None:
         """Bind ColumnAttribute instances to their corresponding table columns.

{sqlobjects-1.2.5 → sqlobjects-1.4.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.2.5 → sqlobjects-1.4.0/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.2.5
+Version: 1.4.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.2.5 → sqlobjects-1.4.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