sql_fusion 1.0.0__tar.gz → 1.1.0__tar.gz

sql_fusion-1.0.0/README.md → sql_fusion-1.1.0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.3
+Name: sql_fusion
+Version: 1.1.0
+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
+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
+Project-URL: Source, https://github.com/Mastermind-U/sql_fusion
+Project-URL: Issues, https://github.com/Mastermind-U/sql_fusion/issues
+Description-Content-Type: text/markdown
+
 # SQL Fusion
 
 SQL Fusion is a lightweight, chainable SQL query builder for Python with zero dependencies.
@@ -17,6 +31,7 @@ That makes it easy to plug into your own connection layer.
 
 ## Table of Contents
 
+- [Motivation](#motivation)
 - [What You Get](#what-you-get)
 - [Installation](#installation)
 - [Public API](#public-api)
@@ -30,6 +45,31 @@ That makes it easy to plug into your own connection layer.
 - [CTEs](#ctes)
 - [Custom Compile Expressions](#custom-compile-expressions)
 - [What To Remember](#what-to-remember)
+- [Feature Comparison](#feature-comparison)
+
+## Motivation
+
+SQL builders often look similar from the outside, but they make very different trade-offs in practice:
+
+- some are template-driven and mainly render filter fragments
+- some are lightweight CRUD helpers with a small API surface
+- some are broad SQL toolkits with dialect systems and advanced composition features
+- some keep SQL parameterized, while others render a finished SQL string directly
+
+This README compares SQL Fusion with several other Python query builders so it is easier to see where the library fits and what it is intentionally optimized for.
+
+### Why SQL Fusion?
+
+SQL Fusion is built for the middle ground:
+
+- it stays small and chainable instead of turning into a full ORM
+- it keeps SQL parameterized by default, so the caller controls execution safely
+- it gives you SQL-like syntax inside Python, with type hints and a clean separation of clauses, inspired by SQLAlchemy Core but without the heavy machinery of a full expression system
+- it supports real SQL building blocks like joins, subqueries, CTEs, and grouping helpers without forcing a dialect-specific API
+- it adds automatic alias management so common queries stay readable even as they grow
+- it exposes `compile_expression()` for the cases where the final SQL needs a backend-specific rewrite
+
+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.
 
 ## What You Get
 
@@ -37,13 +77,21 @@ That makes it easy to plug into your own connection layer.
 - automatic table aliases
 - composable conditions with `AND`, `OR`, and `NOT`
 - joins, subqueries, and CTEs
-- ordering, joins, subqueries, and CTEs
+- 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
 
 ## Installation
 
 The project targets Python 3.14 or newer.
+Install it from PyPI:
+
+```bash
+pip install sql_fusion
+```
+```bash
+uv add sql_fusion
+```
 
 For local development:
 
@@ -60,17 +108,30 @@ pip install -e .
 ## Public API
 
 ```python
-from sql_fusion import Alias, Table, delete, func, insert, select, update
+from sql_fusion import (
+    Alias,
+    Column,
+    Table,
+    delete,
+    func,
+    insert,
+    select,
+    text,
+    update,
+)
 ```
 
 ### Core Objects
 
 - `Table` represents a real table or a subquery.
+- `Column` is the reusable column object used by `Table` when you want to
+  predeclare columns.
 - `select` creates a `SELECT` builder.
 - `insert` creates an `INSERT` builder.
 - `update` creates an `UPDATE` builder.
 - `delete` creates a `DELETE` builder.
 - `func` is a dynamic SQL function registry.
+- `text_op` builds a condition with a raw SQL operator such as `@>`.
 - `Alias` represents a reusable SQL alias for aggregate expressions and
   `HAVING` conditions.
 
@@ -205,6 +266,26 @@ users = Table("users", alias="u")
 `Table` can also wrap a subquery. In practice, you usually pass a query
 builder directly to `from_()` or `join()`, and the library wraps it for you.
 
+If you want explicit, hint-friendly columns on a table instance, pass them
+when you create it:
+
+```python
+from sql_fusion import Column, Table, select
+
+
+users = Table(
+    "users",
+    Column("id"),
+    Column("name"),
+)
+
+
+query = select(users.id, users.name).from_(users)
+```
+
+This style keeps the column list declared in one place and is verified at
+runtime when you access `users.id` / `users.name`.
+
 ### Conditions
 
 Columns support the usual comparison operators:
@@ -222,6 +303,10 @@ They also support SQL helpers:
 - `.ilike(pattern)`
 - `.in_(values)`
 - `.not_in(values)`
+- `text(column, operator, value)` for backend-specific operators such as
+  PostgreSQL array containment (`@>`).
+
+Use `|` for SQL `OR`. Python's `or` cannot be overloaded for SQL expressions.
 
 Conditions can be combined with:
 
@@ -243,6 +328,19 @@ query = (
 )
 ```
 
+For PostgreSQL-style array containment, `text()` lets you pass the operator
+symbol directly:
+
+```python
+users = Table("users", Column("name"), Column("tags"))
+
+query = (
+    select(users.name)
+    .from_(users)
+    .where(users.name == "bob" or text_op(users.tags, "@>", ["coffee"]))
+)
+```
+
 ### Join Example
 
 ```python
@@ -569,3 +667,31 @@ The library also exposes a few built-in compile-time helpers:
 - query builders are chainable
 - repeated calls to many methods merge rather than overwrite
 - backend support still depends on the database you execute against
+
+## Feature Comparison
+
+
+| Project | Focus | SQL coverage | SQL injection protected | Automatic alias management | Advanced features | Dialect/output model | Takeaway |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Py-QueryBuilder | Template-driven filter rendering | No direct CRUD builder; it renders a `WHERE` fragment into a Jinja template | Yes, via JinjaSQL qmark placeholders and a separate params list | No, subquery and join aliases are template-defined rather than auto-managed by the builder | Nested rule groups, operator mapping, field pruning | Jinja2 + JinjaSQL, SQL formatting | Best for UI-driven search forms, not for composing full statements |
+| simple-query-builder-python | Small mutable CRUD helper | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Mostly yes, because execution uses `?` placeholders and a params tuple; `get_sql(with_values=True)` can inline values for display | No, subquery and join aliases are supplied manually in the input data | `JOIN`, `GROUP BY`, `HAVING`, `UNION`, `EXCEPT`, `INTERSECT`, `LIMIT`, `OFFSET` | SQLite-first, raw SQL string builder | Simple and approachable, but the SQL surface is modest |
+| sqlquerybuilder | Django-ORM-style queryset wrapper | Basic read/write queries | No, it renders a ready SQL string with values embedded into the query text | No, subquery and join aliases are handled manually in query strings | Filters and excludes, joins, grouping, ordering, `extra()`, slicing, `with_nolock()` | SQLite-oriented, with SQL Server pagination branches in code | Convenient for ORM-like chaining, but not aimed at deep SQL composition |
+| python-sql | Rich Pythonic SQL builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Yes, it keeps placeholders separate from args and can switch param styles via flavor | Partial, it can auto-alias tables and some subqueries, while join aliases are still often explicit | `JOIN`, subqueries, CTEs, `DISTINCT ON`, windows, `RETURNING`, `MERGE`, `UNION` / `INTERSECT` / `EXCEPT` | Dialect/flavor system with multiple param styles | Very broad SQL coverage and strong backend flexibility |
+| PyPika | Mature fluent query builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | No by default, it renders literal SQL strings with values injected into the output | Partial, it auto-aliases some subqueries and duplicate joins, but most table and join aliases are explicit | `JOIN`, subqueries, CTEs, set operations, analytics/window helpers, DDL support | Dialect-aware with vendor-specific extensions | One of the broadest and most extensible builders in the set |
+| SQLFactory | General-purpose SQL builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Yes, it emits placeholders and keeps args separately | No, subquery and join aliases are mostly explicit and part of the statement shape | `JOIN`, subselects, CTEs, window functions, set operations, `INSERT ... SELECT`, MySQL-style duplicate-key handling | MySQL / SQLite / PostgreSQL / Oracle / custom dialects, async execution helpers | Full-featured and explicit, with a heavier API than lightweight builders |
+| SQL Fusion | Lightweight chainable builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Yes, it returns `(sql, params)` and leaves binding to the caller | Yes, it auto-assigns stable table aliases and reuses them for subqueries and joins | `JOIN` variants including `CROSS`, `SEMI`, `ANTI`, subqueries, recursive CTEs, `ROLLUP`, `CUBE`, `GROUPING SETS`, functions, comments, `EXPLAIN` / `ANALYZE`, `DELETE RETURNING` | Backend-agnostic, `compile_expression()` hook for rewrites | Best when you want a compact, composable builder with post-processing hooks and no execution layer |
+
+## Syntax Comparison
+
+The examples below are representative shapes, not copy-paste snippets for every library. Where a library exposes a `Table`
+object, the snippet uses it.
+
+| Project | Typical syntax shape |
+| --- | --- |
+| SQL Fusion | `users = Table("users"); orders = Table("orders"); select(users.id, users.name).from_(users).join(orders, users.id == orders.user_id).where(users.active == True).compile()` |
+| PyPika | `users = Table("users"); orders = Table("orders"); Query.from_(users).join(orders).on(users.id == orders.user_id).select(users.id, users.name).where(users.active == True).get_sql()` |
+| python-sql | `user = Table("users"); tuple(user.select(user.name, where=user.active == True))` |
+| SQLFactory | `users = Table("users"); orders = Table("orders"); Select(users.id, users.name, table=users, join=[Join(orders, Eq("users.id", "orders.user_id"))]).where(Eq("users.active", True))` |
+| simple-query-builder-python | `qb.select("users").where([["active", "=", True]]).join("orders", on=[["users.id", "=", "orders.user_id"]]).all()` |
+| sqlquerybuilder | `Queryset("users").filter(active=True).join("orders", on="users.id=orders.user_id")` |
+| Py-QueryBuilder | `QueryBuilder("app.users", filters).render("query.sql", query)` |

sql_fusion-1.0.0/PKG-INFO → sql_fusion-1.1.0/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.3
-Name: sql_fusion
-Version: 1.0.0
-Summary: Add your description here
-Author: Mastermind-U
-Author-email: Mastermind-U <rex49513@gmail.com>
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-
 # SQL Fusion
 
 SQL Fusion is a lightweight, chainable SQL query builder for Python with zero dependencies.
@@ -26,6 +17,7 @@ That makes it easy to plug into your own connection layer.
 
 ## Table of Contents
 
+- [Motivation](#motivation)
 - [What You Get](#what-you-get)
 - [Installation](#installation)
 - [Public API](#public-api)
@@ -39,6 +31,31 @@ That makes it easy to plug into your own connection layer.
 - [CTEs](#ctes)
 - [Custom Compile Expressions](#custom-compile-expressions)
 - [What To Remember](#what-to-remember)
+- [Feature Comparison](#feature-comparison)
+
+## Motivation
+
+SQL builders often look similar from the outside, but they make very different trade-offs in practice:
+
+- some are template-driven and mainly render filter fragments
+- some are lightweight CRUD helpers with a small API surface
+- some are broad SQL toolkits with dialect systems and advanced composition features
+- some keep SQL parameterized, while others render a finished SQL string directly
+
+This README compares SQL Fusion with several other Python query builders so it is easier to see where the library fits and what it is intentionally optimized for.
+
+### Why SQL Fusion?
+
+SQL Fusion is built for the middle ground:
+
+- it stays small and chainable instead of turning into a full ORM
+- it keeps SQL parameterized by default, so the caller controls execution safely
+- it gives you SQL-like syntax inside Python, with type hints and a clean separation of clauses, inspired by SQLAlchemy Core but without the heavy machinery of a full expression system
+- it supports real SQL building blocks like joins, subqueries, CTEs, and grouping helpers without forcing a dialect-specific API
+- it adds automatic alias management so common queries stay readable even as they grow
+- it exposes `compile_expression()` for the cases where the final SQL needs a backend-specific rewrite
+
+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.
 
 ## What You Get
 
@@ -46,13 +63,21 @@ That makes it easy to plug into your own connection layer.
 - automatic table aliases
 - composable conditions with `AND`, `OR`, and `NOT`
 - joins, subqueries, and CTEs
-- ordering, joins, subqueries, and CTEs
+- 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
 
 ## Installation
 
 The project targets Python 3.14 or newer.
+Install it from PyPI:
+
+```bash
+pip install sql_fusion
+```
+```bash
+uv add sql_fusion
+```
 
 For local development:
 
@@ -69,17 +94,30 @@ pip install -e .
 ## Public API
 
 ```python
-from sql_fusion import Alias, Table, delete, func, insert, select, update
+from sql_fusion import (
+    Alias,
+    Column,
+    Table,
+    delete,
+    func,
+    insert,
+    select,
+    text,
+    update,
+)
 ```
 
 ### Core Objects
 
 - `Table` represents a real table or a subquery.
+- `Column` is the reusable column object used by `Table` when you want to
+  predeclare columns.
 - `select` creates a `SELECT` builder.
 - `insert` creates an `INSERT` builder.
 - `update` creates an `UPDATE` builder.
 - `delete` creates a `DELETE` builder.
 - `func` is a dynamic SQL function registry.
+- `text_op` builds a condition with a raw SQL operator such as `@>`.
 - `Alias` represents a reusable SQL alias for aggregate expressions and
   `HAVING` conditions.
 
@@ -214,6 +252,26 @@ users = Table("users", alias="u")
 `Table` can also wrap a subquery. In practice, you usually pass a query
 builder directly to `from_()` or `join()`, and the library wraps it for you.
 
+If you want explicit, hint-friendly columns on a table instance, pass them
+when you create it:
+
+```python
+from sql_fusion import Column, Table, select
+
+
+users = Table(
+    "users",
+    Column("id"),
+    Column("name"),
+)
+
+
+query = select(users.id, users.name).from_(users)
+```
+
+This style keeps the column list declared in one place and is verified at
+runtime when you access `users.id` / `users.name`.
+
 ### Conditions
 
 Columns support the usual comparison operators:
@@ -231,6 +289,10 @@ They also support SQL helpers:
 - `.ilike(pattern)`
 - `.in_(values)`
 - `.not_in(values)`
+- `text(column, operator, value)` for backend-specific operators such as
+  PostgreSQL array containment (`@>`).
+
+Use `|` for SQL `OR`. Python's `or` cannot be overloaded for SQL expressions.
 
 Conditions can be combined with:
 
@@ -252,6 +314,19 @@ query = (
 )
 ```
 
+For PostgreSQL-style array containment, `text()` lets you pass the operator
+symbol directly:
+
+```python
+users = Table("users", Column("name"), Column("tags"))
+
+query = (
+    select(users.name)
+    .from_(users)
+    .where(users.name == "bob" or text_op(users.tags, "@>", ["coffee"]))
+)
+```
+
 ### Join Example
 
 ```python
@@ -578,3 +653,31 @@ The library also exposes a few built-in compile-time helpers:
 - query builders are chainable
 - repeated calls to many methods merge rather than overwrite
 - backend support still depends on the database you execute against
+
+## Feature Comparison
+
+
+| Project | Focus | SQL coverage | SQL injection protected | Automatic alias management | Advanced features | Dialect/output model | Takeaway |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Py-QueryBuilder | Template-driven filter rendering | No direct CRUD builder; it renders a `WHERE` fragment into a Jinja template | Yes, via JinjaSQL qmark placeholders and a separate params list | No, subquery and join aliases are template-defined rather than auto-managed by the builder | Nested rule groups, operator mapping, field pruning | Jinja2 + JinjaSQL, SQL formatting | Best for UI-driven search forms, not for composing full statements |
+| simple-query-builder-python | Small mutable CRUD helper | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Mostly yes, because execution uses `?` placeholders and a params tuple; `get_sql(with_values=True)` can inline values for display | No, subquery and join aliases are supplied manually in the input data | `JOIN`, `GROUP BY`, `HAVING`, `UNION`, `EXCEPT`, `INTERSECT`, `LIMIT`, `OFFSET` | SQLite-first, raw SQL string builder | Simple and approachable, but the SQL surface is modest |
+| sqlquerybuilder | Django-ORM-style queryset wrapper | Basic read/write queries | No, it renders a ready SQL string with values embedded into the query text | No, subquery and join aliases are handled manually in query strings | Filters and excludes, joins, grouping, ordering, `extra()`, slicing, `with_nolock()` | SQLite-oriented, with SQL Server pagination branches in code | Convenient for ORM-like chaining, but not aimed at deep SQL composition |
+| python-sql | Rich Pythonic SQL builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Yes, it keeps placeholders separate from args and can switch param styles via flavor | Partial, it can auto-alias tables and some subqueries, while join aliases are still often explicit | `JOIN`, subqueries, CTEs, `DISTINCT ON`, windows, `RETURNING`, `MERGE`, `UNION` / `INTERSECT` / `EXCEPT` | Dialect/flavor system with multiple param styles | Very broad SQL coverage and strong backend flexibility |
+| PyPika | Mature fluent query builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | No by default, it renders literal SQL strings with values injected into the output | Partial, it auto-aliases some subqueries and duplicate joins, but most table and join aliases are explicit | `JOIN`, subqueries, CTEs, set operations, analytics/window helpers, DDL support | Dialect-aware with vendor-specific extensions | One of the broadest and most extensible builders in the set |
+| SQLFactory | General-purpose SQL builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Yes, it emits placeholders and keeps args separately | No, subquery and join aliases are mostly explicit and part of the statement shape | `JOIN`, subselects, CTEs, window functions, set operations, `INSERT ... SELECT`, MySQL-style duplicate-key handling | MySQL / SQLite / PostgreSQL / Oracle / custom dialects, async execution helpers | Full-featured and explicit, with a heavier API than lightweight builders |
+| SQL Fusion | Lightweight chainable builder | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Yes, it returns `(sql, params)` and leaves binding to the caller | Yes, it auto-assigns stable table aliases and reuses them for subqueries and joins | `JOIN` variants including `CROSS`, `SEMI`, `ANTI`, subqueries, recursive CTEs, `ROLLUP`, `CUBE`, `GROUPING SETS`, functions, comments, `EXPLAIN` / `ANALYZE`, `DELETE RETURNING` | Backend-agnostic, `compile_expression()` hook for rewrites | Best when you want a compact, composable builder with post-processing hooks and no execution layer |
+
+## Syntax Comparison
+
+The examples below are representative shapes, not copy-paste snippets for every library. Where a library exposes a `Table`
+object, the snippet uses it.
+
+| Project | Typical syntax shape |
+| --- | --- |
+| SQL Fusion | `users = Table("users"); orders = Table("orders"); select(users.id, users.name).from_(users).join(orders, users.id == orders.user_id).where(users.active == True).compile()` |
+| PyPika | `users = Table("users"); orders = Table("orders"); Query.from_(users).join(orders).on(users.id == orders.user_id).select(users.id, users.name).where(users.active == True).get_sql()` |
+| python-sql | `user = Table("users"); tuple(user.select(user.name, where=user.active == True))` |
+| SQLFactory | `users = Table("users"); orders = Table("orders"); Select(users.id, users.name, table=users, join=[Join(orders, Eq("users.id", "orders.user_id"))]).where(Eq("users.active", True))` |
+| simple-query-builder-python | `qb.select("users").where([["active", "=", True]]).join("orders", on=[["users.id", "=", "orders.user_id"]]).all()` |
+| sqlquerybuilder | `Queryset("users").filter(active=True).join("orders", on="users.id=orders.user_id")` |
+| Py-QueryBuilder | `QueryBuilder("app.users", filters).render("query.sql", query)` |

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

@@ -1,14 +1,21 @@
 [project]
 name = "sql_fusion"
-version = "1.0.0"
-description = "Add your description here"
+version = "1.1.0"
+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"
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/Mastermind-U/sql_fusion"
+Documentation = "https://github.com/Mastermind-U/sql_fusion/blob/main/README.md"
+Repository = "https://github.com/Mastermind-U/sql_fusion.git"
+Source = "https://github.com/Mastermind-U/sql_fusion"
+Issues = "https://github.com/Mastermind-U/sql_fusion/issues"
+
 [project.scripts]
-sql_fuser = "sql_fuser:main"
+sql_fusion = "sql_fusion:main"
 
 [build-system]
 requires = ["uv_build>=0.11.1,<0.12.0"]
@@ -125,6 +132,7 @@ ignore-variadic-names = true
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*.py" = ["S101", "PLR2004"]
+"examples/*.py" = ["S101", "T201"]
 
 [tool.ruff.lint.mccabe]
 max-complexity = 15

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

@@ -1,4 +1,4 @@
-from .composite_table import Alias, Table, func
+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
@@ -6,10 +6,12 @@ from .query.update import update
 
 __all__ = [
     "Alias",
+    "Column",
     "Table",
     "delete",
     "func",
     "insert",
     "select",
+    "text_op",
     "update",
 ]

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

@@ -1,3 +1,4 @@
+from collections.abc import Iterable
 from copy import copy
 from typing import Any, Callable, Self
 
@@ -13,12 +14,14 @@ from sql_fusion.operators import (
     LikeOperator,
     NotEqualOperator,
     NotInOperator,
+    TextOperator,
 )
 
 CompileExpression = Callable[
     [str, tuple[Any, ...]],
     tuple[str, tuple[Any, ...]],
 ]
+OperatorFactory = Callable[[str], AbstractOperator]
 
 
 class AliasRegistry:
@@ -303,7 +306,7 @@ class AbstractQuery:
 class ComparableExpression:
     def _cond(
         self,
-        operator: type[AbstractOperator],
+        operator: type[AbstractOperator] | OperatorFactory,
         other: object,
     ) -> Condition:
         return Condition(column=self, operator=operator, value=other)
@@ -412,7 +415,9 @@ class Condition:
     def __init__(  # noqa: PLR0913
         self,
         column: ComparableExpression | FunctionCall | None = None,
-        operator: type[AbstractOperator] | None = None,
+        operator: (
+            type[AbstractOperator] | AbstractOperator | OperatorFactory | None
+        ) = None,
         value: object | None = None,
         is_and: bool = True,
         left: Condition | None = None,
@@ -420,7 +425,9 @@ class Condition:
         negated: bool = False,
     ) -> None:
         self.column: ComparableExpression | FunctionCall | None = column
-        self.operator: type[AbstractOperator] | None = operator
+        self.operator: (
+            type[AbstractOperator] | AbstractOperator | OperatorFactory | None
+        ) = operator
         self.value: object | None = value
         self.is_and: bool = is_and
         self.left: Condition | None = left
@@ -436,6 +443,15 @@ class Condition:
             return value.to_sql(alias_registry)
         return value.get_ref(alias_registry), tuple()
 
+    @staticmethod
+    def _resolve_operator(
+        operator: type[AbstractOperator] | AbstractOperator | OperatorFactory,
+        col_ref: str,
+    ) -> AbstractOperator:
+        if isinstance(operator, AbstractOperator):
+            return operator
+        return operator(col_ref)
+
     def __and__(self, other: Condition) -> Condition:
         return Condition(is_and=True, left=self, right=other)
 
@@ -475,28 +491,30 @@ class Condition:
             self.column,
             alias_registry,
         )
-        operator_class = self.operator
-        if operator_class is None:
+        operator_spec = self.operator
+        if operator_spec is None:
             return apply_negation(col_ref, col_params)
 
+        operator = self._resolve_operator(operator_spec, col_ref)
+
         if isinstance(self.value, (ComparableExpression, FunctionCall)):
             value_sql, value_params = self._render_expression(
                 self.value,
                 alias_registry,
             )
-            sql, op_params = operator_class(col_ref).to_sql_ref(value_sql)
+            sql, op_params = operator.to_sql_ref(value_sql)
             return apply_negation(sql, col_params + value_params + op_params)
 
         if isinstance(self.value, AbstractQuery):
             subquery_sql, subquery_params = self.value.build_query(
                 alias_registry,
             )
+            sql, op_params = operator.to_sql_ref(subquery_sql)
             return apply_negation(
-                f"{col_ref} {operator_class.sql_symbol} ({subquery_sql})",
-                col_params + subquery_params,
+                sql, col_params + subquery_params + op_params
             )
 
-        sql, op_params = operator_class(col_ref).to_sql(self.value)
+        sql, op_params = operator.to_sql(self.value)
         return apply_negation(sql, col_params + op_params)
 
 
@@ -624,6 +642,18 @@ class FunctionRegistry:
 func = FunctionRegistry()
 
 
+def text_op(
+    column: ComparableExpression | FunctionCall,
+    operator: str,
+    value: object,
+) -> Condition:
+    return Condition(
+        column=column,
+        operator=lambda col_ref: TextOperator(col_ref, operator),
+        value=value,
+    )
+
+
 class Column(ComparableExpression):
     def __init__(self, name: str) -> None:
         self.name: str = name
@@ -652,15 +682,22 @@ class Table:
     def __init__(
         self,
         name: str | AbstractQuery,
+        *columns: Column,
     ) -> None:
         self._table_name: str = ""
         self._subquery: AbstractQuery | None = None
+        self.columns: dict[str, Column] = {}
 
         if isinstance(name, AbstractQuery):
             self._subquery = name
         else:
             self._table_name = name
 
+        if columns:
+            for col in columns:
+                col._attach_table(self)  # pyright: ignore[reportPrivateUsage]
+                self.columns[col.name] = col
+
     def get_name(self) -> str:
         if self._subquery is not None:
             raise ValueError("Table is a subquery, no name available")
@@ -678,12 +715,22 @@ class Table:
 
         return f'"{self._table_name}"', tuple()
 
+    def __dir__(self) -> Iterable[str]:
+        default_dir = super().__dir__()
+        cols = list(self.columns.keys())
+        cols.extend(default_dir)
+        return cols
+
     def __getattr__(self, column_name: str) -> Column:
         if column_name.startswith("_"):
             raise AttributeError(
                 f"'{type(self).__name__}' "
                 f"object has no attribute '{column_name}'",
             )
+
+        if self.columns:
+            return self.columns[column_name]
+
         column = Column(column_name)
         column._attach_table(self)  # pyright: ignore[reportPrivateUsage]
         return column

{sql_fusion-1.0.0 → sql_fusion-1.1.0}/src/sql_fusion/operators.py

@@ -1,6 +1,4 @@
-from typing import Any, Callable
-
-OPERATORS: dict[str, type[AbstractOperator]] = {}
+from typing import Any
 
 
 class AbstractOperator:
@@ -16,18 +14,6 @@ class AbstractOperator:
         raise NotImplementedError()
 
 
-def register_operator(
-    symbol: str,
-) -> Callable[[type[AbstractOperator]], type[AbstractOperator]]:
-    def decorator(cls: type[AbstractOperator]) -> type[AbstractOperator]:
-        OPERATORS[symbol] = cls
-        cls.sql_symbol = symbol
-        return cls
-
-    return decorator
-
-
-@register_operator("=")
 class EqualOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} = ?", (value,)
@@ -36,7 +22,6 @@ class EqualOperator(AbstractOperator):
         return f"{self._col_ref} = {value_ref}", tuple()
 
 
-@register_operator("!=")
 class NotEqualOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} != ?", (value,)
@@ -45,7 +30,6 @@ class NotEqualOperator(AbstractOperator):
         return f"{self._col_ref} != {value_ref}", tuple()
 
 
-@register_operator("<")
 class LessThanOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} < ?", (value,)
@@ -54,7 +38,6 @@ class LessThanOperator(AbstractOperator):
         return f"{self._col_ref} < {value_ref}", tuple()
 
 
-@register_operator(">")
 class GreaterThanOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} > ?", (value,)
@@ -63,7 +46,6 @@ class GreaterThanOperator(AbstractOperator):
         return f"{self._col_ref} > {value_ref}", tuple()
 
 
-@register_operator("<=")
 class LessThanOrEqualOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} <= ?", (value,)
@@ -72,7 +54,6 @@ class LessThanOrEqualOperator(AbstractOperator):
         return f"{self._col_ref} <= {value_ref}", tuple()
 
 
-@register_operator(">=")
 class GreaterThanOrEqualOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} >= ?", (value,)
@@ -81,7 +62,6 @@ class GreaterThanOrEqualOperator(AbstractOperator):
         return f"{self._col_ref} >= {value_ref}", tuple()
 
 
-@register_operator("LIKE")
 class LikeOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} LIKE ?", (value,)
@@ -90,7 +70,6 @@ class LikeOperator(AbstractOperator):
         return f"{self._col_ref} LIKE {value_ref}", tuple()
 
 
-@register_operator("ILIKE")
 class IlikeOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} ILIKE ?", (value,)
@@ -99,7 +78,6 @@ class IlikeOperator(AbstractOperator):
         return f"{self._col_ref} ILIKE {value_ref}", tuple()
 
 
-@register_operator("IN")
 class InOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         placeholders: str = ", ".join("?" * len(value))
@@ -109,7 +87,6 @@ class InOperator(AbstractOperator):
         return f"{self._col_ref} IN ({value_ref})", tuple()
 
 
-@register_operator("NOT IN")
 class NotInOperator(AbstractOperator):
     def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
         placeholders: str = ", ".join("?" * len(value))
@@ -117,3 +94,15 @@ class NotInOperator(AbstractOperator):
 
     def to_sql_ref(self, value_ref: str) -> tuple[str, tuple[Any, ...]]:
         return f"{self._col_ref} NOT IN ({value_ref})", tuple()
+
+
+class TextOperator(AbstractOperator):
+    def __init__(self, col_ref: str, sql_symbol: str) -> None:
+        super().__init__(col_ref)
+        self.sql_symbol: str = sql_symbol
+
+    def to_sql(self, value: Any) -> tuple[str, tuple[Any, ...]]:
+        return f"{self._col_ref} {self.sql_symbol} ?", (value,)
+
+    def to_sql_ref(self, value_ref: str) -> tuple[str, tuple[Any, ...]]:
+        return f"{self._col_ref} {self.sql_symbol} {value_ref}", tuple()