sqlobjects 1.0.16__tar.gz → 1.2.0__tar.gz

sqlobjects-1.2.0/CHANGELOG.md

@@ -0,0 +1,142 @@
+## 1.2.0 (2026-02-25)
+
+### Feat
+
+- **metadata**: improve constraint and index naming conventions
+
+## 1.1.0 (2026-02-14)
+
+### Feat
+
+- update custom field type imports to use sqlobjects.fields.types
+- implement CTE (Common Table Expressions) support
+- add support for SQL window functions
+- add EXPLAIN support with dialect-based architecture
+
+### Fix
+
+- update test imports to use DeferredObject instead of DeferredFieldProxy
+
+## 1.0.16 (2025-11-18)
+
+### Fix
+
+- correct ModelMixin inheritance
+
+## 1.0.15 (2025-11-18)
+
+### Feat
+
+- preserve annotate fields and add serialization options
+
+## 1.0.14 (2025-11-18)
+
+### Feat
+
+- add has_session() to check explicit session availability
+
+## 1.0.13 (2025-11-18)
+
+## 1.0.12 (2025-11-18)
+
+### Refactor
+
+- move rules installer to independent scripts
+
+## 1.0.11 (2025-11-18)
+
+### Feat
+
+- add AI assistant rules with auto-install support
+
+## 1.0.10 (2025-11-17)
+
+### Feat
+
+- support Model class in join methods for cleaner API
+
+## 1.0.9 (2025-11-14)
+
+### Feat
+
+- add optional tables parameter to create_tables/drop_tables
+
+## 1.0.8 (2025-11-11)
+
+### Feat
+
+- add model-level relationship loading methods
+- improve relation field type inference
+- refactor relationship proxies
+
+## 1.0.7 (2025-10-14)
+
+### Feat
+
+- add upsert support for PostgreSQL
+
+### Fix
+
+- identity support for PostgreSQL
+
+### Refactor
+
+- consolidate bulk and queryset logic
+
+### Perf
+
+- improve bulk delete performance
+
+## 1.0.6 (2025-10-08)
+
+### Feat
+
+- optimize field cache and state manager
+- implement relationship prefetch support
+- add kwargs parameter support to filter/exclude/get methods
+
+### Refactor
+
+- unify cascade for model and queryset operations
+
+## 1.0.5 (2025-09-25)
+
+### Fix
+
+- generate DDL using column definition order
+
+## 1.0.4 (2025-09-25)
+
+### Feat
+
+- remove unnecessary exception catching
+- implement insert or update using database upsert
+
+### Fix
+
+- use pk column name instead of column instance for pgsql upsert
+
+### Refactor
+
+- move field default value related methods to DataConversionMixin
+
+## 1.0.3 (2025-09-25)
+
+### Fix
+
+- field default/default_factory not working
+
+## 1.0.2 (2025-09-24)
+
+### Feat
+
+- add type support for StringColumn
+- add support for cascade delete in relationships
+- add cascade support to relationship fields
+- add type checking for __registry__
+- use base model to create database tables
+- init public commit
+
+### Fix
+
+- foreign key type inference issue

