buildaquery 0.1.0__py3-none-any.whl

buildaquery/abstract_syntax_tree/README.md

@@ -0,0 +1,54 @@
+# Abstract Syntax Tree (AST)
+
+The `abstract_syntax_tree` module defines the data structures used to represent SQL queries as an Abstract Syntax Tree. This representation is agnostic of any specific SQL dialect and serves as the intermediate format that the query builder constructs and the compiler translates into SQL.
+
+## Core Concepts
+
+The AST is built using a hierarchy of nodes, all inheriting from the base `ASTNode` class.
+
+### Node Categories
+
+-   **`ExpressionNode`**: Represents values, column references, and operations (e.g., `LiteralNode`, `ColumnNode`, `BinaryOperationNode`, `FunctionCallNode`).
+-   **`StatementNode`**: Represents complete SQL statements. Currently, `SelectStatementNode` is the primary implementation.
+-   **`FromClauseNode`**: Represents entities that can appear in a `FROM` clause, such as `TableNode` or `JoinClauseNode`.
+
+## Key Components
+
+-   **`SelectStatementNode`**: The central node for `SELECT` queries. It encapsulates the select list, `FROM` table/joins, `WHERE` conditions, `GROUP BY`, `HAVING`, `ORDER BY`, and pagination (`LIMIT`, `OFFSET`, `TOP`).
+-   **`TopClauseNode`**: A specialized node for limiting results, particularly for dialects that support the `TOP` syntax. It is mutually exclusive with standard `LIMIT`/`OFFSET`.
+-   **`JoinClauseNode`**: Represents various types of table joins (INNER, LEFT, etc.) with associated join conditions.
+-   **Operations**: Support for both binary (e.g., `+`, `-`, `AND`, `OR`) and unary (e.g., `NOT`, `-`) operations.
+
+## Usage
+
+Nodes are typically instantiated and composed to build a tree representing a query. For example:
+
+```python
+from buildaquery.abstract_syntax_tree.models import SelectStatementNode, ColumnNode, TableNode
+
+# SELECT * FROM users
+query = SelectStatementNode(
+    select_list=[ColumnNode(name="*")],
+    from_table=TableNode(name="users")
+)
+```
+
+This tree can then be processed by visitors (see the `traversal` module) for compilation or analysis.
+
+## TODOs
+
+To make the AST more robust and capable of representing the full scope of the SQL language, the following enhancements are planned:
+
+- **DML Support**:
+    - [x] Implement `InsertStatementNode` and `UpdateStatementNode`.
+    - [x] Implement `DeleteStatementNode`.
+- **Advanced Query Features**:
+    - [x] **CTEs**: Add `WithClauseNode` for common table expressions.
+    - [x] **Set Operations**: Implement `UnionNode`, `IntersectNode`, and `ExceptNode`.
+    - [x] **DISTINCT**: Add support for `SELECT DISTINCT`.
+- **Richer Expression Logic**:
+    - **Specialized Expressions**: Add [x] `CaseExpressionNode`, [x] `InNode`, and [x] `BetweenNode`.
+    - [x] **Subqueries**: Enable `SelectStatementNode` to be used within expressions.
+    - [x] **Window Functions**: Support `OVER` clauses and partitioning.
+    - [x] **Schema & Namespacing**: Update `TableNode` and `ColumnNode` to support qualified names (e.g., `schema.table`) and add a `CastNode` for type casting.
+- **DDL Support**: [x] Add nodes for `CREATE`, `ALTER`, and `DROP` statements for schema management.

buildaquery/abstract_syntax_tree/__init__.py

@@ -0,0 +1 @@
+from .models import *

buildaquery/abstract_syntax_tree/models.py

