sqlobjects 1.2.2__tar.gz → 1.2.4__tar.gz

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 1.2.4 (2026-02-28)
+
+### Fix
+
+- handle nested Q objects in Q._to_sqlalchemy
+
+### Refactor
+
+- **relationships**: overhaul relationship resolution and prefetch system
+
+## 1.2.3 (2026-02-26)
+
+### Fix
+
+- resolve PostgreSQL test failures and cross-test data pollution
+- **executor**: add overloads to execute() and fix iterator type narrowing
+- **queryset**: replace non-existent executor.session with _get_session()
+- enhance exception handling to surface detailed SQLAlchemy errors
+
+### Refactor
+
+- **metadata**: simplify index handling and config parsing
+
 ## 1.2.2 (2026-02-26)
 
 ### Fix

{sqlobjects-1.2.2/sqlobjects.egg-info → sqlobjects-1.2.4}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.2.2"
+version = "1.2.4"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"
@@ -98,7 +98,6 @@ pythonVersion = "3.12"
 reportMissingImports = "error"
 reportUnnecessaryTypeIgnoreComment = "warning"
 reportMissingTypeStubs = false
-lang = "en"
 
 [tool.ruff]
 line-length = 120

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/sqlobjects/database/manager.py

@@ -189,12 +189,17 @@ class Database:
             >>> await db.create_tables(ObjectModel)  # Create all tables
             >>> await db.create_tables(ObjectModel, [User, Post])  # Create specific tables
         """
-        async with self.engine.begin() as conn:
-            if tables is None:
-                await conn.run_sync(base_class.__registry__.create_all)
-            else:
-                table_objects = [model.__table__ for model in tables]
-                await conn.run_sync(base_class.__registry__.create_all, tables=table_objects)
+        try:
+            async with self.engine.begin() as conn:
+                if tables is None:
+                    await conn.run_sync(base_class.__registry__.create_all)
+                else:
+                    table_objects = [model.__table__ for model in tables]
+                    await conn.run_sync(base_class.__registry__.create_all, tables=table_objects)
+        except Exception as e:
+            from ..exceptions import convert_sqlalchemy_error
+
+            raise convert_sqlalchemy_error(e) from e
 
     async def drop_tables(self, base_class, tables: list[type] | None = None) -> None:
         """Drop tables defined in the model registry of SQLObjects base class
@@ -211,12 +216,17 @@ class Database:
             >>> await db.drop_tables(ObjectModel)  # Drop all tables
             >>> await db.drop_tables(ObjectModel, [User, Post])  # Drop specific tables
         """
-        async with self.engine.begin() as conn:
-            if tables is None:
-                await conn.run_sync(base_class.__registry__.drop_all)
-            else:
-                table_objects = [model.__table__ for model in tables]
-                await conn.run_sync(base_class.__registry__.drop_all, tables=table_objects)
+        try:
+            async with self.engine.begin() as conn:
+                if tables is None:
+                    await conn.run_sync(base_class.__registry__.drop_all)
+                else:
+                    table_objects = [model.__table__ for model in tables]
+                    await conn.run_sync(base_class.__registry__.drop_all, tables=table_objects)
+        except Exception as e:
+            from ..exceptions import convert_sqlalchemy_error
+
+            raise convert_sqlalchemy_error(e) from e
 
     async def disconnect(self) -> None:
         """Disconnect database and clean up resources

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/sqlobjects/exceptions.py

