sqlobjects 1.5.0__tar.gz → 1.7.0__tar.gz

{sqlobjects-1.5.0 → sqlobjects-1.7.0}/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 1.7.0 (2026-03-26)
+
+### Feat
+
+- **metadata**: add foreignkey() constraint builder
+
+### Fix
+
+- **raw**: allow SA expressions as arguments in raw() methods
+
+## 1.6.0 (2026-03-18)
+
+### Feat
+
+- **metadata**: add foreignkey()    constraint builder
+
 ## 1.5.0 (2026-03-16)
 
 ### Feat

{sqlobjects-1.5.0/sqlobjects.egg-info → sqlobjects-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.5.0
+Version: 1.7.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.5.0 → sqlobjects-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.5.0"
+version = "1.7.0"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"

{sqlobjects-1.5.0 → sqlobjects-1.7.0}/sqlobjects/expressions/function.py

@@ -183,7 +183,9 @@ class FunctionExpression:
 
         Args:
             sql: Raw SQL function name or expression
-            *args: Arguments to pass to the function. Use ... (Ellipsis) as placeholder for current expression
+            *args: Arguments to pass to the function. Use ... (Ellipsis) as placeholder for current expression.
+                   SQLAlchemy expressions (ColumnElement, FunctionExpression) are passed through as-is;
+                   plain Python values are wrapped with literal().
             **kwargs: Additional keyword arguments passed to the function
 
         Returns:
@@ -198,12 +200,17 @@ class FunctionExpression:
             User.age.avg().raw('CUSTOM_FUNCTION', 'param1', ..., 'param2')
             # Generates: CUSTOM_FUNCTION('param1', avg(age), 'param2')
 
-            # Only current expression
-            User.age.raw('CUSTOM_FUNCTION')
-            # Generates: CUSTOM_FUNCTION(age)
+            # Passing another SA expression as argument
+            User.name.raw('CUSTOM_FUNCTION', other_func_expr)
+            # Generates: CUSTOM_FUNCTION(name, other_func_expr)
         """
         from sqlalchemy import literal
 
+        def _to_sql_arg(arg):
+            if isinstance(arg, (ColumnElement, FunctionExpression)):
+                return arg
+            return literal(arg)
+
         # Check if ... (Ellipsis) is used as placeholder
         if ... in args:
             # Replace ... with current expression
@@ -212,12 +219,10 @@ class FunctionExpression:
                 if arg is ...:
                     all_args.append(self.expression)
                 else:
-                    all_args.append(literal(arg))
+                    all_args.append(_to_sql_arg(arg))
         else:
             # Default behavior: current expression as first argument
-            all_args = [self.expression]
-            for arg in args:
-                all_args.append(literal(arg))
+            all_args = [self.expression] + [_to_sql_arg(arg) for arg in args]
 
         # Use func to create the raw function call
         raw_func = getattr(_sa_func, sql)
@@ -425,6 +430,38 @@ class _FuncWrapper:
 
         def nth_value(self, col: Any, n: int) -> NthValueFunction: ...
 
+        def raw(self, sql: str, *args) -> FunctionExpression: ...
+
+    def raw(self, sql: str, *args) -> "FunctionExpression":
+        """Call an arbitrary SQL function by name.
+
+        Unlike col.raw() / FunctionExpression.raw() which insert the current
+        expression as the first argument, this standalone form takes the function
+        name and all arguments explicitly.
+
+        Args:
+            sql: SQL function name (e.g. "ts_rank", "to_tsvector")
+            *args: Arguments passed to the function. SQLAlchemy expressions
+                   (ColumnElement, FunctionExpression) are used as-is; plain
+                   Python values are wrapped with literal().
+
+        Examples:
+            func.raw("ts_rank", DocumentIndexes.content_vector, query_vec)
+            # → ts_rank(document_indexes.content_vector, <query_vec>)
+
+            func.raw("to_tsvector", "'simple'::regconfig", "some text")
+            # → to_tsvector('simple'::regconfig, 'some text')
+        """
+        from sqlalchemy import literal
+
+        def _to_sql_arg(arg):
+            if isinstance(arg, (ColumnElement, FunctionExpression)):
+                return arg
+            return literal(arg)
+
+        sa_func = getattr(_sa_func, sql)
+        return FunctionExpression(sa_func(*[_to_sql_arg(a) for a in args]))
+
     def __getattr__(self, name: str) -> Any:
         """Delegate to SQLAlchemy func for all other functions."""
         return getattr(_sa_func, name)

{sqlobjects-1.5.0 → sqlobjects-1.7.0}/sqlobjects/fields/types/comparators.py

@@ -50,6 +50,12 @@ class ComparatorMixin:
 
     def raw(self, sql: str, *args, **kwargs) -> FunctionExpression:
         from sqlalchemy import literal
+        from sqlalchemy.sql.elements import ColumnElement
+
+        def _to_sql_arg(arg):
+            if isinstance(arg, (ColumnElement, FunctionExpression)):
+                return arg
+            return literal(arg)
 
         if ... in args:
             all_args = []
@@ -57,9 +63,9 @@ class ComparatorMixin:
                 if arg is ...:
                     all_args.append(self)
                 else:
-                    all_args.append(literal(arg))
+                    all_args.append(_to_sql_arg(arg))
         else:
-            all_args = [self] + [literal(arg) for arg in args]
+            all_args = [self] + [_to_sql_arg(arg) for arg in args]
         raw_func = getattr(func, sql)
         return FunctionExpression(raw_func(*all_args, **kwargs))
 

{sqlobjects-1.5.0 → sqlobjects-1.7.0}/sqlobjects/metadata.py

@@ -22,6 +22,7 @@ __all__ = [
     "index",
     "constraint",
     "unique",
+    "foreignkey",
 ]
 
 _FIELD_NAME_PATTERN = re.compile(r"\b([a-zA-Z_][a-zA-Z0-9_]*)\b")
@@ -37,7 +38,7 @@ class _RawModelConfig:
     verbose_name_plural: str | None = None
     ordering: list[str] = field(default_factory=list)
     indexes: list[Index] = field(default_factory=list)
-    constraints: list[CheckConstraint | UniqueConstraint] = field(default_factory=list)
+    constraints: list[CheckConstraint | UniqueConstraint | ForeignKeyConstraint] = field(default_factory=list)
     description: str | None = None
     db_options: dict[str, dict[str, Any]] = field(default_factory=dict)
     custom: dict[str, Any] = field(default_factory=dict)
@@ -52,7 +53,7 @@ class ModelConfig:
     verbose_name_plural: str
     ordering: list[str] = field(default_factory=list)
     indexes: list[Index] = field(default_factory=list)
-    constraints: list[CheckConstraint | UniqueConstraint] = field(default_factory=list)
+    constraints: list[CheckConstraint | UniqueConstraint | ForeignKeyConstraint] = field(default_factory=list)
     description: str | None = None
     db_options: dict[str, dict[str, Any]] = field(default_factory=dict)
     custom: dict[str, Any] = field(default_factory=dict)
@@ -1109,3 +1110,55 @@ def unique(
         >>> unique("first_name", "last_name", name="uq_full_name")
     """
     return UniqueConstraint(*fields, name=name, **kwargs)
+
+
+def foreignkey(
+    fields: str | list[str],
+    references: str | list[str],
+    *,
+    name: str | None = None,
+    ondelete: str | None = None,
+    onupdate: str | None = None,
+    deferrable: bool = False,
+    initially: str = "IMMEDIATE",
+    **kwargs: Any,
+) -> ForeignKeyConstraint:
+    """Create a ForeignKeyConstraint with convenient field name support.
+
+    Use this in Config.constraints for explicit constraint definition, custom
+    names, or composite foreign keys. For simple single-column foreign keys,
+    prefer the ``foreign_key()`` field descriptor instead.
+
+    Args:
+        fields: Local field name(s) as string or list of strings.
+        references: Referenced column(s) as "Table.column" or list thereof.
+            Supports class names (e.g. "User.id") or table names (e.g. "users.id").
+        name: Constraint name (optional, auto-generated if not provided).
+        ondelete: Referential action on delete (CASCADE, SET NULL, RESTRICT, etc.).
+        onupdate: Referential action on update.
+        deferrable: Whether the constraint can be deferred.
+        initially: Initial deferral state ("IMMEDIATE" or "DEFERRED").
+        **kwargs: Additional SQLAlchemy ForeignKeyConstraint arguments.
+
+    Returns:
+        SQLAlchemy ForeignKeyConstraint instance.
+
+    Examples:
+        >>> foreignkey("author_id", "User.id")
+        >>> foreignkey("author_id", "User.id", name="fk_posts_author", ondelete="CASCADE")
+        >>> foreignkey(["a_id", "b_id"], ["A.id", "B.id"])
+    """
+    if isinstance(fields, str):
+        fields = [fields]
+    if isinstance(references, str):
+        references = [references]
+    return ForeignKeyConstraint(
+        fields,
+        references,
+        name=name,
+        ondelete=ondelete,
+        onupdate=onupdate,
+        deferrable=deferrable or None,
+        initially=initially if deferrable else None,
+        **kwargs,
+    )

{sqlobjects-1.5.0 → sqlobjects-1.7.0/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.5.0
+Version: 1.7.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>