@@ -0,0 +1,285 @@
+from abc import ABC
+from dataclasses import dataclass
+from typing import Any
+
+# ==================================================
+# Base classes
+# ==================================================
+@dataclass
+class ASTNode(ABC):
+    """
+    A generic AST node. All specific AST node types will inherit from this base class.
+    """
+    pass
+
+@dataclass
+class ExpressionNode(ASTNode):
+    """
+    A base class for all expression nodes in the AST.
+    """
+    pass
+
+# ==================================================
+# Specific expression nodes
+# ==================================================
+
+@dataclass
+class LiteralNode(ExpressionNode):
+    """
+    Represents a literal value in the AST, such as a number or string.
+    """
+    value: Any
+
+@dataclass
+class ColumnNode(ExpressionNode):
+    """
+    Represents a column reference in the AST.
+    """
+    name: str
+    table: str | None = None
+
+@dataclass
+class BinaryOperationNode(ExpressionNode):
+    """
+    Represents a binary operation in the AST, such as addition, subtraction, etc.
+    """
+    left: ExpressionNode
+    operator: str
+    right: ExpressionNode
+
+# ==================================================
+# Statement nodes
+# ==================================================
+
+@dataclass
+class StatementNode(ASTNode):
+    """
+    A base class for all statement nodes in the AST.
+    """
+    pass
+
+@dataclass
+class FromClauseNode(ASTNode):
+    """
+    Represents a FROM clause in the AST, anything can appears here, including subqueries, joins, etc.
+    """
+    pass
+
+@dataclass
+class SubqueryNode(ExpressionNode, FromClauseNode):
+    """
+    Represents a subquery that can be used in an expression or a FROM clause.
+    """
+    statement: 'SelectStatementNode'
+    alias: str | None = None
+
+@dataclass
+class JoinClauseNode(FromClauseNode):
+    """
+    Represents a JOIN clause in the AST.
+    """
+    left: FromClauseNode
+    right: FromClauseNode
+    on_condition: ExpressionNode
+    join_type: str
+
+@dataclass
+class OrderByClauseNode(ASTNode):
+    """
+    Represents a single item in the ORDER BY clause in the AST.
+    """
+    expression: ExpressionNode
+    direction: str = "ASC" # default to ascending order
+
+@dataclass
+class TopClauseNode(ASTNode):
+    """
+    Represents a TOP clause in the AST.
+    """
+    count: int
+    # Optional: Column to order by for TOP clause, if not already specified in ORDER BY
+    on_expression: ExpressionNode | None = None
+    direction: str = "DESC" # default to descending order for TOP
+
+@dataclass
+class TableNode(FromClauseNode):
+    """
+    Represents a table reference in the AST.
+    """
+    name: str
+    schema: str | None = None
+    alias: str | None = None
+
+@dataclass
+class AliasNode(ExpressionNode):
+    """Represents an aliased expression (e.g., 'column AS new_name')."""
+    expression: ExpressionNode
+    name: str
+
+@dataclass
+class OverClauseNode(ASTNode):
+    """Represents an OVER clause for window functions."""
+    partition_by: list[ExpressionNode] | None = None
+    order_by: list[OrderByClauseNode] | None = None
+
+@dataclass
+class CastNode(ExpressionNode):
+    """Represents a type cast (e.g., 'CAST(column AS type)' or 'column::type')."""
+    expression: ExpressionNode
+    data_type: str
+
+@dataclass
+class FunctionCallNode(ExpressionNode):
+    """Represents a function call (e.g., COUNT(*), MAX(price))."""
+    name: str
+    args: list[ExpressionNode]
+    over: OverClauseNode | None = None # optional OVER clause for window functions
+
+@dataclass
+class UnaryOperationNode(ExpressionNode):
+    """Represents a unary operation (e.g., NOT, -)."""
+    operator: str
+    operand: ExpressionNode
+
+@dataclass
+class InNode(ExpressionNode):
+    """Represents an IN expression (e.g., 'column IN (1, 2, 3)')."""
+    expression: ExpressionNode
+    values: list[ExpressionNode]
+    negated: bool = False
+
+@dataclass
+class WhenThenNode(ASTNode):
+    """Represents a WHEN ... THEN ... clause in a CASE expression."""
+    condition: ExpressionNode
+    result: ExpressionNode
+
+@dataclass
+class CaseExpressionNode(ExpressionNode):
+    """Represents a CASE expression (e.g., 'CASE WHEN cond THEN res ELSE default END')."""
+    cases: list[WhenThenNode]
+    else_result: ExpressionNode | None = None
+
+@dataclass
+class BetweenNode(ExpressionNode):
+    """Represents a BETWEEN expression (e.g., 'column BETWEEN 1 AND 10')."""
+    expression: ExpressionNode
+    low: ExpressionNode
+    high: ExpressionNode
+    negated: bool = False
+
+@dataclass
+class StarNode(ExpressionNode):
+    """Represents the '*' in 'SELECT *'."""
+    pass
+
+@dataclass
+class WhereClauseNode(ASTNode):
+    """A wrapper for the expression in a WHERE clause."""
+    condition: ExpressionNode
+
+@dataclass
+class GroupByClauseNode(ASTNode):
+    """A wrapper for the list of expressions in a GROUP BY clause."""
+    expressions: list[ExpressionNode]
+
+@dataclass
+class HavingClauseNode(ASTNode):
+    """A wrapper for the expression in a HAVING clause."""
+    condition: ExpressionNode
+
+@dataclass
+class CTENode(ASTNode):
+    """Represents a Common Table Expression (WITH clause)."""
+    name: str
+    subquery: 'SelectStatementNode'
+
+@dataclass
+class SelectStatementNode(StatementNode):
+    """
+    Represents a SELECT statement in the AST.
+    """
+    select_list: list[ExpressionNode] # list of expressions to select (eg: columns, functions, etc.)
+    distinct: bool = False # toggle between SELECT ALL and SELECT DISTINCT
+    ctes: list[CTENode] | None = None # optional list of Common Table Expressions
+    from_table: FromClauseNode | None = None # the table to select from, optional for edge cases
+    where_clause: WhereClauseNode | None = None # optional where clause for filtering results
+    group_by: GroupByClauseNode | None = None # optional group by clause for aggregation
+    having_clause: HavingClauseNode | None = None # optional having clause for filtering groups in aggregation
+    order_by_clause: list[OrderByClauseNode] | None = None # optional list of order by clauses for sorting results
+    top_clause: TopClauseNode | None = None # optional top clause, mutually exclusive with limit and offset
+    limit: int | None = None # optional limit for number of results to return
+    offset: int | None = None # optional offset for skipping results
+
+@dataclass
+class DeleteStatementNode(StatementNode):
+    """
+    Represents a DELETE statement in the AST.
+    """
+    table: TableNode
+    where_clause: WhereClauseNode | None = None
+
+@dataclass
+class ColumnDefinitionNode(ASTNode):
+    """Represents a column definition in a CREATE TABLE statement."""
+    name: str
+    data_type: str
+    primary_key: bool = False
+    not_null: bool = False
+    default: ExpressionNode | None = None
+
+@dataclass
+class CreateStatementNode(StatementNode):
+    """Represents a CREATE TABLE statement."""
+    table: TableNode
+    columns: list[ColumnDefinitionNode]
+    if_not_exists: bool = False
+
+@dataclass
+class DropStatementNode(StatementNode):
+    """Represents a DROP TABLE statement."""
+    table: TableNode
+    if_exists: bool = False
+    cascade: bool = False
+
+@dataclass
+class InsertStatementNode(StatementNode):
+    """
+    Represents an INSERT statement in the AST.
+    """
+    table: TableNode
+    values: list[ExpressionNode]
+    columns: list[ColumnNode] | None = None
+
+@dataclass
+class UpdateStatementNode(StatementNode):
+    """
+    Represents an UPDATE statement in the AST.
+    """
+    table: TableNode
+    set_clauses: dict[str, ExpressionNode] # Map column names to new values/expressions
+    where_clause: WhereClauseNode | None = None
+
+@dataclass
+class SetOperationNode(StatementNode):
+    """
+    Base class for set operations like UNION, INTERSECT, EXCEPT.
+    """
+    left: StatementNode
+    right: StatementNode
+    all: bool = False
+
+@dataclass
+class UnionNode(SetOperationNode):
+    """Represents a UNION operation."""
+    pass
+
+@dataclass
+class IntersectNode(SetOperationNode):
+    """Represents an INTERSECT operation."""
+    pass
+
+@dataclass
+class ExceptNode(SetOperationNode):
+    """Represents an EXCEPT operation."""
+    pass