@@ -458,8 +458,21 @@ def convert_sqlalchemy_error(error: Exception) -> SQLObjectsError:
         ... except SQLAlchemyError as e:
         ...     raise convert_sqlalchemy_error(e)
     """
+    # Build detailed error message with context
     error_msg = str(error)
 
+    # Add SQL statement if available
+    if hasattr(error, "statement") and getattr(error, "statement", None):
+        error_msg += f"\nSQL: {error.statement}"  # type: ignore[reportAttributeAccessIssue]
+
+    # Add parameters if available
+    if hasattr(error, "params") and getattr(error, "params", None):
+        error_msg += f"\nParams: {error.params}"  # type: ignore[reportAttributeAccessIssue]
+
+    # Add original database error if available
+    if hasattr(error, "orig") and getattr(error, "orig", None):
+        error_msg += f"\nOriginal: {error.orig}"  # type: ignore[reportAttributeAccessIssue]
+
     if isinstance(error, SQLAIntegrityError):
         return IntegrityError(error_msg, original_error=error)
     elif isinstance(error, SQLAOperationalError):

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/sqlobjects/expressions/function.py

@@ -432,13 +432,13 @@ class _FuncWrapper:
 func = _FuncWrapper()
 
 # Add window functions at runtime
-func.row_number = lambda: RowNumberFunction()  # type: ignore
-func.rank = lambda: RankFunction()  # type: ignore
-func.dense_rank = lambda: DenseRankFunction()  # type: ignore
-func.percent_rank = lambda: PercentRankFunction()  # type: ignore
-func.ntile = lambda n: NtileFunction(n)  # type: ignore
-func.lag = lambda col, offset=1, default=None: LagFunction(col, offset, default)  # type: ignore
-func.lead = lambda col, offset=1, default=None: LeadFunction(col, offset, default)  # type: ignore
-func.first_value = lambda col: FirstValueFunction(col)  # type: ignore
-func.last_value = lambda col: LastValueFunction(col)  # type: ignore
-func.nth_value = lambda col, n: NthValueFunction(col, n)  # type: ignore
+func.row_number = lambda: RowNumberFunction()
+func.rank = lambda: RankFunction()
+func.dense_rank = lambda: DenseRankFunction()
+func.percent_rank = lambda: PercentRankFunction()
+func.ntile = lambda n: NtileFunction(n)
+func.lag = lambda col, offset=1, default=None: LagFunction(col, offset, default)
+func.lead = lambda col, offset=1, default=None: LeadFunction(col, offset, default)
+func.first_value = lambda col: FirstValueFunction(col)
+func.last_value = lambda col: LastValueFunction(col)
+func.nth_value = lambda col, n: NthValueFunction(col, n)

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/sqlobjects/fields/core.py

@@ -317,6 +317,7 @@ class ColumnAttribute(ColumnAttributeFunctionMixin, Generic[T]):
     """
 
     inherit_cache = True  # make use of the cache key generated by the superclass from SQLAlchemy
