sqlobjects 1.2.4__tar.gz → 1.3.0__tar.gz

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

@@ -1,3 +1,16 @@
+## 1.3.0 (2026-03-10)
+
+### Feat
+
+- **fields**: support class name reference in foreign_key() with delayed matching
+
+## 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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.2.4"
+version = "1.3.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.2.4 → sqlobjects-1.3.0}/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.4 → sqlobjects-1.3.0}/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.4 → sqlobjects-1.3.0}/sqlobjects/fields/functions.py

@@ -8,6 +8,22 @@ from .core import Column, column
 from .shortcuts import ComputedColumn, IdentityColumn
 
 
+def _extract_table_or_class_name(reference: str) -> str | None:
+    """从 'X.col' 或 'schema.X.col' 中提取 X（可能是表名或类名）。
+
+    Returns:
+        X 部分，用于后续延迟匹配；格式不合法时返回 None
+    """
+    parts = reference.split(".")
+    if len(parts) == 2:
+        # "X.col"
+        return parts[0]
+    if len(parts) == 3:
+        # "schema.X.col"
+        return parts[1]
+    return None
+
+
 def identity(
     *,
     start: int = 1,
@@ -76,7 +92,10 @@ def foreign_key(
     """Create foreign key column with database constraint behavior.
 
     Args:
-        reference: Foreign key reference in format "table.column"
+        reference: Foreign key reference in format "X.column" where X can be either
+            a model class name (e.g. "User.id", "UserProfile.id") or a database table
+            name (e.g. "users.id"). Class names are automatically resolved to table
+            names via delayed matching. Schema is also supported: "schema.X.column".
         type: Column type, "auto" for automatic type inference
         nullable: Whether column can be null
         ondelete: Database constraint behavior when referenced object is deleted
@@ -89,12 +108,15 @@ def foreign_key(
         Column descriptor with foreign key constraint
 
     Examples:
-        # Basic usage with auto type inference
+        # Using class name (resolved automatically)
+        author_id: Column[int] = foreign_key("User.id")
+
+        # Using table name directly (also works)
         author_id: Column[int] = foreign_key("users.id")
 
         # Complete constraint configuration
         author_id: Column[int] = foreign_key(
-            "users.id",
+            "User.id",
             ondelete="CASCADE",
             onupdate="CASCADE",
             nullable=False
@@ -102,7 +124,7 @@ def foreign_key(
 
         # Deferred constraint for circular references
         parent_id: Column[int] = foreign_key(
-            "categories.id",
+            "Category.id",
             deferrable=True,
             initially="DEFERRED"
         )
@@ -122,9 +144,16 @@ def foreign_key(
         fk_kwargs["deferrable"] = True
         fk_kwargs["initially"] = initially
 
-    # Create ForeignKey constraint
+    # Reference is passed directly to SQLAlchemy; delayed matching in
+    # ModelProcessor._resolve_class_foreign_keys will correct the table
+    # name if the first segment turns out to be a class name.
     fk_constraint = ForeignKey(reference, **fk_kwargs)
 
+    # Store the table-or-class segment for delayed resolution
+    table_or_class = _extract_table_or_class_name(reference)
+    if table_or_class:
+        fk_constraint.info["_fk_ref"] = table_or_class
+
     # Use existing column() function with foreign key
     return column(
         type=type,

{sqlobjects-1.2.4 → sqlobjects-1.3.0}/sqlobjects/fields/types/comparators.py

@@ -323,13 +323,62 @@ class DateTimeComparator(ComparatorMixin, DateTime.Comparator):  # type: ignore[
 
 
 class JSONComparator(ComparatorMixin, JSON.Comparator):  # type: ignore[reportIncompatibleMethodOverride]
-    """JSON type comparator with JSON extraction and manipulation methods."""
+    """MySQL JSON type comparator. For PostgreSQL, use jsonb type instead."""
 
-    def extract_path(self, path) -> FunctionExpression:
-        return FunctionExpression(func.json_extract_path(self, path))
+    def json_extract(self, path: str) -> FunctionExpression:
+        """JSON_EXTRACT(col, path) - e.g. json_extract('$.name')"""
+        return FunctionExpression(func.json_extract(self, path))
 
-    def extract_text(self, path) -> FunctionExpression:
-        return FunctionExpression(func.json_extract_path_text(self, path))
+    def json_unquote(self, path: str) -> FunctionExpression:
+        """JSON_UNQUOTE(JSON_EXTRACT(col, path)) - returns unquoted string value"""
+        return FunctionExpression(func.json_unquote(func.json_extract(self, path)))
+
+    def json_contains(self, other, path: str | None = None) -> FunctionExpression:
+        """JSON_CONTAINS(col, val[, path]) - check if JSON contains value"""
+        import json
+
+        from sqlalchemy import literal
+
+        value = [other] if not isinstance(other, (list, dict)) else other
+        json_val = literal(json.dumps(value))
+        if path is not None:
+            return FunctionExpression(func.json_contains(self, json_val, path))
+        return FunctionExpression(func.json_contains(self, json_val))
+
+    def json_contains_path(self, *paths: str, match: str = "one") -> FunctionExpression:
+        """JSON_CONTAINS_PATH(col, 'one'|'all', path, ...) - check if path(s) exist"""
+        return FunctionExpression(func.json_contains_path(self, match, *paths))
+
+    def json_length(self, path: str | None = None) -> FunctionExpression:
+        """JSON_LENGTH(col[, path]) - array/object length"""
+        if path is not None:
+            return FunctionExpression(func.json_length(self, path))
+        return FunctionExpression(func.json_length(self))
+
+    def json_keys(self, path: str | None = None) -> FunctionExpression:
+        """JSON_KEYS(col[, path]) - return all keys as JSON array"""
+        if path is not None:
+            return FunctionExpression(func.json_keys(self, path))
+        return FunctionExpression(func.json_keys(self))
+
+    def json_overlaps(self, other) -> FunctionExpression:
+        """JSON_OVERLAPS(col, val) - check if two JSON documents share any key-value pairs (MySQL 8.0+)"""
+        import json
+
+        from sqlalchemy import literal
+
+        value = other if isinstance(other, str) else json.dumps(other)
+        return FunctionExpression(func.json_overlaps(self, literal(value)))
+
+    def json_search(self, value: str, match: str = "one", path: str | None = None) -> FunctionExpression:
+        """JSON_SEARCH(col, 'one'|'all', val[, path]) - find path of value"""
+        if path is not None:
+            return FunctionExpression(func.json_search(self, match, value, None, path))
+        return FunctionExpression(func.json_search(self, match, value))
+
+    def json_type(self) -> FunctionExpression:
+        """JSON_TYPE(col) - return JSON value type as string"""
+        return FunctionExpression(func.json_type(self))
 
 
 class BooleanComparator(ComparatorMixin, Boolean.Comparator):  # type: ignore[reportIncompatibleMethodOverride]

{sqlobjects-1.2.4 → sqlobjects-1.3.0}/sqlobjects/fields/types/registry.py

@@ -1,9 +1,10 @@
 import inspect
 from typing import Any, Callable, NotRequired, TypedDict
 
+from sqlalchemy.dialects.mysql import JSON
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.sql.sqltypes import (
     ARRAY,
-    JSON,
     BigInteger,
     Boolean,
     Date,
@@ -344,14 +345,15 @@ class TypeRegistry:
             (Interval, "interval", DateTimeComparator, [], {}),
             (LargeBinary, "binary", DefaultComparator, ["bytes"], {}),
             (Uuid, "uuid", StringComparator, [], {}),
-            (JSON, "json", JSONComparator, ["dict"], {}),
         ]
 
-        # Special types
+        # Special types: dialect-specific or non-standard types
         special_types = [
-            (ARRAY, "array", DefaultComparator, [], {}),
+            (ARRAY, "array", DefaultComparator, [], {}),  # PostgreSQL only
             (Enum, "enum", DefaultComparator, [], {}),
             (Auto, "auto", DefaultComparator, [], {}),
+            (JSON, "json", JSONComparator, ["dict"], {}),  # MySQL: contains -> JSON_CONTAINS
+            (JSONB, "jsonb", JSONB.Comparator, [], {}),  # PostgreSQL: contains -> @>
         ]
 
         for field_type, name, comparator, aliases, defaults in builtin_types + special_types:

{sqlobjects-1.2.4 → sqlobjects-1.3.0}/sqlobjects/metadata.py

@@ -368,6 +368,9 @@ class ModelProcessor(type):
             # Auto-register model to ModelRegistry
             registry.register_model(cast(type["ObjectModel"], cls))
 
+            # Resolve class name foreign key references to actual table names
+            mcs._resolve_class_foreign_keys(registry)
+
             # Process pending M2M tables
             registry.process_pending_m2m()
 
@@ -851,6 +854,40 @@ class ModelProcessor(type):
 
         cls.__eq__ = __eq__
 
+    @classmethod
+    def _resolve_class_foreign_keys(mcs, registry):
+        """延迟解析外键引用：优先按类名匹配，匹配不到则视为表名。
+
+        foreign_key("User.id") 传入时原样交给 SQLAlchemy（_colspec="User.id"）。
+        每次新模型注册后，此方法遍历所有 FK：
+        1. 取出 info["_fk_ref"]（即 "." 前的那段，如 "User"）
+        2. 尝试在 registry 中按类名查找模型
+        3. 找到 → 替换 _colspec 为实际表名，标记 _resolved
+        4. 找不到 → 保留原样（视为已经是表名）
+        """
+        for table in registry.tables.values():
+            for col in table.columns:
+                for fk in col.foreign_keys:
+                    fk_info = fk.info
+                    if fk_info.get("_fk_resolved"):
+                        continue
+                    ref_name = fk_info.get("_fk_ref")
+                    if not ref_name:
+                        continue
+                    model = registry.get_model(ref_name)
+                    if not model or not hasattr(model, "__table__"):
+                        continue
+                    # Found matching model — rewrite _colspec to actual table name
+                    actual_table = model.__table__.name
+                    schema, tname, colname = fk._column_tokens
+                    if tname != actual_table:
+                        if schema:
+                            fk._colspec = f"{schema}.{actual_table}.{colname}"
+                        else:
+                            fk._colspec = f"{actual_table}.{colname}"
+                        fk.__dict__.pop("_column_tokens", None)
+                    fk_info["_fk_resolved"] = True
+
     @classmethod
     def _bind_column_attributes_to_table(mcs, cls: Any, table) -> None:
         """Bind ColumnAttribute instances to their corresponding table columns.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.2.4
+Version: 1.3.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>