sqlobjects 1.1.0__tar.gz → 1.2.1__tar.gz

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 1.2.1 (2026-02-25)
+
+### Refactor
+
+- centralize session resolution in get_session()
+
+## 1.2.0 (2026-02-25)
+
+### Feat
+
+- **metadata**: improve constraint and index naming conventions
+
 ## 1.1.0 (2026-02-14)
 
 ### Feat

{sqlobjects-1.1.0/sqlobjects.egg-info → sqlobjects-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.1.0
+Version: 1.2.1
 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.1.0 → sqlobjects-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.1.0"
+version = "1.2.1"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"
@@ -49,22 +49,22 @@ Changelog = "https://github.com/XtraVisionsAI/sqlobjects/blob/main/CHANGELOG.md"
 
 [dependency-groups]
 dev = [
-    "pre-commit>=4.4.0",
-    "pyright>=1.1.407",
-    "ruff>=0.14.5",
-    "setuptools>=80.9.0",
+    "pre-commit>=4.5.1",
+    "pyright>=1.1.408",
+    "ruff>=0.15.2",
+    "setuptools>=82.0.0",
 ]
 test = [
     "aiomysql>=0.3.2",
-    "aiosqlite>=0.20.0",
-    "asyncpg>=0.30.0",
-    "pytest>=9.0.1",
+    "aiosqlite>=0.22.1",
+    "asyncpg>=0.31.0",
+    "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
-    "psutil>=7.1.3", # For memory monitoring in performance tests
+    "psutil>=7.2.2", # For memory monitoring in performance tests
 ]
 
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=82.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/sqlobjects/metadata.py

@@ -2,7 +2,7 @@ import re
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Union, cast
 
-from sqlalchemy import CheckConstraint, Index, UniqueConstraint
+from sqlalchemy import CheckConstraint, ForeignKeyConstraint, Index, UniqueConstraint
 from sqlalchemy import MetaData as SqlAlchemyMetaData
 
 from .fields import ColumnAttribute
@@ -24,8 +24,8 @@ __all__ = [
     "unique",
 ]
 
-
 _FIELD_NAME_PATTERN = re.compile(r"\b([a-zA-Z_][a-zA-Z0-9_]*)\b")
+_TEMP_INDEX_PREFIX = "__temp__idx_"
 
 
 @dataclass
@@ -574,7 +574,9 @@ class ModelProcessor(type):
 
     @classmethod
     def _normalize_all_indexes(mcs, indexes: list[Index], table_name: str) -> list[Index]:
-        """Force uniform naming format for all indexes.
+        """Normalize index names that need normalization.
+
+        Only normalizes indexes with temporary names (starting with __temp__idx_).
 
         Args:
             indexes: List of indexes to normalize
@@ -586,6 +588,11 @@ class ModelProcessor(type):
         normalized_indexes = []
 
         for idx in indexes:
+            # Only normalize temporary names
+            if not idx.name or not idx.name.startswith(_TEMP_INDEX_PREFIX):
+                normalized_indexes.append(idx)
+                continue
+
             # Get field name list
             if hasattr(idx, "columns") and idx.columns:
                 field_names = "_".join(col.name for col in idx.columns)  # noqa
@@ -597,10 +604,7 @@ class ModelProcessor(type):
                 continue
 
             # Generate standardized name
-            new_name = f"idx_{table_name}_{field_names}"
-
-            # Directly modify index name (instead of rebuilding)
-            idx.name = new_name  # type: ignore[reportAttributeAccessIssue]
+            idx.name = f"idx_{table_name}_{field_names}"  # type: ignore[reportAttributeAccessIssue]
             normalized_indexes.append(idx)
 
         return normalized_indexes
@@ -683,15 +687,20 @@ class ModelProcessor(type):
     def _post_process_table_indexes(mcs, table, table_name: str) -> None:
         """Normalize index names after table construction.
 
+        Only normalizes indexes with temporary names (starting with __temp__idx_).
+
         Args:
             table: SQLAlchemy Table instance
             table_name: Database table name
         """
         for idx in table.indexes:
+            # Only normalize temporary names
+            if not idx.name or not idx.name.startswith(_TEMP_INDEX_PREFIX):
+                continue
+
             if hasattr(idx, "columns") and idx.columns:
                 field_names = "_".join(col.name for col in idx.columns)
-                new_name = f"idx_{table_name}_{field_names}"
-                idx.name = new_name
+                idx.name = f"idx_{table_name}_{field_names}"
 
     @classmethod
     def _post_process_table_constraints(mcs, table, table_name: str) -> None:
@@ -714,6 +723,20 @@ class ModelProcessor(type):
                 elif isinstance(cst, UniqueConstraint) and hasattr(cst, "columns"):
                     field_names = "_".join(col.name for col in cst.columns)
                     cst.name = f"uq_{table_name}_{field_names}"
+                elif isinstance(cst, ForeignKeyConstraint) and hasattr(cst, "columns"):
+                    # Handle foreign key constraints
+                    field_names = "_".join(col.name for col in cst.columns)
+                    # Get referenced table and column names
+                    if cst.elements:
+                        try:
+                            ref_table = cst.elements[0].column.table.name
+                            ref_columns = "_".join(elem.column.name for elem in cst.elements)
+                            cst.name = f"fk_{table_name}_{field_names}_{ref_table}_{ref_columns}"
+                        except Exception:
+                            # Fallback if reference cannot be resolved yet
+                            cst.name = f"fk_{table_name}_{field_names}"
+                    else:
+                        cst.name = f"fk_{table_name}_{field_names}"
 
     @classmethod
     def _apply_dataclass_functionality(mcs, cls: Any) -> Any:
@@ -1114,11 +1137,9 @@ def index(
         >>> index("idx_users_status", "status", postgresql_where="status = 'active'")
         >>> index("idx_users_tags", "tags", postgresql_using="gin")
     """
-    # Note: Don't auto-generate name here because table_name is needed
-    # Actual name normalization is handled in _merge_indexes
     if name is None:
         field_part = "_".join(fields)
-        name = f"idx_{field_part}"  # Temporary name, will be replaced later
+        name = f"{_TEMP_INDEX_PREFIX}{field_part}"
 
     # Build dialect-specific kwargs
     dialect_kwargs = {}

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/sqlobjects/mixins.py

@@ -165,10 +165,7 @@ class SessionMixin(BaseMixin):
         Returns:
             AsyncSession instance for database operations
         """
-        bound_session = self._state_manager.get_bound_session()
-        if isinstance(bound_session, str):
-            return get_session(bound_session)
-        return bound_session or get_session()
+        return get_session(self._state_manager.get_bound_session())
 
     def using(self, db_or_session: str | AsyncSession):
         """Return self bound to specific database/connection.

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/sqlobjects/objects/core.py

@@ -82,12 +82,7 @@ class ObjectsManager(Generic[T]):
         Returns:
             AsyncSession instance
         """
-        if self._db_or_session is None:
-            return get_session(readonly=readonly)
-        elif isinstance(self._db_or_session, str):
-            return get_session(self._db_or_session, readonly=readonly)
-        else:
-            return self._db_or_session
+        return get_session(self._db_or_session, readonly=readonly)
 
     def _validate_field_names(self, **kwargs) -> None:
         """Validate that all field names exist on the model.

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/sqlobjects/queries/dialect.py

@@ -1,6 +1,7 @@
 """Database dialect handlers for database-specific SQL generation."""
 
 from abc import ABC, abstractmethod
+from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
 import sqlalchemy as sa
@@ -46,7 +47,7 @@ class BaseDialect(ABC):
         pass
 
     @abstractmethod
-    def parse_explain_result(self, rows: list) -> str:
+    def parse_explain_result(self, rows: Sequence) -> str:
         """Parse EXPLAIN result for the database."""
         pass
 
@@ -108,7 +109,7 @@ class PostgreSQLDialect(BaseDialect):
             return f"EXPLAIN ({', '.join(options)}) {sql}"
         return f"EXPLAIN {sql}"
 
-    def parse_explain_result(self, rows: list) -> str:
+    def parse_explain_result(self, rows: Sequence) -> str:
         """Parse PostgreSQL EXPLAIN result."""
         return "\n".join(str(row[0]) for row in rows)
 
@@ -151,7 +152,7 @@ class MySQLDialect(BaseDialect):
             return f"EXPLAIN ANALYZE {sql}"
         return f"EXPLAIN {sql}"
 
-    def parse_explain_result(self, rows: list) -> str:
+    def parse_explain_result(self, rows: Sequence) -> str:
         """Parse MySQL EXPLAIN result."""
         return "\n".join(str(row[0]) for row in rows)
 
@@ -199,7 +200,7 @@ class SQLiteDialect(BaseDialect):
         """
         return f"EXPLAIN QUERY PLAN {sql}"
 
-    def parse_explain_result(self, rows: list) -> str:
+    def parse_explain_result(self, rows: Sequence) -> str:
         """Parse SQLite EXPLAIN result.
 
         SQLite EXPLAIN QUERY PLAN returns: (id, parent, notused, detail)

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/sqlobjects/queries/executor.py

@@ -18,13 +18,22 @@ class QueryExecutor:
     aggregations, and memory-efficient iteration for large datasets.
     """
 
+    _WRITE_TYPES = frozenset({"update", "delete"})
+
     def __init__(self, session=None):
         """Initialize executor with optional session.
 
         Args:
-            session: Database session for query execution
+            session: Database session, database name string, or None
         """
-        self.session = session
+        self._db_or_session = session
+
+    def _get_session(self, query_type: str):
+        """Resolve session with appropriate readonly flag."""
+        from ..session import get_session
+
+        readonly = query_type not in self._WRITE_TYPES
+        return get_session(self._db_or_session, readonly=readonly)
 
     async def execute(
         self,
@@ -115,23 +124,24 @@ class QueryExecutor:
         Returns:
             Query execution plan as string
         """
-        if not self.session:
+        session = self._get_session("all")
+        if not session:
             raise RuntimeError("No session available for explain operation")
 
         # Get dialect handler
         from .dialect import DialectHandler
 
-        dialect = DialectHandler.create(self.session)
+        dialect = DialectHandler.create(session)
 
         # Compile query to SQL
-        compiled = query.compile(dialect=self.session.bind.dialect, compile_kwargs={"literal_binds": True})
+        compiled = query.compile(dialect=session.bind.dialect, compile_kwargs={"literal_binds": True})
         sql_str = str(compiled)
 
         # Build EXPLAIN query using dialect handler
         explain_sql = dialect.build_explain_query(sql_str, analyze, verbose)
 
         # Execute query
-        result = await self.session.execute(text(explain_sql))
+        result = await session.execute(text(explain_sql))
         rows = result.fetchall()
 
         # Parse result using dialect handler
@@ -196,7 +206,8 @@ class QueryExecutor:
         relationships=None,
     ):
         """Execute query and return appropriate result."""
-        if not self.session:
+        session = self._get_session(query_type)
+        if not session:
             if query_type == "all":
                 return []
             elif query_type in ("count", "update", "delete"):
@@ -206,7 +217,7 @@ class QueryExecutor:
             else:  # exists
                 return False
 
-        result = await self.session.execute(query)
+        result = await session.execute(query)
 
         if query_type == "all":
             rows = result.fetchall()
@@ -417,7 +428,7 @@ class QueryExecutor:
         if not instances or not prefetch_relationships:
             return instances
 
-        prefetch_handler = PrefetchHandler(self.session)
+        prefetch_handler = PrefetchHandler(self._get_session("all"))
         return await prefetch_handler.handle_prefetch_relationships(instances, prefetch_relationships)
 
     @staticmethod

{sqlobjects-1.1.0 → sqlobjects-1.2.1}/sqlobjects/session.py

@@ -3,7 +3,7 @@ from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from typing import Any
 
-from sqlalchemy import CursorResult
+from sqlalchemy import CursorResult, text
 from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.ext.asyncio import AsyncConnection, AsyncResult
 
@@ -13,7 +13,6 @@ from .exceptions import convert_sqlalchemy_error
 
 __all__ = ["AsyncSession", "ctx_session", "ctx_sessions", "get_session", "has_session"]
 
-
 # Explicit session management (highest priority)
 _explicit_sessions: contextvars.ContextVar[dict[str, "AsyncSession"]] = contextvars.ContextVar("explicit_sessions")
 
@@ -64,9 +63,17 @@ class AsyncSession:
         return get_database(self._db_name).engine
 
     async def execute(self, statement: Any, parameters: Any = None) -> CursorResult[Any]:
-        """Execute statement with automatic transaction management."""
+        """Execute statement with automatic transaction management.
+
+        Supports both SQLAlchemy statement objects and raw SQL strings.
+        Raw SQL strings are automatically wrapped with text().
+        """
         await self._ensure_connection()
 
+        # Auto-wrap string SQL with text()
+        if isinstance(statement, str):
+            statement = text(statement)
+
         # Auto-begin transaction for non-readonly sessions
         if not self.readonly and self._trans is None:
             self._trans = await self._conn.begin()  # type: ignore
@@ -89,6 +96,9 @@ class AsyncSession:
     async def stream(self, statement: Any, parameters: Any = None) -> AsyncResult[Any]:
         """Execute statement and return streaming result.
 
+        Supports both SQLAlchemy statement objects and raw SQL strings.
+        Raw SQL strings are automatically wrapped with text().
+
         Note: stream() is not supported with auto_commit=True sessions.
         Use explicit sessions (ctx_session) for streaming operations.
         """
@@ -99,6 +109,10 @@ class AsyncSession:
 
         await self._ensure_connection()
 
+        # Auto-wrap string SQL with text()
+        if isinstance(statement, str):
+            statement = text(statement)
+
         # Auto-begin transaction for non-readonly sessions
         if not self.readonly and self._trans is None:
             self._trans = await self._conn.begin()  # type: ignore
@@ -331,11 +345,13 @@ async def ctx_sessions(*db_names: str) -> AsyncGenerator[dict[str, AsyncSession]
             _SessionContextManager.clear_session(db_name)
 
 
-def get_session(db_name: str | None = None, readonly: bool = True, auto_commit: bool = True) -> AsyncSession:
+def get_session(
+    db_or_name: str | AsyncSession | None = None, readonly: bool = True, auto_commit: bool = True
+) -> AsyncSession:
     """Get database session with readonly optimization.
 
     Args:
-        db_name: Database name (uses default database if None)
+        db_or_name: Database name, existing AsyncSession, or None for default database
         readonly: True for readonly (no transaction), False for transactional
         auto_commit: True to auto-commit transactions (ignored if readonly=True)
 
@@ -343,10 +359,13 @@ def get_session(db_name: str | None = None, readonly: bool = True, auto_commit:
         AsyncSession instance
 
     Priority:
+        - If db_or_name is an AsyncSession, return it directly
         - First try use explicitly set session (ctx_session, ctx_sessions)
         - Create a new AsyncSession with specified parameters if no explicit session
     """
-    return _SessionContextManager.get_session(db_name, readonly, auto_commit)
+    if isinstance(db_or_name, AsyncSession):
+        return db_or_name
+    return _SessionContextManager.get_session(db_or_name, readonly, auto_commit)
 
 
 def has_session(db_name: str | None = None) -> bool:

{sqlobjects-1.1.0 → sqlobjects-1.2.1/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.1.0
+Version: 1.2.1
 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>