+    is_clause_element = False  # force SQLAlchemy to call __clause_element__() for proper coercion
 
     def __getattr__(self, name):
         """Handle attribute access with proper priority.

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/sqlobjects/fields/proxies.py

@@ -96,6 +96,14 @@ class BaseRelated(Generic[T]):
         self.property = descriptor.property
         self._cached_value = None
         self._loaded = False
+        self._rel_info = None
+
+    def _get_relationship_info(self):
+        if self._rel_info is None:
+            from .relations.utils import RelationshipAnalyzer
+
+            self._rel_info = RelationshipAnalyzer.analyze_relationship(self.instance.__class__, self.property.name)
+        return self._rel_info
 
     async def fetch(self) -> T:
         """Fetch related object(s)."""
@@ -122,23 +130,28 @@ class RelatedObject(BaseRelated[T]):
 
     async def _load(self):
         """Load related object from database."""
-        if self.property.foreign_keys and self.property.resolved_model:
-            fk_field = self.property.foreign_keys
-            if isinstance(fk_field, list):
-                fk_field = fk_field[0]
+        if not self.property.resolved_model:
+            self._loaded = True
+            return
 
-            fk_value = getattr(self.instance, fk_field)
-            if fk_value is not None:
-                related_table = self.property.resolved_model.get_table()
-                pk_col = list(related_table.primary_key.columns)[0]
+        info = self._get_relationship_info()
+        if not info:
+            self._loaded = True
+            return
 
-                query = select(related_table).where(pk_col == fk_value)
-                session = self.instance.get_session()
-                result = await session.execute(query)
-                row = result.first()
+        fk_field = info["foreign_key_fields"][0]
+        ref_field = info["ref_fields"][0]
+        fk_value = getattr(self.instance, fk_field)
 
-                if row:
-                    self._cached_value = self.property.resolved_model.from_dict(dict(row._mapping), validate=False)
+        if fk_value is not None:
+            related_table = self.property.resolved_model.get_table()
+            ref_col = related_table.c[ref_field]
+            query = select(related_table).where(ref_col == fk_value)
+            session = self.instance.get_session()
+            result = await session.execute(query)
+            row = result.first()
+            if row:
+                self._cached_value = self.property.resolved_model.from_dict(dict(row._mapping), validate=False)
 
         self._loaded = True
 
@@ -191,12 +204,18 @@ class OneToManyRelation(RelatedCollection[T]):
             self._set_empty_result()
             return
 
-        instance_pk = self.instance.id
-        related_table = self.property.resolved_model.get_table()
+        info = self._get_relationship_info()
+        if not info:
+            self._set_empty_result()
+            return
+
+        fk_field = info["foreign_key_fields"][0]
+        ref_field = info["ref_fields"][0]
+        ref_value = getattr(self.instance, ref_field)
 
-        fk_name = self._get_fk_field()
-        fk_col = related_table.c[fk_name]
-        query = select(related_table).where(fk_col == instance_pk)
+        related_table = self.property.resolved_model.get_table()
+        fk_col = related_table.c[fk_field]
+        query = select(related_table).where(fk_col == ref_value)
         session = self.instance.get_session()
         result = await session.execute(query)
 
@@ -207,19 +226,32 @@ class OneToManyRelation(RelatedCollection[T]):
 
     async def add(self, *objs: T, session=None) -> None:
         """Add objects to the relationship."""
+        info = self._get_relationship_info()
+        if not info:
+            raise ValueError(
+                f"Cannot resolve relationship '{self.property.name}' on "
+                f"'{self.instance.__class__.__name__}'. Define it explicitly with relationship()."
+            )
         session = session or self.instance.get_session()
-        fk_field = self._get_fk_field()
+        fk_field = info["foreign_key_fields"][0]
+        ref_value = getattr(self.instance, info["ref_fields"][0])
 
         for obj in objs:
-            setattr(obj, fk_field, self.instance.id)
+            setattr(obj, fk_field, ref_value)
             await obj.using(session).save()  # type: ignore
 
         self._invalidate_cache()
 
     async def remove(self, *objs: T, session=None) -> None:
         """Remove objects from the relationship."""
+        info = self._get_relationship_info()
+        if not info:
+            raise ValueError(
+                f"Cannot resolve relationship '{self.property.name}' on "
+                f"'{self.instance.__class__.__name__}'. Define it explicitly with relationship()."
+            )
         session = session or self.instance.get_session()
-        fk_field = self._get_fk_field()
+        fk_field = info["foreign_key_fields"][0]
 
         for obj in objs:
             setattr(obj, fk_field, None)
@@ -227,19 +259,6 @@ class OneToManyRelation(RelatedCollection[T]):
 
         self._invalidate_cache()
 
-    def _get_fk_field(self):
-        """Get foreign key field name."""
-        fk_name = self.property.foreign_keys
-        if isinstance(fk_name, list):
-            fk_name = fk_name[0]
-        elif fk_name is None:
-            fk_name = (
-                f"{self.property.back_populates}_id"
-                if self.property.back_populates
-                else f"{self.instance.__class__.__name__.lower()}_id"
-            )
-        return fk_name
-
     def __str__(self):
         return f"<OneToManyRelation: {self.property.name}>"
 

{sqlobjects-1.2.2 → sqlobjects-1.2.4}/sqlobjects/fields/relations/descriptors.py

@@ -3,6 +3,12 @@ from typing import TYPE_CHECKING, Generic, TypeVar, overload
 from ...cascade import OnDelete
 
 
+def _normalize_fields(fields: str | list[str] | None) -> list[str] | None:
+    if fields is None:
+        return None
+    return [fields] if isinstance(fields, str) else list(fields)
+
+
 if TYPE_CHECKING:
     from ...model import ObjectModel
     from ..proxies import BaseRelated
@@ -27,6 +33,7 @@ class RelationshipProperty:
         self,
         argument: str | type["ObjectModel"],
         foreign_keys: str | list[str] | None = None,
+        remote_fields: str | list[str] | None = None,
         back_populates: str | None = None,
         backref: str | None = None,
         lazy: str = "select",
@@ -40,32 +47,21 @@ class RelationshipProperty:
         passive_deletes: bool = False,
         **kwargs,
     ):
-        """Initialize relationship property with cascade and deletion behavior.
-
-        Args:
-            argument: Target model class or string name
-            foreign_keys: Foreign key field name(s)
-            back_populates: Name of reverse relationship attribute
-            backref: Name for automatic reverse relationship
-            lazy: Loading strategy ('select', 'dynamic', 'noload', 'raise')
-            uselist: Whether relationship returns a list
-            secondary: M2M table name
-            primaryjoin: Custom primary join condition
-            secondaryjoin: Custom secondary join condition for M2M
-            order_by: Default ordering for collections
-            cascade: Cascade behavior (bool for simple on/off, str for SQLAlchemy cascade options)
-            on_delete: Behavior when related object is deleted
-            passive_deletes: Whether to use passive deletes
-            **kwargs: Additional relationship options
-        """
+        if foreign_keys and remote_fields:
+            raise ValueError(
+                "Cannot specify both 'foreign_keys' and 'remote_fields'. "
+                "Use 'foreign_keys' when the FK is on this model, "
+                "'remote_fields' when the FK is on the related model."
+            )
         self.argument = argument
-        self.foreign_keys = foreign_keys
+        self.foreign_keys: list[str] | None = _normalize_fields(foreign_keys)
+        self.remote_fields: list[str] | None = _normalize_fields(remote_fields)
         self.back_populates = back_populates
         self.backref = backref
         self.lazy = lazy
         self.uselist = uselist
         self.secondary = secondary
-        self.m2m_definition = None  # M2M table definition
+        self.m2m_definition = None
         self.primaryjoin = primaryjoin
         self.secondaryjoin = secondaryjoin
         self.order_by = order_by
@@ -75,9 +71,7 @@ class RelationshipProperty:
         self.name: str | None = None
         self.resolved_model: type[ObjectModel] | None = None
         self.relationship_type: str | None = None
-        self.is_many_to_many: bool = False  # M2M relationship flag
-
-        # Store additional relationship configuration parameters
+        self.is_many_to_many: bool = False
         self.extra_kwargs = kwargs
 
 

sqlobjects-1.2.4/sqlobjects/fields/relations/prefetch.py

@@ -0,0 +1,159 @@
+from sqlalchemy import tuple_
+
+from .utils import RelationshipAnalyzer
+
+
+class PrefetchHandler:
+    """Handle prefetch_related operations for model relationships."""
+
+    def __init__(self, session):
+        self.session = session
+
+    async def handle_prefetch_relationships(self, instances, prefetch_relationships):
+        if not instances or not prefetch_relationships:
+            return instances
+
+        for relationship_name in prefetch_relationships:
+            relationship_info = RelationshipAnalyzer.analyze_relationship(instances[0].__class__, relationship_name)
+            if relationship_info:
+                await self._prefetch_single_relationship(instances, relationship_name, relationship_info)
+
+        return instances
+
+    async def _prefetch_single_relationship(self, instances, relationship_name, relationship_info):
+        rel_type = relationship_info["type"]
+
+        if rel_type == "reverse_fk":
+            await self._prefetch_by_fields(
+                instances,
+                relationship_name,
+                relationship_info["related_model"],
+                relationship_info["ref_fields"],
+                relationship_info["foreign_key_fields"],
+                [],
+            )
+        elif rel_type == "one_to_one":
+            info = relationship_info
+            await self._prefetch_by_fields(
+                instances,
+                relationship_name,
+                info["related_model"],
+                info["ref_fields"],
+                info["foreign_key_fields"],
+                None,
+            )
+        elif rel_type == "many_to_one":
+            info = relationship_info
+            await self._prefetch_by_fields(
+                instances,
+                relationship_name,
+                info["related_model"],
+                info["foreign_key_fields"],
+                info["ref_fields"],
+                None,
+            )
+        elif rel_type == "many_to_many":
+            await self._prefetch_many_to_many(instances, relationship_name, relationship_info)
+
+    async def _prefetch_by_fields(
+        self, instances, relationship_name, related_model, lookup_fields, group_fields, empty
+    ):
+        """Unified prefetch for FK-based relationships."""
+        composite = len(lookup_fields) > 1
+
+        def make_key(obj, fields):
+            return tuple(getattr(obj, f) for f in fields) if composite else getattr(obj, fields[0])
+
+        lookup_values = [
+            make_key(inst, lookup_fields)
+            for inst in instances
+            if all(getattr(inst, f, None) is not None for f in lookup_fields)
+        ]
+        if not lookup_values:
+            for inst in instances:
+                inst._update_cache(relationship_name, [] if isinstance(empty, list) else empty)
+            return
+
+        if composite:
+            cols = [getattr(related_model, f) for f in group_fields]
+            qs = related_model.objects.using(self.session).filter(tuple_(*cols).in_(lookup_values))
+        else:
+            qs = related_model.objects.using(self.session).filter(
+                getattr(related_model, group_fields[0]).in_(lookup_values)
+            )
+        related_objects = await qs.all()
+
+        if isinstance(empty, list):
+            grouped = {}
+            for obj in related_objects:
+                grouped.setdefault(make_key(obj, group_fields), []).append(obj)
+            for inst in instances:
+                inst._update_cache(relationship_name, grouped.get(make_key(inst, lookup_fields), []))
+        else:
+            related_map = {make_key(obj, group_fields): obj for obj in related_objects}
+            for inst in instances:
+                inst._update_cache(relationship_name, related_map.get(make_key(inst, lookup_fields)))
+
+    async def _prefetch_many_to_many(self, instances, relationship_name, relationship_info):
+        """Prefetch many-to-many via through table."""
+        related_model = relationship_info["related_model"]
+        through_table = relationship_info["through_table"]
+        left_field = relationship_info["left_field"]
+        right_field = relationship_info["right_field"]
+        left_ref_field = relationship_info["left_ref_field"]
+        right_ref_field = relationship_info["right_ref_field"]
+
+        instance_values = [
+            getattr(inst, left_ref_field) for inst in instances if getattr(inst, left_ref_field, None) is not None
+        ]
+        if not instance_values:
+            for inst in instances:
+                inst._update_cache(relationship_name, [])
+            return
+
+        through_model = self._find_through_model(through_table)
+        if not through_model:
+            return
+
+        through_objects = await (
+            through_model.objects.using(self.session)
+            .filter(getattr(through_model, left_field).in_(instance_values))
+            .all()
+        )
+
+        related_values = [getattr(obj, right_field) for obj in through_objects]
+        if not related_values:
+            for inst in instances:
+                inst._update_cache(relationship_name, [])
+            return
+
+        related_objects = await (
+            related_model.objects.using(self.session)
+            .filter(getattr(related_model, right_ref_field).in_(related_values))
+            .all()
+        )
+
+        related_map = {getattr(obj, right_ref_field): obj for obj in related_objects}
+
+        grouped = {}
+        for through_obj in through_objects:
+            main_val = getattr(through_obj, left_field)
+            rel_val = getattr(through_obj, right_field)
+            if rel_val in related_map:
+                grouped.setdefault(main_val, []).append(related_map[rel_val])
+
+        for inst in instances:
+            key = getattr(inst, left_ref_field, None)
+            inst._update_cache(relationship_name, grouped.get(key, []))
+
+    @staticmethod
+    def _find_through_model(through_table):
+        from ...model import ObjectModel
+
+        for subclass in ObjectModel.__subclasses__():
+            try:
+                if hasattr(subclass, "get_table") and subclass.get_table().name == through_table:
+                    return subclass
+            except Exception:  # noqa
+                continue
+        return None