sqlobjects 1.2.3__py3-none-any.whl → 1.2.4__py3-none-any.whl

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/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/fields/relations/prefetch.py

@@ -1,3 +1,5 @@
+from sqlalchemy import tuple_
+
 from .utils import RelationshipAnalyzer
 
 
@@ -8,19 +10,9 @@ class PrefetchHandler:
         self.session = session
 
     async def handle_prefetch_relationships(self, instances, prefetch_relationships):
-        """Handle prefetch_related relationship prefetching.
-
-        Args:
-            instances: List of model instances
-            prefetch_relationships: Set of relationship names to prefetch
-
-        Returns:
-            list: Instances with prefetched relationships attached
-        """
         if not instances or not prefetch_relationships:
             return instances
 
-        # Prefetch each relationship field
         for relationship_name in prefetch_relationships:
             relationship_info = RelationshipAnalyzer.analyze_relationship(instances[0].__class__, relationship_name)
             if relationship_info:
@@ -29,98 +21,81 @@ class PrefetchHandler:
         return instances
 
     async def _prefetch_single_relationship(self, instances, relationship_name, relationship_info):
-        """Prefetch single relationship field."""
         rel_type = relationship_info["type"]
 
         if rel_type == "reverse_fk":
-            await self._prefetch_reverse_foreign_key(instances, relationship_name, relationship_info)
+            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":
-            await self._prefetch_one_to_one(instances, relationship_name, relationship_info)
+            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)
-        elif rel_type == "many_to_one":
-            await self._prefetch_forward_foreign_key(instances, relationship_name, relationship_info)
-
-    async def _prefetch_reverse_foreign_key(self, instances, relationship_name, relationship_info):
-        """Prefetch reverse foreign key relationship (one-to-many)."""
-        related_model = relationship_info["related_model"]
-        foreign_key_field = relationship_info["foreign_key_field"]
-        ref_field = relationship_info["ref_field"]
-
-        # Collect reference values from main instances
-        instance_values = [
-            getattr(instance, ref_field)
-            for instance in instances
-            if hasattr(instance, ref_field) and getattr(instance, ref_field) is not None
-        ]
-        if not instance_values:
-            # Still need to attach empty lists to all instances
-            for instance in instances:
-                instance._update_cache(relationship_name, [])
-            return
 
-        # Execute prefetch query
-        related_objects = (
-            await related_model.objects.using(self.session)
-            .filter(getattr(related_model, foreign_key_field).in_(instance_values))
-            .all()
-        )
+    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
 
-        # Group by foreign key value
-        grouped_objects = {}
-        for obj in related_objects:
-            fk_value = getattr(obj, foreign_key_field, None)
-            if fk_value is not None:
-                if fk_value not in grouped_objects:
-                    grouped_objects[fk_value] = []
-                grouped_objects[fk_value].append(obj)
-
-        # Attach to main instances using unified proxy_cache
-        for instance in instances:
-            instance_value = getattr(instance, ref_field, None)
-            related_list = grouped_objects.get(instance_value, [])
-            instance._update_cache(relationship_name, related_list)
-
-    async def _prefetch_one_to_one(self, instances, relationship_name, relationship_info):
-        """Prefetch one-to-one relationship (reverse FK with uselist=False)."""
-        related_model = relationship_info["related_model"]
-        foreign_key_field = relationship_info["foreign_key_field"]
-        ref_field = relationship_info["ref_field"]
+        def make_key(obj, fields):
+            return tuple(getattr(obj, f) for f in fields) if composite else getattr(obj, fields[0])
 
