sql_fusion 1.1.0__tar.gz → 1.2.1__tar.gz

{sql_fusion-1.1.0 → sql_fusion-1.2.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: sql_fusion
-Version: 1.1.0
+Version: 1.2.1
 Summary: Python query builder with a focus on composability and reusability.
 Author: Mastermind-U
 Author-email: Mastermind-U <rex49513@gmail.com>
-Requires-Python: >=3.14
+Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/Mastermind-U/sql_fusion
 Project-URL: Documentation, https://github.com/Mastermind-U/sql_fusion/blob/main/README.md
 Project-URL: Repository, https://github.com/Mastermind-U/sql_fusion.git
@@ -40,6 +40,7 @@ That makes it easy to plug into your own connection layer.
 - [Quickstart: psycopg3](#quickstart-psycopg3)
 - [Query Basics](#query-basics)
 - [Subquery Example](#subquery-example)
+- [Set Operations](#set-operations)
 - [Method Reference](#method-reference)
 - [Functions](#functions)
 - [CTEs](#ctes)
@@ -77,6 +78,7 @@ In short, the goal is to keep the ergonomics of a lightweight builder while stil
 - automatic table aliases
 - composable conditions with `AND`, `OR`, and `NOT`
 - joins, subqueries, and CTEs
+- set operations with `UNION`, `INTERSECT`, and `EXCEPT`
 - ordering and grouping with `GROUP BY`, `ROLLUP`, `CUBE`, and `GROUPING SETS`
 - aggregate and custom SQL functions through `func`
 - backend-specific SQL rewrites through compile expressions
@@ -113,10 +115,13 @@ from sql_fusion import (
     Column,
     Table,
     delete,
+    except_,
     func,
     insert,
+    intersect,
     select,
-    text,
+    union,
+    text_op,
     update,
 )
 ```
@@ -400,6 +405,94 @@ paid_orders = (
 query, params = select().from_(paid_orders).compile()
 ```
 
+## Set Operations
+
+SQL Fusion supports compound queries through three small wrapper classes:
+
+- `union(query1, query2, all=False, by_name=False)`
+- `intersect(q1, q2, all_=False)`
+- `except_(q1, q2, all_=False)`
+
+Each builder accepts two query objects and returns a new query that compiles to
+the matching SQL set operation.
+
+### `union(...)`
+
+```python
+users = Table("users")
+archived_users = Table("archived_users")
+
+active_users = select(users.id, users.name).from_(users).where_by(status="active")
+archived_active_users = (
+    select(archived_users.id, archived_users.name)
+    .from_(archived_users)
+    .where_by(status="active")
+)
+
+query, params = union(active_users, archived_active_users).compile()
+```
+
+Use `all=True` for `UNION ALL`:
+
+```python
+query, params = union(active_users, archived_active_users, all=True).compile()
+```
+
+Use `by_name=True` when the two result sets expose the same logical columns in
+different orders:
+
+```python
+left = select(users.id, users.name).from_(users)
+right = select(archived_users.name, archived_users.id).from_(archived_users)
+
+query, params = union(left, right, all=True, by_name=True).compile()
+```
+
+### `intersect(...)`
+
+```python
+users = Table("users")
+premium_users = Table("premium_users")
+
+active_users = select(users.id).from_(users).where_by(status="active")
+premium_active_users = (
+    select(premium_users.id).from_(premium_users).where_by(status="active")
+)
+
+query, params = intersect(active_users, premium_active_users).compile()
+```
+
+Use `all_=True` for `INTERSECT ALL`:
+
+```python
+query, params = intersect(
+    active_users,
+    premium_active_users,
+    all_=True,
+).compile()
+```
+
+### `except_(...)`
+
+```python
+users = Table("users")
+banned_users = Table("banned_users")
+
+all_users = select(users.id).from_(users)
+banned_user_ids = select(banned_users.id).from_(banned_users)
+
+query, params = except_(all_users, banned_user_ids).compile()
+```
+
+Use `all_=True` for `EXCEPT ALL`:
+
+```python
+query, params = except_(all_users, banned_user_ids, all_=True).compile()
+```
+
+These builders preserve the parameter order from left to right, so the returned
+`params` tuple can be passed directly to DB-API drivers.
+
 ### Having Example
 
 ```python

{sql_fusion-1.1.0 → sql_fusion-1.2.1}/README.md

@@ -26,6 +26,7 @@ That makes it easy to plug into your own connection layer.
 - [Quickstart: psycopg3](#quickstart-psycopg3)
 - [Query Basics](#query-basics)
 - [Subquery Example](#subquery-example)
+- [Set Operations](#set-operations)
 - [Method Reference](#method-reference)
 - [Functions](#functions)
 - [CTEs](#ctes)
@@ -63,6 +64,7 @@ In short, the goal is to keep the ergonomics of a lightweight builder while stil
 - automatic table aliases
 - composable conditions with `AND`, `OR`, and `NOT`
 - joins, subqueries, and CTEs
+- set operations with `UNION`, `INTERSECT`, and `EXCEPT`
 - ordering and grouping with `GROUP BY`, `ROLLUP`, `CUBE`, and `GROUPING SETS`
 - aggregate and custom SQL functions through `func`
 - backend-specific SQL rewrites through compile expressions
@@ -99,10 +101,13 @@ from sql_fusion import (
     Column,
     Table,
     delete,
+    except_,
     func,
     insert,
+    intersect,
     select,
-    text,
+    union,
+    text_op,
     update,
 )
 ```
@@ -386,6 +391,94 @@ paid_orders = (
 query, params = select().from_(paid_orders).compile()
 ```
 
+## Set Operations
+
+SQL Fusion supports compound queries through three small wrapper classes:
+
+- `union(query1, query2, all=False, by_name=False)`
+- `intersect(q1, q2, all_=False)`
+- `except_(q1, q2, all_=False)`
+
+Each builder accepts two query objects and returns a new query that compiles to
+the matching SQL set operation.
+
+### `union(...)`
+
+```python
+users = Table("users")
+archived_users = Table("archived_users")
+
+active_users = select(users.id, users.name).from_(users).where_by(status="active")
+archived_active_users = (
+    select(archived_users.id, archived_users.name)
+    .from_(archived_users)
+    .where_by(status="active")
+)
+
+query, params = union(active_users, archived_active_users).compile()
+```
+
+Use `all=True` for `UNION ALL`:
+
+```python
+query, params = union(active_users, archived_active_users, all=True).compile()
+```
+
+Use `by_name=True` when the two result sets expose the same logical columns in
+different orders:
+
+```python
+left = select(users.id, users.name).from_(users)
+right = select(archived_users.name, archived_users.id).from_(archived_users)
+
+query, params = union(left, right, all=True, by_name=True).compile()
+```
+
+### `intersect(...)`
+
+```python
+users = Table("users")
+premium_users = Table("premium_users")
+
+active_users = select(users.id).from_(users).where_by(status="active")
+premium_active_users = (
+    select(premium_users.id).from_(premium_users).where_by(status="active")
+)
+
+query, params = intersect(active_users, premium_active_users).compile()
+```
+
+Use `all_=True` for `INTERSECT ALL`:
+
+```python
+query, params = intersect(
+    active_users,
+    premium_active_users,
+    all_=True,
+).compile()
+```
+
+### `except_(...)`
+
+```python
+users = Table("users")
+banned_users = Table("banned_users")
+
+all_users = select(users.id).from_(users)
+banned_user_ids = select(banned_users.id).from_(banned_users)
+
+query, params = except_(all_users, banned_user_ids).compile()
+```
+
+Use `all_=True` for `EXCEPT ALL`:
+
+```python
+query, params = except_(all_users, banned_user_ids, all_=True).compile()
+```
+
+These builders preserve the parameter order from left to right, so the returned
+`params` tuple can be passed directly to DB-API drivers.
+
 ### Having Example
 
 ```python

{sql_fusion-1.1.0 → sql_fusion-1.2.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "sql_fusion"
-version = "1.1.0"
+version = "1.2.1"
 description = "Python query builder with a focus on composability and reusability."
 readme = "README.md"
 authors = [{ name = "Mastermind-U", email = "rex49513@gmail.com" }]
-requires-python = ">=3.14"
+requires-python = ">=3.11"
 dependencies = []
 
 [project.urls]

{sql_fusion-1.1.0 → sql_fusion-1.2.1}/src/sql_fusion/__init__.py

@@ -2,6 +2,7 @@ from .composite_table import Alias, Column, Table, func, text_op
 from .query.delete import delete
 from .query.insert import insert
 from .query.select import select
+from .query.sets import except_, intersect, union
 from .query.update import update
 
 __all__ = [
@@ -9,9 +10,12 @@ __all__ = [
     "Column",
     "Table",
     "delete",
+    "except_",
     "func",
     "insert",
+    "intersect",
     "select",
     "text_op",
+    "union",
     "update",
 ]

{sql_fusion-1.1.0 → sql_fusion-1.2.1}/src/sql_fusion/composite_table.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from collections.abc import Iterable
 from copy import copy
 from typing import Any, Callable, Self
@@ -511,7 +513,8 @@ class Condition:
             )
             sql, op_params = operator.to_sql_ref(subquery_sql)
             return apply_negation(
-                sql, col_params + subquery_params + op_params
+                sql,
+                col_params + subquery_params + op_params,
             )
 
         sql, op_params = operator.to_sql(self.value)

sql_fusion-1.2.1/src/sql_fusion/query/__init__.py

@@ -0,0 +1,15 @@
+from .delete import delete
+from .insert import insert
+from .select import select
+from .sets import except_, intersect, union
+from .update import update
+
+__all__ = [
+    "delete",
+    "except_",
+    "insert",
+    "intersect",
+    "select",
+    "union",
+    "update",
+]

sql_fusion-1.2.1/src/sql_fusion/query/sets.py

@@ -0,0 +1,107 @@
+from typing import Any
+
+from sql_fusion.composite_table import AbstractQuery, AliasRegistry
+
+
+class _set_operation(AbstractQuery):
+    def __init__(
+        self,
+        query1: AbstractQuery,
+        query2: AbstractQuery,
+    ) -> None:
+        super().__init__(table=None, columns=())
+        self._query1 = query1
+        self._query2 = query2
+
+    def _operator_sql(self) -> str:
+        raise NotImplementedError()
+
+    def _render_query(
+        self,
+        query: AbstractQuery,
+        alias_registry: AliasRegistry,
+    ) -> tuple[str, tuple[Any, ...]]:
+        return query.build_query(alias_registry)
+
+    def build_query(
+        self,
+        alias_registry: AliasRegistry | None = None,
+    ) -> tuple[str, tuple[Any, ...]]:
+        registry = alias_registry or self._alias_registry
+        params: list[Any] = []
+
+        with_sql, with_params = self._build_with_clause(registry)
+        params.extend(with_params)
+
+        left_sql, left_params = self._render_query(self._query1, registry)
+        right_sql, right_params = self._render_query(self._query2, registry)
+
+        query_parts: list[str] = []
+        if with_sql:
+            query_parts.append(with_sql)
+        query_parts.append(
+            f"{left_sql} {self._operator_sql()} {right_sql}",
+        )
+
+        params.extend(left_params)
+        params.extend(right_params)
+
+        return self._apply_compile_expressions(
+            " ".join(query_parts),
+            tuple(params),
+        )
+
+
+class union(_set_operation):
+    def __init__(
+        self,
+        query1: AbstractQuery,
+        query2: AbstractQuery,
+        all: bool = False,  # noqa: A002
+        by_name: bool = False,
+    ) -> None:
+        super().__init__(query1, query2)
+        self._all = all
+        self._by_name = by_name
+
+    def _operator_sql(self) -> str:
+        operator = "UNION"
+        if self._all:
+            operator += " ALL"
+        if self._by_name:
+            operator += " BY NAME"
+        return operator
+
+
+class intersect(_set_operation):
+    def __init__(
+        self,
+        query1: AbstractQuery,
+        query2: AbstractQuery,
+        all_: bool = False,
+    ) -> None:
+        super().__init__(query1, query2)
+        self._all = all_
+
+    def _operator_sql(self) -> str:
+        operator = "INTERSECT"
+        if self._all:
+            operator += " ALL"
+        return operator
+
+
+class except_(_set_operation):
+    def __init__(
+        self,
+        query1: AbstractQuery,
+        query2: AbstractQuery,
+        all_: bool = False,
+    ) -> None:
+        super().__init__(query1, query2)
+        self._all = all_
+
+    def _operator_sql(self) -> str:
+        operator = "EXCEPT"
+        if self._all:
+            operator += " ALL"
+        return operator