{sqlobjects-1.0.16/sqlobjects.egg-info → sqlobjects-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.0.16
+Version: 1.2.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>
@@ -246,6 +246,7 @@ sqlobjects-install-rules amazonq  # or cursor, claude, kiro
 - [Relationships](docs/features/05-relationships.md) - Model relationships and loading strategies
 - [Validation & Signals](docs/features/06-validation-signals.md) - Data validation and lifecycle hooks
 - [Performance Optimization](docs/features/07-performance-optimization.md) - Performance tuning and best practices
+- [Custom Field Types](docs/features/08-custom-field-types.md) - Extend with database-specific types
 
 ### Design Documentation
 
@@ -309,6 +310,29 @@ users = await User.objects.raw(
 )
 ```
 
+### Custom Field Types
+
+```python
+# Extend with database-specific types
+from sqlobjects.fields.types.registry import register_field_type
+from sqlalchemy.dialects.postgresql import TSVECTOR
+
+register_field_type(
+    TSVECTOR, "tsvector",
+    comparator=TSVectorComparator
+)
+
+class Document(ObjectModel):
+    content_vector: Column = column(type="tsvector")  # PostgreSQL full-text search
+
+# Query with custom types
+docs = await Document.objects.filter(
+    Document.content_vector.match("python & programming")
+).all()
+```
+
+See [Custom Field Types](docs/features/08-custom-field-types.md) for complete examples.
+
 ## 🧪 Testing
 
 SQLObjects includes comprehensive test coverage:

{sqlobjects-1.0.16 → sqlobjects-1.2.0}/README.md

@@ -217,6 +217,7 @@ sqlobjects-install-rules amazonq  # or cursor, claude, kiro
 - [Relationships](docs/features/05-relationships.md) - Model relationships and loading strategies
 - [Validation & Signals](docs/features/06-validation-signals.md) - Data validation and lifecycle hooks
 - [Performance Optimization](docs/features/07-performance-optimization.md) - Performance tuning and best practices
+- [Custom Field Types](docs/features/08-custom-field-types.md) - Extend with database-specific types
 
 ### Design Documentation
 
@@ -280,6 +281,29 @@ users = await User.objects.raw(
 )
 ```
 
+### Custom Field Types
+
+```python
+# Extend with database-specific types
+from sqlobjects.fields.types.registry import register_field_type
+from sqlalchemy.dialects.postgresql import TSVECTOR
+
+register_field_type(
+    TSVECTOR, "tsvector",
+    comparator=TSVectorComparator
+)
+
+class Document(ObjectModel):
+    content_vector: Column = column(type="tsvector")  # PostgreSQL full-text search
+
+# Query with custom types
+docs = await Document.objects.filter(
+    Document.content_vector.match("python & programming")
+).all()
+```
+
+See [Custom Field Types](docs/features/08-custom-field-types.md) for complete examples.
+
 ## 🧪 Testing
 
 SQLObjects includes comprehensive test coverage:

{sqlobjects-1.0.16 → sqlobjects-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.0.16"
+version = "1.2.0"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"
@@ -49,22 +49,22 @@ Changelog = "https://github.com/XtraVisionsAI/sqlobjects/blob/main/CHANGELOG.md"
 
 [dependency-groups]
 dev = [
-    "pre-commit>=4.4.0",
-    "pyright>=1.1.407",
-    "ruff>=0.14.5",
-    "setuptools>=80.9.0",
+    "pre-commit>=4.5.1",
+    "pyright>=1.1.408",
+    "ruff>=0.15.2",
+    "setuptools>=82.0.0",
 ]
 test = [
     "aiomysql>=0.3.2",
-    "aiosqlite>=0.20.0",
-    "asyncpg>=0.30.0",
-    "pytest>=9.0.1",
+    "aiosqlite>=0.22.1",
+    "asyncpg>=0.31.0",
+    "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
-    "psutil>=7.1.3", # For memory monitoring in performance tests
+    "psutil>=7.2.2", # For memory monitoring in performance tests
 ]
 
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=82.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
@@ -81,7 +81,7 @@ sqlobjects = ["py.typed"]
 
 [[tool.uv.index]]
 name = "tsinghua"
-url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
+url = "https://mirrors.aliyun.com/pypi/simple"
 default = true
 
 [tool.commitizen]

{sqlobjects-1.0.16 → sqlobjects-1.2.0}/sqlobjects/expressions/__init__.py

@@ -1,5 +1,7 @@
 from .aggregate import AggregateExpression
 from .base import ComparisonExpression, QueryExpression
+from .cte import CTEExpression
+from .explain import ExplainResult
 from .function import FunctionExpression, func
 from .scalar import CountExpression, ExistsExpression, ScalarSubquery
 from .subquery import SubqueryExpression
@@ -15,14 +17,30 @@ from .terminal import (
     ValuesExpression,
     ValuesListExpression,
 )
+from .window import (
+    DenseRankFunction,
+    FirstValueFunction,
+    LagFunction,
+    LastValueFunction,
+    LeadFunction,
+    NthValueFunction,
+    NtileFunction,
+    PercentRankFunction,
+    RankFunction,
+    RowNumberFunction,
+    WindowFunction,
+    WindowSpec,
+)
 
 
 __all__ = [
     "func",
     "FunctionExpression",
     "SubqueryExpression",
+    "CTEExpression",
     "QueryExpression",
     "ComparisonExpression",
+    "ExplainResult",
     "AggregateExpression",
     "CountExpression",
     "ExistsExpression",
@@ -37,4 +55,16 @@ __all__ = [
     "DatesExpression",
     "DatetimesExpression",
     "GetItemExpression",
+    "WindowFunction",
+    "WindowSpec",
+    "RowNumberFunction",
+    "RankFunction",
+    "DenseRankFunction",
+    "PercentRankFunction",
+    "NtileFunction",
+    "LagFunction",
+    "LeadFunction",
+    "FirstValueFunction",
+    "LastValueFunction",
+    "NthValueFunction",
 ]

{sqlobjects-1.0.16 → sqlobjects-1.2.0}/sqlobjects/expressions/aggregate.py

@@ -30,6 +30,10 @@ class AggregateExpression(QueryExpression[dict[str, Any]]):
         self._builder = builder
         self._aggregations = aggregations
 
+    def get_query(self):
+        """Return SQLAlchemy query object."""
+        return self._builder.build(self._builder.model_class.get_table())
+
     async def execute(self) -> dict[str, Any]:
         """Execute aggregation query and return results dictionary.
 

{sqlobjects-1.0.16 → sqlobjects-1.2.0}/sqlobjects/expressions/base.py

@@ -42,27 +42,42 @@ class QueryExpression(ABC, Generic[T_Result]):
         pass
 
     @abstractmethod
+    def get_query(self) -> Any:
+        """Get SQLAlchemy query object.
+
+        Returns:
+            SQLAlchemy Select/Update/Delete object
+        """
+        pass
+
     def get_sql(self) -> str:
-        """Generate SQL string for this expression.
+        """Generate SQL string for debugging.
 
         Returns:
             SQL string representation
         """
-        pass
+        query = self.get_query()
+        return str(query.compile(compile_kwargs={"literal_binds": True}))
 
-    def explain(self, analyze: bool = False, verbose: bool = False) -> str:
-        """Generate execution plan for this expression.
+    def explain(self, analyze: bool = False, verbose: bool = False):
+        """Return awaitable EXPLAIN result.
+
+        Usage:
+            plan = await expression.explain()
+            plan = await expression.explain(analyze=True, verbose=True)
 
         Args:
             analyze: Include actual execution statistics
             verbose: Include detailed execution information
 
         Returns:
-            Query execution plan
+            ExplainResult that can be awaited
         """
+        from .explain import ExplainResult
+
         if not self._executor:
             raise RuntimeError("No executor available for explain operation")
-        return self._executor.explain(self.get_sql(), analyze=analyze, verbose=verbose)
+        return ExplainResult(self, analyze, verbose)
 
     def __gt__(self, other) -> "ComparisonExpression":
         """Create greater-than comparison expression."""

sqlobjects-1.2.0/sqlobjects/expressions/cte.py

@@ -0,0 +1,136 @@
+"""CTE (Common Table Expression) support for SQLObjects.
+
+This module provides CTE functionality for building complex queries with
+reusable subqueries and recursive queries.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import CTE as SACTE
+
+
+if TYPE_CHECKING:
+    from sqlobjects.queryset import QuerySet
+
+__all__ = ["CTEExpression"]
+
+
+class CTEExpression:
+    """CTE expression wrapper for query reuse.
+
+    A CTE (Common Table Expression) allows you to define a temporary named
+    result set that can be referenced within a SELECT, INSERT, UPDATE, or
+    DELETE statement.
+
+    Examples:
+        Basic CTE:
+            >>> adults = User.objects.filter(User.age >= 18).cte("adults")
+            >>> result = await User.objects.with_cte(adults).filter(adults.c.age < 30).all()
+
+        Recursive CTE:
+            >>> base = Employee.objects.filter(Employee.manager_id.is_(None)).cte("hierarchy", recursive=True)
+            >>> recursive = Employee.objects.join(base, Employee.manager_id == base.c.id)
+            >>> hierarchy = base.union_all(recursive)
+            >>> all_employees = await Employee.objects.with_cte(hierarchy).select_from(hierarchy).all()
+    """
+
+    def __init__(self, queryset: QuerySet, name: str, recursive: bool = False):
+        """Initialize CTE expression.
+
+        Args:
+            queryset: The QuerySet to convert to CTE
+            name: Name of the CTE
+            recursive: Whether this is a recursive CTE
+        """
+        self._queryset = queryset
+        self._name = name
+        self._recursive = recursive
+        self._cte_obj: SACTE | None = None
+        self._union_query: QuerySet | None = None
+
+    def _build_cte(self, session) -> SACTE:
+        """Build SQLAlchemy CTE object.
+
+        Args:
+            session: Database session for building the query
+
+        Returns:
+            SQLAlchemy CTE object
+        """
+        if self._cte_obj is not None:
+            return self._cte_obj
+
+        # Build base query
+        stmt = self._queryset._builder.build(session)
+
+        # Handle recursive CTE with UNION ALL
+        if self._recursive and self._union_query is not None:
+            # Build recursive part
+            recursive_stmt = self._union_query._builder.build(session)
+
+            # Combine with UNION ALL
+            combined = stmt.union_all(recursive_stmt)
+            cte_obj = combined.cte(self._name, recursive=True)
+        else:
+            # Non-recursive CTE
+            cte_obj = stmt.cte(self._name, recursive=self._recursive)
+
+        self._cte_obj = cte_obj
+        return cte_obj
+
+    @property
+    def c(self) -> Any:
+        """Access CTE columns (similar to Table.c).
+
+        Returns:
+            Column collection for the CTE
+
+        Note:
+            The CTE must be built before accessing columns.
+            This is typically done automatically when used in a query.
+        """
+        if self._cte_obj is None:
+            raise RuntimeError(f"CTE '{self._name}' has not been built yet. Use it in a query with .with_cte() first.")
+        return self._cte_obj.c
+
+    def union_all(self, recursive_queryset: QuerySet) -> CTEExpression:
+        """Add UNION ALL clause for recursive CTE.
+
+        This method is used to define the recursive part of a recursive CTE.
+
+        Args:
+            recursive_queryset: QuerySet for the recursive part
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> base = Employee.objects.filter(Employee.manager_id.is_(None)).cte("tree", recursive=True)
+            >>> recursive = Employee.objects.join(base, Employee.manager_id == base.c.id)
+            >>> tree = base.union_all(recursive)
+        """
+        if not self._recursive:
+            raise ValueError(
+                f"union_all() can only be used with recursive CTEs. "
+                f"Set recursive=True when creating CTE '{self._name}'."
+            )
+
+        self._union_query = recursive_queryset
+        return self
+
+    @property
+    def name(self) -> str:
+        """Get CTE name."""
+        return self._name
+
+    @property
+    def is_recursive(self) -> bool:
+        """Check if this is a recursive CTE."""
+        return self._recursive
+
+    def __repr__(self) -> str:
+        """String representation."""
+        recursive_str = ", recursive=True" if self._recursive else ""
+        return f"CTEExpression(name='{self._name}'{recursive_str})"

sqlobjects-1.2.0/sqlobjects/expressions/explain.py

@@ -0,0 +1,38 @@
+"""EXPLAIN query analysis support."""
+
+
+class ExplainResult:
+    """Awaitable result for EXPLAIN operations.
+
+    This class wraps EXPLAIN query execution and makes it awaitable,
+    providing a clean async interface for query plan analysis.
+
+    Examples:
+        plan = await User.objects.filter(User.age > 25).explain()
+        analysis = await User.objects.all().explain(analyze=True, verbose=True)
+    """
+
+    def __init__(self, expression, analyze: bool, verbose: bool):
+        """Initialize EXPLAIN result.
+
+        Args:
+            expression: QueryExpression to explain
+            analyze: Include actual execution statistics
+            verbose: Include detailed execution information
+        """
+        self.expression = expression
+        self.analyze = analyze
+        self.verbose = verbose
+
+    def __await__(self):
+        """Make this object awaitable."""
+        return self._execute().__await__()
+
+    async def _execute(self) -> str:
+        """Execute EXPLAIN and return plan.
+
+        Returns:
+            Query execution plan as string
+        """
+        query = self.expression.get_query()
+        return await self.expression._executor.explain(query, self.analyze, self.verbose)