-        # Collect reference values from main instances
-        instance_values = [
-            getattr(instance, ref_field)
-            for instance in instances
-            if hasattr(instance, ref_field) and getattr(instance, ref_field) is not None
+        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 instance_values:
-            # Still need to attach None to all instances
-            for instance in instances:
-                instance._update_cache(relationship_name, None)
+        if not lookup_values:
+            for inst in instances:
+                inst._update_cache(relationship_name, [] if isinstance(empty, list) else empty)
             return
 
-        # Execute prefetch query
-        related_objects = (
-            await related_model.objects.using(self.session)
-            .filter(getattr(related_model, foreign_key_field).in_(instance_values))
-            .all()
-        )
-
-        # Create mapping (should be one-to-one)
-        related_map = {}
-        for obj in related_objects:
-            fk_value = getattr(obj, foreign_key_field, None)
-            if fk_value is not None:
-                related_map[fk_value] = obj  # Single object, not list
-
-        # Attach to main instances using unified proxy_cache
-        for instance in instances:
-            instance_value = getattr(instance, ref_field, None)
-            related_obj = related_map.get(instance_value, None)  # Single object or None
-            instance._update_cache(relationship_name, related_obj)
+        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 relationship."""
+        """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"]
@@ -128,114 +103,57 @@ class PrefetchHandler:
         left_ref_field = relationship_info["left_ref_field"]
         right_ref_field = relationship_info["right_ref_field"]
 
-        # Collect reference values from main instances
         instance_values = [
-            getattr(instance, left_ref_field)
-            for instance in instances
-            if hasattr(instance, left_ref_field) and getattr(instance, left_ref_field) is not None
+            getattr(inst, left_ref_field) for inst in instances if getattr(inst, left_ref_field, None) is not None
         ]
         if not instance_values:
-            # Still need to attach empty lists to all instances
-            for instance in instances:
-                instance._update_cache(relationship_name, [])
+            for inst in instances:
+                inst._update_cache(relationship_name, [])
             return
 
-        # Find through model
         through_model = self._find_through_model(through_table)
         if not through_model:
             return
 
-        # Query through table associations
-        through_objects = (
-            await through_model.objects.using(self.session)
+        through_objects = await (
+            through_model.objects.using(self.session)
             .filter(getattr(through_model, left_field).in_(instance_values))
             .all()
         )
 
-        # Collect related object reference values
         related_values = [getattr(obj, right_field) for obj in through_objects]
         if not related_values:
-            # Still need to attach empty lists to all instances
-            for instance in instances:
-                instance._update_cache(relationship_name, [])
+            for inst in instances:
+                inst._update_cache(relationship_name, [])
             return
 
-        # Query related objects
-        related_objects = (
-            await related_model.objects.using(self.session)
+        related_objects = await (
+            related_model.objects.using(self.session)
             .filter(getattr(related_model, right_ref_field).in_(related_values))
             .all()
         )
 
-        # Create related object mapping
         related_map = {getattr(obj, right_ref_field): obj for obj in related_objects}
 
-        # Group by main instance reference value
-        grouped_relations = {}
+        grouped = {}
         for through_obj in through_objects:
-            main_value = getattr(through_obj, left_field)
-            related_value = getattr(through_obj, right_field)
-
-            if main_value not in grouped_relations:
-                grouped_relations[main_value] = []
-
-            if related_value in related_map:
-                grouped_relations[main_value].append(related_map[related_value])
-
-        # Attach to main instances using unified proxy_cache
-        for instance in instances:
-            instance_value = getattr(instance, left_ref_field, None)
-            related_list = grouped_relations.get(instance_value, [])
-            instance._update_cache(relationship_name, related_list)
-
-    async def _prefetch_forward_foreign_key(self, instances, relationship_name, relationship_info):
-        """Prefetch forward foreign key relationship (many-to-one)."""
-        related_model = relationship_info["related_model"]
-        foreign_key_field = relationship_info["foreign_key_field"]
-        ref_field = relationship_info["ref_field"]
-
-        # Collect foreign key values
-        fk_values = [
-            getattr(instance, foreign_key_field)
-            for instance in instances
-            if hasattr(instance, foreign_key_field) and getattr(instance, foreign_key_field) is not None
-        ]
-        if not fk_values:
-            # Still need to attach None to all instances
-            for instance in instances:
-                instance._update_cache(relationship_name, None)
-            return
-
-        # Query related objects
-        related_objects = (
-            await related_model.objects.using(self.session)
-            .filter(getattr(related_model, ref_field).in_(fk_values))
-            .all()
-        )
-
-        # Create mapping
-        related_map = {getattr(obj, ref_field): obj for obj in related_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])
 
-        # Attach to main instances using unified proxy_cache
-        for instance in instances:
-            fk_value = getattr(instance, foreign_key_field, None)
-            if fk_value in related_map:
-                instance._update_cache(relationship_name, related_map[fk_value])
-            else:
-                # Store None for instances without related objects
-                instance._update_cache(relationship_name, None)
+        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):
-        """Find through table model."""
         from ...model import ObjectModel
 
         for subclass in ObjectModel.__subclasses__():
             try:
-                if hasattr(subclass, "get_table"):
-                    table = subclass.get_table()
-                    if table.name == through_table:
-                        return subclass
+                if hasattr(subclass, "get_table") and subclass.get_table().name == through_table:
+                    return subclass
             except Exception:  # noqa
                 continue
         return None

sqlobjects/fields/relations/utils.py

@@ -1,5 +1,6 @@
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, TypeVar, overload
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from sqlalchemy import Column, ForeignKey, Table
 
@@ -77,90 +78,26 @@ class RelationshipResolver:
 
     @staticmethod
     def resolve_relationship_type(property_: RelationshipProperty) -> str:
-        """Automatically infer relationship type based on parameters.
-
-        Args:
-            property_: RelationshipProperty instance to analyze
-
-        Returns:
-            String representing the relationship type
-        """
-        # Handle explicit uselist setting
-        if property_.uselist is False:
-            return RelationshipType.MANY_TO_ONE if property_.foreign_keys else RelationshipType.ONE_TO_ONE
-        elif property_.uselist:
-            return RelationshipType.MANY_TO_MANY if property_.secondary else RelationshipType.ONE_TO_MANY
-
-        # Auto-infer based on parameters
         if property_.secondary:
             property_.is_many_to_many = True
             property_.uselist = True
             return RelationshipType.MANY_TO_MANY
         elif property_.foreign_keys:
-            property_.uselist = False
+            if property_.uselist is None:
+                property_.uselist = False
             return RelationshipType.MANY_TO_ONE
         else:
-            property_.uselist = True
-            return RelationshipType.ONE_TO_MANY
-
-
-@overload
-def relationship(
-    argument: str | type,
-    *,
-    uselist: Literal[False],
-    foreign_keys: str | list[str] | None = None,
-    back_populates: str | None = None,
-    backref: str | None = None,
-    lazy: Literal["select"] = "select",
-    primaryjoin: str | None = None,
-    order_by: str | list[str] | None = None,
-    cascade: CascadeType = None,
-    passive_deletes: bool = False,
-    **kwargs: Any,
-) -> Any: ...
-
-
-@overload
-def relationship(
-    argument: str | type,
-    *,
-    secondary: str | M2MTable,
-    foreign_keys: str | list[str] | None = None,
-    back_populates: str | None = None,
-    backref: str | None = None,
-    lazy: str = "select",
-    uselist: bool | None = None,
-    primaryjoin: str | None = None,
-    secondaryjoin: str | None = None,
-    order_by: str | list[str] | None = None,
-    cascade: CascadeType = None,
-    passive_deletes: bool = False,
-    **kwargs: Any,
-) -> Any: ...
-
-
-@overload
-def relationship(
-    argument: str | type,
-    *,
-    foreign_keys: str | list[str] | None = None,
-    back_populates: str | None = None,
-    backref: str | None = None,
-    lazy: str = "select",
-    uselist: bool | None = None,
-    primaryjoin: str | None = None,
-    order_by: str | list[str] | None = None,
-    cascade: CascadeType = None,
-    passive_deletes: bool = False,
-    **kwargs: Any,
-) -> Any: ...
+            # remote_fields or no hint — one_to_many or one_to_one
+            if property_.uselist is None:
+                property_.uselist = True
+            return RelationshipType.ONE_TO_ONE if property_.uselist is False else RelationshipType.ONE_TO_MANY
 
 
 def relationship(
     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",
@@ -173,49 +110,30 @@ def relationship(
     passive_deletes: bool = False,
     **kwargs: Any,
 ) -> Any:
-    """Define model relationship with SQLAlchemy-compatible cascade behavior.
+    """Define model relationship.
 
     Args:
         argument: Target model class or string name
-        foreign_keys: Foreign key field name(s)
+        foreign_keys: FK field name(s) on this model (many_to_one side)
+        remote_fields: FK field name(s) on the related model (one_to_many/one_to_one side)
         back_populates: Name of reverse relationship attribute
         backref: Name for automatic reverse relationship
-        lazy: Loading strategy ('select', 'dynamic', 'noload', 'raise')
+        lazy: Loading strategy
         uselist: Whether relationship returns a list
         secondary: M2M table name or M2MTable instance
         primaryjoin: Custom primary join condition
         secondaryjoin: Custom secondary join condition for M2M
         order_by: Default ordering for collections
-        cascade: Application-layer cascade behavior (SQLAlchemy compatible)
+        cascade: Cascade behavior
         passive_deletes: Whether to use passive deletes
-        **kwargs: Additional relationship options
-
-    Returns:
-        Column instance wrapping RelationshipDescriptor for type compatibility
-
-    Raises:
-        ValueError: If both back_populates and backref are specified
-
-    Example:
-        # With type annotation
-        posts: Column[list["Post"]] = relationship("Post", back_populates="author")
-        author: Column[User] = relationship("User", back_populates="posts")
-
-        # With cascade
-        posts = relationship("Post", cascade={CascadeOption.ALL, CascadeOption.DELETE_ORPHAN})
     """
-
-    # Validate mutually exclusive parameters
     if back_populates and backref:
         raise ValueError("Cannot specify both 'back_populates' and 'backref'")
 
-    # Normalize cascade parameter to SQLAlchemy string format
     cascade_str = normalize_cascade(cascade)
 
-    # Handle M2M table definition
     secondary_table_name = None
     m2m_def = None
-
     if isinstance(secondary, M2MTable):
         m2m_def = secondary
         secondary_table_name = secondary.table_name
@@ -225,6 +143,7 @@ def relationship(
     property_ = RelationshipProperty(
         argument=argument,
         foreign_keys=foreign_keys,
+        remote_fields=remote_fields,
         back_populates=back_populates,
         backref=backref,
         lazy=lazy,
@@ -233,20 +152,17 @@ def relationship(
         primaryjoin=primaryjoin,
         secondaryjoin=secondaryjoin,
         order_by=order_by,
-        cascade=cascade_str,  # Use normalized string
+        cascade=cascade_str,
         passive_deletes=passive_deletes,
         **kwargs,
     )
 
-    # Set M2M definition if provided
     if m2m_def:
         property_.m2m_definition = m2m_def  # type: ignore[reportAttributeAccessIssue]
         property_.is_many_to_many = True
 
-    # Import Related here to avoid circular import
     from ..core import Related
 
-    # Return Related container for relationship fields
     return Related(is_relationship=True, relationship_property=property_, m2m_definition=m2m_def)
 
 
@@ -254,117 +170,147 @@ class RelationshipAnalyzer:
     """Analyze model relationships and extract metadata for prefetch operations."""
 
     @staticmethod
+    @lru_cache(maxsize=256)
     def analyze_relationship(model_class, relationship_name):
-        """Analyze relationship type and extract related information.
-
-        Args:
-            model_class: Main model class
-            relationship_name: Relationship field name
-
-        Returns:
-            dict: Relationship info dict with type, related model, field mappings
-        """
         try:
-            # Check explicit relationship definition
             if hasattr(model_class, relationship_name):
                 field_attr = getattr(model_class, relationship_name)
                 if hasattr(field_attr, "property"):
                     return RelationshipAnalyzer._extract_relationship_info(model_class, field_attr.property)
-
-            # Infer reverse relationship
             return RelationshipAnalyzer._infer_reverse_relationship(model_class, relationship_name)
         except Exception:  # noqa
             return None
 
     @staticmethod
     def _extract_relationship_info(model_class, prop):
-        """Extract information from relationship property."""
         related_model = RelationshipAnalyzer._resolve_model_class(prop.argument)
         if not related_model:
             return None
 
-        if prop.secondary:  # Many-to-many relationship
+        # many_to_many
+        if prop.secondary:
             m2m_def = getattr(prop, "m2m_definition", None)
-            if m2m_def:
-                return {
-                    "type": "many_to_many",
-                    "related_model": related_model,
-                    "through_table": prop.secondary,
-                    "left_field": m2m_def.left_field,
-                    "right_field": m2m_def.right_field,
-                    "left_ref_field": m2m_def.left_ref_field,
-                    "right_ref_field": m2m_def.right_ref_field,
-                }
-            else:
-                # String-only secondary table - cannot determine field mappings without M2MTable definition
+            if not m2m_def:
                 return None
+            return {
+                "type": "many_to_many",
+                "related_model": related_model,
+                "through_table": prop.secondary,
+                "left_field": m2m_def.left_field,
+                "right_field": m2m_def.right_field,
+                "left_ref_field": m2m_def.left_ref_field,
+                "right_ref_field": m2m_def.right_ref_field,
+            }
 
-        elif prop.foreign_keys:  # Many-to-one (forward foreign key)
+        # many_to_one — FK is on this model
+        if prop.foreign_keys:
+            from .descriptors import _normalize_fields
+
+            fks = _normalize_fields(prop.foreign_keys)
+            ref_fields = RelationshipAnalyzer._scan_ref_fields(model_class, fks, related_model)
             return {
                 "type": "many_to_one",
                 "related_model": related_model,
-                "foreign_key_field": prop.foreign_keys,
-                "ref_field": RelationshipAnalyzer._extract_ref_field(prop.foreign_keys),
+                "foreign_key_fields": fks,
+                "ref_fields": ref_fields,
             }
 
-        else:  # One-to-many or one-to-one (reverse relationship)
-            # Try to find the correct foreign key field from back_populates
-            foreign_key_field = f"{model_class.__name__.lower()}_id"  # Default
+        # one_to_many / one_to_one — FK is on the related model
+        rel_type = "one_to_one" if prop.uselist is False else "reverse_fk"
 
-            if prop.back_populates:
-                # Look for the corresponding relationship in the related model
-                if hasattr(related_model, prop.back_populates):
-                    back_attr = getattr(related_model, prop.back_populates)
-                    if hasattr(back_attr, "property") and back_attr.property.foreign_keys:
-                        foreign_key_field = back_attr.property.foreign_keys
+        if prop.remote_fields:
+            from .descriptors import _normalize_fields
 
-            # Determine if it's one-to-one or one-to-many based on uselist
-            rel_type = "one_to_one" if prop.uselist is False else "reverse_fk"
+            rf = prop.remote_fields
+            foreign_key_fields = _normalize_fields(rf) if isinstance(rf, (str, list)) else None
+            if not foreign_key_fields:
+                foreign_key_fields, ref_fields = RelationshipAnalyzer._scan_fk_fields(related_model, model_class, prop)
+            else:
+                ref_fields = RelationshipAnalyzer._scan_ref_fields(related_model, foreign_key_fields, model_class)
+        else:
+            foreign_key_fields, ref_fields = RelationshipAnalyzer._scan_fk_fields(related_model, model_class, prop)
 
-            return {
-                "type": rel_type,
-                "related_model": related_model,
-                "foreign_key_field": foreign_key_field,
-                "ref_field": "id",
-            }
+        return {
+            "type": rel_type,
+            "related_model": related_model,
+            "foreign_key_fields": foreign_key_fields,
+            "ref_fields": ref_fields,
+        }
+
+    @staticmethod
+    def _scan_fk_fields(related_model, current_model, prop):
+        """Scan related model's columns to find FK(s) pointing to current model's table."""
+        try:
+            current_table = current_model.__table__
+            related_table = related_model.__table__
+        except AttributeError:
+            raise ValueError(
+                f"Cannot resolve relationship: model tables not available. "
+                f"Use 'remote_fields' to specify the FK field on {related_model.__name__}."
+            ) from None
+
+        candidates = [
+            (col.name, [fk.column.name for fk in col.foreign_keys if fk.column.table == current_table])
+            for col in related_table.columns
+            if any(fk.column.table == current_table for fk in col.foreign_keys)
+        ]
+
+        if not candidates:
+            # Fallback: try back_populates
+            if prop.back_populates and hasattr(related_model, prop.back_populates):
+                back_attr = getattr(related_model, prop.back_populates)
+                if hasattr(back_attr, "property") and back_attr.property.foreign_keys:
+                    fks = back_attr.property.foreign_keys
+                    refs = [RelationshipAnalyzer._extract_ref_field(fk) for fk in fks]
+                    return fks, refs
+            raise ValueError(
+                f"No foreign key found on '{related_model.__name__}' pointing to '{current_model.__name__}'. "
+                f"Use 'remote_fields' to specify the FK field."
+            )
+
+        if len(candidates) > 1:
+            names = [c[0] for c in candidates]
+            raise ValueError(
+                f"Multiple foreign keys found on '{related_model.__name__}' pointing to "
+                f"'{current_model.__name__}': {names}. Use 'remote_fields' to specify which one."
+            )
+
+        fk_col_name, ref_col_names = candidates[0]
+        return [fk_col_name], ref_col_names if ref_col_names else ["id"]
+
+    @staticmethod
+    def _scan_ref_fields(related_model, foreign_key_fields, current_model):
+        """Given FK field names on related model, find the referenced columns on current model."""
+        try:
+            related_table = related_model.__table__
+        except AttributeError:
+            return ["id"] * len(foreign_key_fields)
+
+        ref_fields = []
+        for fk_name in foreign_key_fields:
+            if fk_name in related_table.c:
+                col = related_table.c[fk_name]
+                refs = [fk.column.name for fk in col.foreign_keys]
+                ref_fields.append(refs[0] if refs else "id")
+            else:
+                ref_fields.append("id")
+        return ref_fields
 
     @staticmethod
     def _extract_ref_field(foreign_key_spec):
-        """Extract reference field from foreign key specification."""
         if isinstance(foreign_key_spec, str) and "." in foreign_key_spec:
             return foreign_key_spec.split(".", 1)[1]
-        return "id"  # Default to primary key
+        return foreign_key_spec if isinstance(foreign_key_spec, str) else "id"
 
     @staticmethod
     def _infer_reverse_relationship(model_class, relationship_name):
-        """Infer reverse relationship (e.g., User.posts)."""
-        # posts -> Post, comments -> Comment
-        related_model_name = relationship_name.rstrip("s").capitalize()
-        related_model = RelationshipAnalyzer._resolve_model_class(related_model_name)
-
-        if related_model:
-            # Check if related model has foreign key pointing to current model
-            foreign_key_field = f"{model_class.__name__.lower()}_id"
-            try:
-                if hasattr(related_model, foreign_key_field):
-                    return {
-                        "type": "reverse_fk",
-                        "related_model": related_model,
-                        "foreign_key_field": foreign_key_field,
-                        "ref_field": "id",
-                    }
-            except Exception:  # noqa
-                pass
-
         return None
 
     @staticmethod
     def _resolve_model_class(argument):
-        """Resolve model class from string or class argument."""
         if isinstance(argument, str):
             from ...model import ObjectModel
 
-            # Try to get any ObjectModel subclass to access the registry
             for subclass in ObjectModel.__subclasses__():
                 if hasattr(subclass, "__registry__"):
                     try:
@@ -372,13 +318,10 @@ class RelationshipAnalyzer:
                     except Exception:
                         continue
 
-            # Fallback to recursive search if registry lookup fails
             def find_subclass(base_class):
-                """Recursively find subclass by name."""
                 for subclass in base_class.__subclasses__():
                     if subclass.__name__ == argument:
                         return subclass
-                    # Recursively search in subclasses
                     found = find_subclass(subclass)
                     if found:
                         return found

sqlobjects/metadata.py

@@ -215,7 +215,7 @@ class ModelRegistry(SqlAlchemyMetaData):
                         if fk.column.table.name == target_table_name:
                             property_.uselist = False
                             if not property_.foreign_keys:
-                                property_.foreign_keys = col.name
+                                property_.foreign_keys = [col.name]
                             return
 
                 # No FK found, assume one-to-many

sqlobjects/queryset.py

@@ -181,6 +181,9 @@ class Q:
                     _, field_name, value = expr
                     field_column = table.c[field_name]
                     conditions.append(field_column == value)
+                elif isinstance(expr, Q):
+                    # Nested Q object passed as positional argument
+                    conditions.append(expr._to_sqlalchemy(table))
                 elif hasattr(expr, "resolve"):
                     # Resolve SQLObjects expressions
                     conditions.append(expr.resolve(table))  # type: ignore[reportAttributeAccessIssue]

sqlobjects/session.py

@@ -62,7 +62,7 @@ class AsyncSession:
         # Return engine if no connection yet
         return get_database(self._db_name).engine
 
-    async def execute(self, statement: Any, parameters: Any = None) -> CursorResult[Any]:
+    async def execute(self, statement: Any, parameters: Any = None) -> "CursorResult[Any]":
         """Execute statement with automatic transaction management.
 
         Supports both SQLAlchemy statement objects and raw SQL strings.
@@ -85,12 +85,21 @@ class AsyncSession:
             if self.auto_commit:
                 await self.commit()
 
-            return result
+            # Buffer rows before closing so the connection can be returned to the pool.
+            # Readonly sessions only run SELECT queries, so freeze()() is safe.
+            # Write sessions with auto_commit need rowcount/inserted_primary_key which
+            # are already captured in the CursorResult before close() is called.
+            if self.readonly:
+                result = result.freeze()()
+
+            return result  # type: ignore[return-value]
         except Exception as e:
             await self._handle_exception(e)
+            raise  # unreachable, _handle_exception always raises
         finally:
             # Auto-close connection for implicit sessions to prevent resource leaks
-            if self.auto_commit:
+            # This covers both auto_commit write sessions and readonly sessions
+            if self.auto_commit or self.readonly:
                 await self.close()
 
     async def stream(self, statement: Any, parameters: Any = None) -> AsyncResult[Any]:

{sqlobjects-1.2.3.dist-info → sqlobjects-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.2.3
+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.3.dist-info → sqlobjects-1.2.4.dist-info}/RECORD

@@ -2,11 +2,11 @@ sqlobjects/__init__.py,sha256=AiZiXBEjvrSItmhnlgyvMDCipU49XmvQPAujg-EoEDg,977
 sqlobjects/_install_rules.py,sha256=ndw9815-60WY_ORGUefijUBnoUHPd0NBzUkCL8mQLKc,4053
 sqlobjects/cascade.py,sha256=HLHB4TEoqK7m2i4X9JM0oX3nbltuTntaX3tMX1B1ym4,38389
 sqlobjects/exceptions.py,sha256=IEp5XV6N3hc3SAU-C3F-5D6jEZU_p72mufvwVhaStHo,16592
-sqlobjects/metadata.py,sha256=YNmeQqOTMSOD4Pqnmef1PS3P4wVRPvoW-TnnlCHNwEk,41479
+sqlobjects/metadata.py,sha256=ftumbrSTJGN73jtg0e88vPwGURQAxRkho6B41YOMU-Q,41481
 sqlobjects/mixins.py,sha256=TBZFYAfa9RKF0UpxloBwREoWRPrWFHQE8MjOu7Aepu0,25501
 sqlobjects/model.py,sha256=PwP-0XhlVktICRCEye0gYlXrkVQG13yErjOwwf2ssJ0,19273
-sqlobjects/queryset.py,sha256=cjoEV-R2qitAIL_TuOx7ZpmEo_DzmNcIwee2zIMAFOI,49903
-sqlobjects/session.py,sha256=ODIxoGtTqdXDN9sa8eZ0ShxzwddjjuicUpv6pntZDM0,14282
+sqlobjects/queryset.py,sha256=nIouDo4oL6a3fdrNNAeicFHeYYIx0fpdOpFND5wugAg,50079
+sqlobjects/session.py,sha256=2XaAkboxcL8qHOcUHWc6wXUqiN1IzNoBRpozQLae8C0,14887
 sqlobjects/signals.py,sha256=N4mhotmMy_Ub-XJCvdlfsQ767KVzPbbJdF0JlJ405Oc,17454
 sqlobjects/validators.py,sha256=aqP7YgCnx-cjthqRo2RD-Iz2lvFsJsDgT73HwLwZGxE,10334
 sqlobjects/database/__init__.py,sha256=6lSRw4RzaWhomWEMyPWnpza7UxACQ6JhcFWxnLZZXlU,434
@@ -26,15 +26,15 @@ sqlobjects/expressions/window.py,sha256=0Olsi422n04SuemGjhIB_WwA9vTGJvMqOjHPWBFj
 sqlobjects/fields/__init__.py,sha256=SXYpmfS3l0CqKTIJsOD68wiQIE_x2ORYk2D7gb_E7Qc,1459
 sqlobjects/fields/core.py,sha256=IUGofZ-BlPuMzQBsqH25Ri9eGvLkenur7969u_wMniU,38712
 sqlobjects/fields/functions.py,sha256=KuCdtjTdfXo_1c2MNSlcPhyQmjPo8xFIt4CNUZnvU88,4281
-sqlobjects/fields/proxies.py,sha256=MS7z9p94QVU2xes2ryPfJns1lYGPiT5Dr9maAJJskTo,16800
+sqlobjects/fields/proxies.py,sha256=nUSKYWDdmv91--0TzWh5-YK-fauW-piVVAiLZtMWjqM,17541
 sqlobjects/fields/shortcuts.py,sha256=euYyW0DliR77jLZDRQLNSsCpIHJBoRc7kzTBOIvHQFo,22794
 sqlobjects/fields/utils.py,sha256=HokUdlkyrUT85U468_ngWH7wbGj-VSjSet1AYG64tqI,3549
 sqlobjects/fields/relations/__init__.py,sha256=Bw64TIxt_HlRzRkjlu1t2hMRSvktWGxtI3BXdleTcVQ,629
-sqlobjects/fields/relations/descriptors.py,sha256=OZhW1GhF0YX17kSEx_ewKpN-Kdl_Pw4NcKB6mcksyNU,5647
+sqlobjects/fields/relations/descriptors.py,sha256=Dws4L_GyF8WljU__jSDkgc559Syx6ERz8elj_vse15o,5222
 sqlobjects/fields/relations/managers.py,sha256=k0dU4xisRCvUTTTowEQpJUM1BXVt3J65lDInAC9W5zg,2919
-sqlobjects/fields/relations/prefetch.py,sha256=oX_cCmREFOY9-m3CO-rlMzKisFhP80GrQEVD7k8K2BE,10082
+sqlobjects/fields/relations/prefetch.py,sha256=ccWO8hKfUUJVPoL5CPLUSMtscwT-XZg82hNArxh2nmc,6206
 sqlobjects/fields/relations/strategies.py,sha256=X4KkeBxwpCcBHWhcL9EGH2WTQ2NdZWBJzm3SMZagpIQ,566
-sqlobjects/fields/relations/utils.py,sha256=VDKT9MQ2WQ8jrS3Bw7K49S-py8Sfr4Mtc6l3BoeudlU,13975
+sqlobjects/fields/relations/utils.py,sha256=G1PbW1heCShUSfjaDIbqj4I0yODdy4j3udf0Ex70cOg,12487
 sqlobjects/fields/types/__init__.py,sha256=PaEslOWuQVZVUoVnUFtqF-sNHOvF9AEVhuDseqRr-GA,651
 sqlobjects/fields/types/base.py,sha256=aK-8UDYtUcqJtwxw_emR-WefKDhrQyp0BK7s-UKx4yw,463
 sqlobjects/fields/types/comparators.py,sha256=d9azQGpUGg7eNF_aR0wWjZDzL3sFClHNh-fyObQudgY,15556
@@ -54,17 +54,17 @@ sqlobjects/utils/__init__.py,sha256=NsJ52Fl_PaB-2WlOIJVGNPmgOnqPmvYRmp7uaq5zfYs,
 sqlobjects/utils/inspect.py,sha256=u-Q9VBoSGYCE_3Soy8jMuCAdM-P7IkSzTxqrJop_Ilk,2612
 sqlobjects/utils/naming.py,sha256=PmfNuEz-Twly2qREjKfMNulJt8TmOUJaxzFTuts3COg,1411
 sqlobjects/utils/pattern.py,sha256=FGCgobTpnmKjdAtQidHIg4Xa2CQLeP35F0VuX_1T1dk,14740
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/01-database-session-guide.md,sha256=lnqRpcDhYKdH-f0avW1jXcWt3qi7XBwkMt7clTs9Zvg,7601
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/02-model-definition-guide.md,sha256=i5gNJM-0bIJ2xSUu3mij8uB9kJC9EAc_439sCBqRph8,10977
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/03-query-operations-guide.md,sha256=BEZE_WUUhY6sEZDiDtrbInlV_UVIhbYETABJTNhu2JQ,10550
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/04-crud-operations-guide.md,sha256=abUEvRPSiSjX8enclXO5Uryox9Rt0WFeRcFkvHXfPf8,10085
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/05-relationships-guide.md,sha256=MJ23fYOTWqrLd54ENZLu3S3QRqbLf7joq-YhF6-V8OQ,12204
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/06-validation-signals-guide.md,sha256=i9WLLhyCDoWGkIYqH2D_XLn98oMbF1pB3-L-b5gRbT4,14294
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/07-performance-guide.md,sha256=rjR0DjT39poEBVaUxAzJBEaMaBrZKLVer1zXaNNYfxg,12851
-sqlobjects-1.2.3.data/data/share/sqlobjects/rules/README.md,sha256=d2n5ZZT8LGvjL60u_HlzXn2uA8FwoCgqG3fuAhvMFvM,2280
-sqlobjects-1.2.3.dist-info/licenses/LICENSE,sha256=ScFR7nvWIhar0d32Y-LA4vqp9zNmy1HSJia7UX7jU6c,1068
-sqlobjects-1.2.3.dist-info/METADATA,sha256=La4cgkP-taTiemMfbkPbwQknox7UwK-1pwoycrjQpaI,13740
-sqlobjects-1.2.3.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
-sqlobjects-1.2.3.dist-info/entry_points.txt,sha256=9Q3Ci55MawxkQhMlR_eLJui00_rYYIVO_Aq_Dm0u5MQ,76
-sqlobjects-1.2.3.dist-info/top_level.txt,sha256=brO5vDtCpn4L9dpX0EHpehbu4kcHaK_2Bbnwze35YKc,11
-sqlobjects-1.2.3.dist-info/RECORD,,
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/01-database-session-guide.md,sha256=lnqRpcDhYKdH-f0avW1jXcWt3qi7XBwkMt7clTs9Zvg,7601
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/02-model-definition-guide.md,sha256=i5gNJM-0bIJ2xSUu3mij8uB9kJC9EAc_439sCBqRph8,10977
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/03-query-operations-guide.md,sha256=BEZE_WUUhY6sEZDiDtrbInlV_UVIhbYETABJTNhu2JQ,10550
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/04-crud-operations-guide.md,sha256=abUEvRPSiSjX8enclXO5Uryox9Rt0WFeRcFkvHXfPf8,10085
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/05-relationships-guide.md,sha256=MJ23fYOTWqrLd54ENZLu3S3QRqbLf7joq-YhF6-V8OQ,12204
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/06-validation-signals-guide.md,sha256=i9WLLhyCDoWGkIYqH2D_XLn98oMbF1pB3-L-b5gRbT4,14294
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/07-performance-guide.md,sha256=rjR0DjT39poEBVaUxAzJBEaMaBrZKLVer1zXaNNYfxg,12851
+sqlobjects-1.2.4.data/data/share/sqlobjects/rules/README.md,sha256=d2n5ZZT8LGvjL60u_HlzXn2uA8FwoCgqG3fuAhvMFvM,2280
+sqlobjects-1.2.4.dist-info/licenses/LICENSE,sha256=ScFR7nvWIhar0d32Y-LA4vqp9zNmy1HSJia7UX7jU6c,1068
+sqlobjects-1.2.4.dist-info/METADATA,sha256=Wql2U7dUxjC3mK9nGp7iF7YoVpHJBbynF798QO4Kc0c,13740
+sqlobjects-1.2.4.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+sqlobjects-1.2.4.dist-info/entry_points.txt,sha256=9Q3Ci55MawxkQhMlR_eLJui00_rYYIVO_Aq_Dm0u5MQ,76
+sqlobjects-1.2.4.dist-info/top_level.txt,sha256=brO5vDtCpn4L9dpX0EHpehbu4kcHaK_2Bbnwze35YKc,11
+sqlobjects-1.2.4.dist-info/RECORD,,