buildaquery/compiler/README.md

@@ -0,0 +1,48 @@
+# Compiler
+
+The `compiler` module is responsible for translating the dialect-agnostic Abstract Syntax Tree (AST) into specific SQL dialects. 
+
+## Core Concepts
+
+### `CompiledQuery` Dataclass
+Every compiler returns a `CompiledQuery` object instead of a raw string. This ensures that queries are handled safely and consistently.
+
+- **`sql` (str)**: The SQL query string containing placeholders (e.g., `%s` for PostgreSQL).
+- **`params` (list[Any])**: A list of values corresponding to the placeholders in the SQL string.
+
+### Parametrization
+To prevent SQL injection, the compilers are designed to automatically parametrize all literal values. When a `LiteralNode` is encountered, the compiler:
+1. Appends a placeholder to the SQL string.
+2. Appends the literal value to the `params` list.
+
+## Implementations
+
+### PostgreSQL (`PostgresCompiler`)
+The initial implementation supports PostgreSQL.
+
+#### Key Features:
+- **DISTINCT Support**: Handles `SELECT DISTINCT` queries.
+- **DML Support**: Supports `INSERT`, `UPDATE`, and `DELETE` operations.
+- **Set Operations**: Support for `UNION`, `INTERSECT`, and `EXCEPT` (including `ALL`).
+- **CTEs**: Support for `WITH` clauses.
+- **Specialized Expressions**: Support for `IN`, `BETWEEN`, and `CASE`.
+- **Subqueries**: Support for subqueries in `FROM` and `WHERE` clauses.
+- **Window Functions**: Support for `OVER` clauses, `PARTITION BY`, and `ORDER BY`.
+- **DDL Support**: Support for `CREATE TABLE` and `DROP TABLE`.
+- **Qualified Names**: Supports `schema.table` and `table.column` naming conventions.
+- **Type Casting**: Supports `CAST(expression AS type)`.
+- **Clause Ordering**: Ensures `SELECT`, `FROM`, `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`, and `LIMIT` are placed in the correct sequence.
+- **TOP Translation**: Automatically translates `TopClauseNode` into PostgreSQL-compliant `LIMIT` and `ORDER BY` logic.
+- **Mutual Exclusivity Enforcement**: Raises a `ValueError` if a query attempts to use both `TOP` and standard `LIMIT/OFFSET`.
+
+## Usage Example
+
+```python
+from buildaquery.compiler.postgres.postgres_compiler import PostgresCompiler
+
+compiler = PostgresCompiler()
+compiled = compiler.compile(ast_root)
+
+print(compiled.sql)    # "SELECT * FROM users WHERE id = %s"
+print(compiled.params) # [123]
+```

