sql_fusion 1.2.0__tar.gz → 1.2.2__tar.gz

{sql_fusion-1.2.0 → sql_fusion-1.2.2}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: sql_fusion
-Version: 1.2.0
+Version: 1.2.2
 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)
@@ -71,6 +72,22 @@ SQL Fusion is built for the middle ground:
 
 In short, the goal is to keep the ergonomics of a lightweight builder while still covering the parts of SQL that matter in real applications.
 
+### Why not SQLAlchemy ORM or Core?
+
+SQLAlchemy is an excellent tool, but it is also a much heavier and more universal system:
+
+- it brings a larger abstraction surface than this project needs
+- it is optimized for a broad ORM and Core ecosystem, not only for a small SQL builder
+- some connectors and databases still do not have first-class SQLAlchemy integrations, which can make adoption less straightforward in mixed environments
+
+SQLAlchemy Core is closer to SQL Fusion than the full ORM, but it still carries more machinery than this project is meant to expose:
+
+- it is part of a broader ecosystem with dialects, compilation layers, and extra conventions
+- it can feel more verbose when you only want a small chainable builder
+- some connectors and databases still do not have smooth SQLAlchemy Core support, so portability can depend on the backend
+
+SQL Fusion is intentionally narrower so it can stay lightweight, easy to embed, and practical for DB-API style backends without extra complexity.
+
 ## What You Get
 
 - `SELECT`, `INSERT`, `UPDATE`, and `DELETE` builders
@@ -404,6 +421,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(query1, query2, all_=False)`
+- `except_(query1, query2, 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.2.0 → sql_fusion-1.2.2}/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)
@@ -57,6 +58,22 @@ SQL Fusion is built for the middle ground:
 
 In short, the goal is to keep the ergonomics of a lightweight builder while still covering the parts of SQL that matter in real applications.
 
+### Why not SQLAlchemy ORM or Core?
+
+SQLAlchemy is an excellent tool, but it is also a much heavier and more universal system:
+
+- it brings a larger abstraction surface than this project needs
+- it is optimized for a broad ORM and Core ecosystem, not only for a small SQL builder
+- some connectors and databases still do not have first-class SQLAlchemy integrations, which can make adoption less straightforward in mixed environments
+
+SQLAlchemy Core is closer to SQL Fusion than the full ORM, but it still carries more machinery than this project is meant to expose:
+
+- it is part of a broader ecosystem with dialects, compilation layers, and extra conventions
+- it can feel more verbose when you only want a small chainable builder
+- some connectors and databases still do not have smooth SQLAlchemy Core support, so portability can depend on the backend
+
+SQL Fusion is intentionally narrower so it can stay lightweight, easy to embed, and practical for DB-API style backends without extra complexity.
+
 ## What You Get
 
 - `SELECT`, `INSERT`, `UPDATE`, and `DELETE` builders
@@ -390,6 +407,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(query1, query2, all_=False)`
+- `except_(query1, query2, 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.2.0 → sql_fusion-1.2.2}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "sql_fusion"
-version = "1.2.0"
+version = "1.2.2"
 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.2.0 → sql_fusion-1.2.2}/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

{sql_fusion-1.2.0 → sql_fusion-1.2.2}/src/sql_fusion/query/sets.py

@@ -57,11 +57,11 @@ class union(_set_operation):
         self,
         query1: AbstractQuery,
         query2: AbstractQuery,
-        all: bool = False,  # noqa: A002
+        all_: bool = False,
         by_name: bool = False,
     ) -> None:
         super().__init__(query1, query2)
-        self._all = all
+        self._all = all_
         self._by_name = by_name
 
     def _operator_sql(self) -> str: