sqlobjects 1.2.3__tar.gz → 1.2.5__tar.gz

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

@@ -1,3 +1,20 @@
+## 1.2.5 (2026-03-06)
+
+### Fix
+
+- **examples,docs**: fix PGVECTOR type definition and documentation errors
+- **types**: fix JSON/JSONB field containment query generating wrong SQL
+
+## 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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.2.3"
+version = "1.2.5"
 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.3 → sqlobjects-1.2.5}/sqlobjects/expressions/function.py

@@ -147,6 +147,8 @@ class FunctionExpression:
     for building complex database expressions.
     """
 
+    is_clause_element = False  # prevent __getattr__ from proxying this to expression.is_clause_element
+
     if TYPE_CHECKING:
         # Inherit all method hints for IDE support
         def __new__(cls, *args, **kwargs) -> "FunctionExpression & _FunctionMethods": ...  # type: ignore

{sqlobjects-1.2.3 → sqlobjects-1.2.5}/sqlobjects/expressions/mixins.py

@@ -247,9 +247,25 @@ class ColumnAttributeFunctionMixin(FunctionMixin):
         def extract(self, field: str) -> "FunctionExpression": ...
         def date_trunc(self, precision: str) -> "FunctionExpression": ...
 
-        # JSON methods
-        def extract_path(self, path) -> "FunctionExpression": ...
-        def extract_text(self, path) -> "FunctionExpression": ...
+        # JSON methods (MySQL json type)
+        def json_extract(self, path: str) -> "FunctionExpression": ...
+        def json_unquote(self, path: str) -> "FunctionExpression": ...
+        def json_contains(self, other, path: str | None = None) -> "FunctionExpression": ...
+        def json_contains_path(self, *paths: str, match: str = "one") -> "FunctionExpression": ...
+        def json_length(self, path: str | None = None) -> "FunctionExpression": ...
+        def json_keys(self, path: str | None = None) -> "FunctionExpression": ...
+        def json_overlaps(self, other) -> "FunctionExpression": ...
+        def json_search(self, value: str, match: str = "one", path: str | None = None) -> "FunctionExpression": ...
+        def json_type(self) -> "FunctionExpression": ...
+
+        # JSONB methods (PostgreSQL jsonb type)
+        def contained_by(self, other) -> "FunctionExpression": ...
+        def has_key(self, other) -> "FunctionExpression": ...
+        def has_all(self, other) -> "FunctionExpression": ...
+        def has_any(self, other) -> "FunctionExpression": ...
+        def path_exists(self, other) -> "FunctionExpression": ...
+        def path_match(self, other) -> "FunctionExpression": ...
+        def delete_path(self, array) -> "FunctionExpression": ...
 
         # Common methods (all types)
         def sum(self) -> "FunctionExpression": ...

{sqlobjects-1.2.3 → sqlobjects-1.2.5}/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.3 → sqlobjects-1.2.5}/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.5/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