buildaquery/compiler/postgres/README.md

@@ -0,0 +1,25 @@
+# PostgreSQL Compiler
+
+This sub-module provides the concrete implementation of the SQL compiler for PostgreSQL.
+
+## Features
+
+- **Standard DML Support**: Compiles `SELECT`, `INSERT`, `UPDATE`, and `DELETE` statements.
+- **Set Operations**: Supports `UNION`, `INTERSECT`, and `EXCEPT` (and their `ALL` variants).
+- **CTEs**: Supports Common Table Expressions (`WITH` clause).
+- **Specialized Expressions**: Supports `IN`, `BETWEEN`, and `CASE` operators.
+- **Subqueries**: Handles subqueries in `FROM` and `WHERE` clauses.
+- **Window Functions**: Supports window functions with `OVER`, `PARTITION BY`, and `ORDER BY`.
+- **DDL Support**: Handles `CREATE TABLE` and `DROP TABLE` statements.
+- **DISTINCT**: Supports `SELECT DISTINCT`.
+- **Qualified Names**: Handles `schema.table` and `table.column` identifiers.
+- **Type Casting**: Supports `CAST(expression AS type)`.
+- **Filtering**: Translates `WhereClauseNode` and complex binary/unary operations.
+- **Parametrization**: Automatically uses `%s` placeholders for all literal values to ensure security.
+- **Dialect Specifics**: 
+    - Translates `TopClauseNode` into a combination of `LIMIT` and `ORDER BY`.
+    - Handles PostgreSQL-specific operator precedence through grouping.
+
+## Implementation Details
+
+The compiler is implemented as a `Visitor` that recursively traverses the AST. For expression nodes, it generally follows a post-order traversal to build the SQL string from the bottom up.