sql_querystring_builder 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

sql_querystring_builder/__init__.py

@@ -1,9 +1,11 @@
 from .clauses import (
     CrossJoin,
+    Delete,
     From,
     FullJoin,
     IncorrectUpdateException,
     InnerJoin,
+    Insert,
     LeftJoin,
     OrderBy,
     RightJoin,
@@ -11,6 +13,7 @@ from .clauses import (
     Update,
     Where,
 )
+from .conditions import Condition
 from .exceptions import SqlQueryBuilderError
 from .query_builder import IncompatibleClausesException, QueryBuilder, UnavailablePlaceException
 from .tables import (
@@ -26,3 +29,4 @@ from .tables import (
     TableException,
     TempTable,
 )
+from .values import NStr, Raw, Str

sql_querystring_builder/clauses.py

@@ -1,16 +1,23 @@
 from __future__ import annotations
 
+from collections.abc import Mapping, Sequence
+
 from .abstract_clause import Clause
+from .conditions import Comparable, Condition, Junction, check_operand, render_operand
 from .exceptions import SqlQueryBuilderError
 from .tables import Aliasable, Field, Fields, Table, TempTable
+from .values import render_value
 
 
 class IncorrectUpdateException(SqlQueryBuilderError):
     pass
 
 
-# TODO  Add INSERT
-# TODO  Add concept of condition
+def _insert_value(value: object) -> object:
+    # VALUES cannot read columns: unlike in a condition, a field or expression is no value here.
+    if isinstance(value, Comparable):
+        raise TypeError(f"Unsupported value type: {type(value).__name__}.")
+    return check_operand(value)
 
 
 def _row_count(keyword: str, value: int, minimum: int) -> int:
@@ -81,8 +88,10 @@ class From(Clause):
 
 
 class Where(Clause):
-    def __init__(self, *conditions: str | Aliasable) -> None:
-        self.conditions: tuple[str | Aliasable, ...] = conditions
+    """`WHERE` and its parts, joined by spaces: conditions, fields, and strings written as raw SQL."""
+
+    def __init__(self, *conditions: str | Aliasable | Condition) -> None:
+        self.conditions: tuple[str | Aliasable | Condition, ...] = conditions
 
     @property
     def place(self) -> int:
@@ -91,7 +100,12 @@ class Where(Clause):
     def build(self) -> str:
         ret: list[str] = ["WHERE"]
         for condition in self.conditions:
-            ret.append(condition.build() if isinstance(condition, Aliasable) else condition)
+            if isinstance(condition, Condition):
+                sql: str = condition.build()
+                # Next to raw strings, an AND or OR condition keeps its meaning only in parentheses.
+                ret.append(f"({sql})" if isinstance(condition, Junction) and len(self.conditions) > 1 else sql)
+            else:
+                ret.append(condition.build() if isinstance(condition, Aliasable) else condition)
         return " ".join(ret)
 
     def __repr__(self) -> str:
@@ -99,14 +113,31 @@ class Where(Clause):
 
 
 class Join(Clause):
-    """A join on `on_left = on_right`; each subclass only sets its `keyword`."""
+    """A join on `on_left = on_right`, or on any condition given as `on`; each subclass only sets its `keyword`."""
 
     keyword: str
 
-    def __init__(self, table: Table, on_left: Field, on_right: Field | Table) -> None:
+    def __init__(
+        self,
+        table: Table,
+        on_left: Field | None = None,
+        on_right: Field | Table | None = None,
+        *,
+        on: Condition | None = None,
+    ) -> None:
+        if on is None:
+            if on_left is None or on_right is None:
+                raise TypeError(f"{self.__class__.__name__} needs on_left and on_right, or on.")
+            on_right = on_right if isinstance(on_right, Aliasable) else on_right.fields[on_left.name]
+            on = on_left.eq(on_right)
+        elif on_left is not None or on_right is not None:
+            raise TypeError(f"{self.__class__.__name__} takes on_left and on_right, or on, not both.")
+        elif not isinstance(on, Condition):
+            raise TypeError(f"on must be a Condition, got {type(on).__name__}.")
         self.table: Table = table
-        self.on_left: Field = on_left
-        self.on_right: Field = on_right if isinstance(on_right, Aliasable) else on_right.fields[on_left.name]
+        self.on_left: Field | None = on_left
+        self.on_right: Field | None = on_right
+        self.on: Condition = on
 
     @property
     def place(self) -> int:
@@ -117,9 +148,11 @@ class Join(Clause):
         return False
 
     def build(self) -> str:
-        return f"{self.keyword} {self.table.build(use_name=True)} on {self.on_left.build()} = {self.on_right.build()}"
+        return f"{self.keyword} {self.table.build(use_name=True)} on {self.on.build()}"
 
     def __repr__(self) -> str:
+        if self.on_left is None:
+            return f"{self.__class__.__name__}(table={self.table}, on={self.on})"
         return f"{self.__class__.__name__}(table={self.table}, on_left={self.on_left}, on_right={self.on_right})"
 
 
@@ -159,10 +192,16 @@ class CrossJoin(Clause):
 
 
 class Update(Clause):
-    def __init__(self, updates: dict[Field, str]) -> None:
+    """`UPDATE … SET field=value, …`: a plain str value is raw SQL (`"'x'"`), `Str("x")` an escaped string.
+
+    Any other value goes through `values.py`, like a value in a condition: `None` is `NULL`, a field is its
+    qualified name.
+    """
+
+    def __init__(self, updates: Mapping[Field, object]) -> None:
         if not updates:
             raise IncorrectUpdateException("The Update is empty.")
-        self.updates: dict[Field, str] = {}
+        self.updates: dict[Field, object] = {}
         first_table: Table | None = None
         for field, value in updates.items():
             if first_table is None:
@@ -175,7 +214,7 @@ class Update(Clause):
                 raise IncorrectUpdateException(
                     f"Two different tables cannot be updated in the same Update: '{first}' and '{other}'."
                 )
-            self.updates[field] = value
+            self.updates[field] = value if isinstance(value, str) else check_operand(value)
         self.table: Table = field.table
 
     @property
@@ -183,13 +222,104 @@ class Update(Clause):
         return 0
 
     def build(self) -> str:
-        field_strings: list[str] = [f"{field.build()}={value}" for field, value in self.updates.items()]
+        # A plain str stays raw SQL until 1.0 (D4 in ROADMAP.md): turning it into a value would quote it.
+        field_strings: list[str] = [
+            f"{field.build()}={value if isinstance(value, str) else render_operand(value)}"
+            for field, value in self.updates.items()
+        ]
         return f"UPDATE {self.table.build(use_name=False, use_alias=True)}\nSET " + ", ".join(field_strings)
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(updates={self.updates})"
 
 
+class Insert(Clause):
+    """`INSERT INTO table (columns)` and `VALUES (…), (…)`, with the rows added by `values()`.
+
+    The columns are fields of one table, or whole tables, as `Select` takes them. Unlike in `Update`, a plain
+    str is a value here. An Insert stands alone in its query (see `QueryBuilder.build()`).
+    """
+
+    def __init__(self, *columns: Field | Table) -> None:
+        tables: list[Table] = []
+        self.columns: list[Field] = []
+        for column in columns:
+            if isinstance(column, Table):
+                tables.append(column)
+                self.columns.extend(column.fields.as_list())
+            elif isinstance(column, Field):
+                tables.append(column.table)
+                self.columns.append(column)
+            else:
+                raise TypeError(f"Insert takes fields or tables, got {type(column).__name__}.")
+        if not self.columns:
+            raise ValueError("Insert needs at least one column.")
+        for table in tables[1:]:
+            if table.name != tables[0].name:
+                raise ValueError(f"Insert columns must come from one table, got '{tables[0].name}' and '{table.name}'.")
+        names: set[str] = set()
+        for column in self.columns:
+            if column.name in names:
+                raise ValueError(f"Insert column '{column.name}' appears twice.")
+            names.add(column.name)
+        self.table: Table = tables[0]
+        self.rows: list[tuple[object, ...]] = []
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def values(self, *rows: Sequence[object]) -> Insert:
+        """Adds rows, each a tuple or list of values in column order, and returns the Insert."""
+        if len(self.rows) + len(rows) > 1000:
+            raise ValueError(f"An INSERT takes at most 1000 rows, got {len(self.rows) + len(rows)}.")
+        checked: list[tuple[object, ...]] = []
+        expected: str = f"{len(self.columns)} value{'s' if len(self.columns) > 1 else ''}"
+        for number, row in enumerate(rows, start=len(self.rows) + 1):
+            if isinstance(row, (str, bytes)) or not isinstance(row, Sequence):
+                raise TypeError(f"An Insert row must be a tuple or list of values, got {type(row).__name__}.")
+            if len(row) != len(self.columns):
+                raise ValueError(f"Insert row {number} needs {expected}, got {len(row)}.")
+            checked.append(tuple(_insert_value(value) for value in row))
+        self.rows.extend(checked)
+        return self
+
+    def build(self) -> str:
+        if not self.rows:
+            raise ValueError("The Insert has no rows: add them with values().")
+        # T-SQL refuses an alias after INSERT INTO, and qualified column names.
+        columns: str = ", ".join(column.name for column in self.columns)
+        rows: str = ", ".join(f"({', '.join(render_value(value) for value in row)})" for row in self.rows)
+        return f"INSERT INTO {self.table.name} ({columns})\nVALUES {rows}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(columns={self.columns}, rows={len(self.rows)})"
+
+
+class Delete(Clause):
+    """`DELETE` and the table's alias, or its name; T-SQL reads an alias from `From(table)`, as for `Update`.
+
+    A query with a Delete needs a Where unless `where_required=False`: an empty filter would delete every row.
+    """
+
+    def __init__(self, table: Table, *, where_required: bool = True) -> None:
+        if not isinstance(table, Table):
+            raise TypeError(f"Delete takes a Table, got {type(table).__name__}.")
+        self.table: Table = table
+        self.where_required: bool = where_required
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def build(self) -> str:
+        return f"DELETE {self.table.build(use_name=False, use_alias=True)}"
+
+    def __repr__(self) -> str:
+        option: str = "" if self.where_required else ", where_required=False"
+        return f"{self.__class__.__name__}(table={self.table}{option})"
+
+
 class OrderBy(Clause):
     def __init__(self, field: Aliasable, descending: bool = False) -> None:
         self.ordering: list[tuple[Aliasable, bool]] = [(field, descending)]

sql_querystring_builder/conditions.py

@@ -0,0 +1,194 @@
+"""Conditions for WHERE and JOIN ON, made by the methods of fields: `f.eq(1) & g.like("A%")`."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from .values import check_value, render_value
+
+
+class Comparable(ABC):
+    """Base of fields, functions on fields and strings: its methods make the conditions that compare them.
+
+    A compared value is another Comparable, written by its qualified name (`t.f = u.g`), or any value
+    `values.py` can write into SQL. `eq` and `ne` are methods, not `==`: a Field is used as a dict key.
+    """
+
+    @abstractmethod
+    def build(self) -> str: ...
+
+    def eq(self, value: object) -> Condition:
+        """`= value`, or `IS NULL` when value is None."""
+        return IsNull(self) if value is None else Comparison(self, "=", value)
+
+    def ne(self, value: object) -> Condition:
+        """`<> value`, or `IS NOT NULL` when value is None."""
+        return IsNull(self, negated=True) if value is None else Comparison(self, "<>", value)
+
+    def lt(self, value: object) -> Condition:
+        return Comparison(self, "<", value)
+
+    def le(self, value: object) -> Condition:
+        return Comparison(self, "<=", value)
+
+    def gt(self, value: object) -> Condition:
+        return Comparison(self, ">", value)
+
+    def ge(self, value: object) -> Condition:
+        return Comparison(self, ">=", value)
+
+    def like(self, pattern: object) -> Condition:
+        return Comparison(self, "LIKE", pattern)
+
+    def in_(self, values: Iterable[object]) -> Condition:
+        return In(self, values)
+
+    def between(self, low: object, high: object) -> Condition:
+        return Between(self, low, high)
+
+    def is_null(self) -> Condition:
+        return IsNull(self)
+
+    def is_not_null(self) -> Condition:
+        return IsNull(self, negated=True)
+
+
+def render_operand(value: object) -> str:
+    """Writes a Comparable by its qualified name, and any other value through `values.py`."""
+    return value.build() if isinstance(value, Comparable) else render_value(value)
+
+
+def check_operand(value: object) -> object:
+    """Returns `value`, or raises TypeError or ValueError now if it is neither a Comparable nor a SQL value."""
+    if isinstance(value, Condition):  # T-SQL has no boolean values; name the public class, not And or Or
+        raise TypeError("Unsupported value type: Condition.")
+    if not isinstance(value, Comparable):
+        check_value(value)
+    return value
+
+
+class Condition(ABC):
+    """A test for WHERE or JOIN ON, made by the methods of a field, such as `f.eq(1)`.
+
+    Combine conditions with `&`, `|` and `~`, or with `and_()`, `or_()` and `not_()`.
+    """
+
+    # T-SQL binds a predicate (`a = 1`, `NOT (…)`) tighter than AND, and AND tighter than OR.
+    _binding: int = 3
+
+    @abstractmethod
+    def build(self) -> str: ...
+
+    def _build_within(self, binding: int) -> str:
+        """Builds the condition, in parentheses when it binds more loosely than what surrounds it."""
+        return f"({self.build()})" if self._binding < binding else self.build()
+
+    def and_(self, other: Condition) -> Condition:
+        return And(self, _condition("and_", other))
+
+    def or_(self, other: Condition) -> Condition:
+        return Or(self, _condition("or_", other))
+
+    def not_(self) -> Condition:
+        return Not(self)
+
+    def __and__(self, other: object) -> Condition:
+        return self.and_(other) if isinstance(other, Condition) else NotImplemented
+
+    def __or__(self, other: object) -> Condition:
+        return self.or_(other) if isinstance(other, Condition) else NotImplemented
+
+    def __invert__(self) -> Condition:
+        return self.not_()
+
+    def __bool__(self) -> bool:
+        # Python's and, or, not and if all call __bool__: `c1 and c2` would silently keep only c2.
+        raise TypeError(
+            "Conditions are not booleans: combine them with &, | and ~ (or and_(), or_() and not_()), "
+            "not with Python's and, or and not."
+        )
+
+    def __repr__(self) -> str:
+        return f"Condition({self.build()!r})"
+
+
+def _condition(method: str, other: object) -> Condition:
+    if not isinstance(other, Condition):
+        raise TypeError(f"{method}() takes a Condition, got {type(other).__name__}.")
+    return other
+
+
+class Comparison(Condition):
+    """`left <operator> right`, such as `t.f = 5` or `t.f LIKE 'A%'`."""
+
+    def __init__(self, left: Comparable, operator: str, right: object) -> None:
+        self.left: Comparable = left
+        self.operator: str = operator
+        self.right: object = check_operand(right)
+
+    def build(self) -> str:
+        return f"{self.left.build()} {self.operator} {render_operand(self.right)}"
+
+
+class IsNull(Condition):
+    def __init__(self, operand: Comparable, negated: bool = False) -> None:
+        self.operand: Comparable = operand
+        self.negated: bool = negated
+
+    def build(self) -> str:
+        return f"{self.operand.build()} IS {'NOT ' if self.negated else ''}NULL"
+
+
+class In(Condition):
+    def __init__(self, left: Comparable, values: Iterable[object]) -> None:
+        # A str is iterable too, but `in_("ab")` would test each of its letters.
+        if isinstance(values, (str, bytes)) or not isinstance(values, Iterable):
+            raise TypeError(f"in_() takes a collection of values, got {type(values).__name__}.")
+        self.left: Comparable = left
+        self.values: tuple[object, ...] = tuple(check_operand(value) for value in values)
+        if not self.values:
+            raise ValueError("in_() needs at least one value.")
+
+    def build(self) -> str:
+        return f"{self.left.build()} IN ({', '.join(render_operand(value) for value in self.values)})"
+
+
+class Between(Condition):
+    def __init__(self, left: Comparable, low: object, high: object) -> None:
+        self.left: Comparable = left
+        self.low: object = check_operand(low)
+        self.high: object = check_operand(high)
+
+    def build(self) -> str:
+        return f"{self.left.build()} BETWEEN {render_operand(self.low)} AND {render_operand(self.high)}"
+
+
+class Junction(Condition):
+    """Conditions joined by AND or OR; each subclass only sets its `keyword` and how tightly it binds."""
+
+    keyword: str
+
+    def __init__(self, *conditions: Condition) -> None:
+        self.conditions: tuple[Condition, ...] = conditions
+
+    def build(self) -> str:
+        return f" {self.keyword} ".join(condition._build_within(self._binding) for condition in self.conditions)
+
+
+class And(Junction):
+    keyword = "AND"
+    _binding = 2
+
+
+class Or(Junction):
+    keyword = "OR"
+    _binding = 1
+
+
+class Not(Condition):
+    def __init__(self, condition: Condition) -> None:
+        self.condition: Condition = condition
+
+    def build(self) -> str:
+        return f"NOT ({self.condition.build()})"

sql_querystring_builder/query_builder.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 from collections.abc import Iterable
+from typing import Literal
 
 from .abstract_clause import Clause
-from .clauses import OrderBy, Select
+from .clauses import Delete, Insert, OrderBy, Select, Where
 from .exceptions import SqlQueryBuilderError
+from .values import parameterize
 
 
 class UnavailablePlaceException(SqlQueryBuilderError):
@@ -15,6 +17,14 @@ class IncompatibleClausesException(SqlQueryBuilderError):
     pass
 
 
+def _describe(clause: Clause) -> str:
+    """A clause's SQL for an error message, or its repr while it cannot be built (an Insert without rows)."""
+    try:
+        return clause.build()
+    except ValueError:
+        return repr(clause)
+
+
 class QueryBuilder:
     def __init__(self, *initial_clauses: Clause) -> None:
         self.places: dict[int, list[Clause]] = {}
@@ -25,7 +35,7 @@ class QueryBuilder:
         old_clause: Clause | None = self._place_is_unavailable(clause)
         if old_clause is not None:
             raise UnavailablePlaceException(
-                f"Cannot add a new clause with the same exclusive place in the query. New clause='{clause.build()}'. Old clause='{old_clause.build()}'"
+                f"Cannot add a new clause with the same exclusive place in the query. New clause='{_describe(clause)}'. Old clause='{_describe(old_clause)}'"
             )
         self.places[clause.place] = self.places.get(clause.place, []) + [clause]
         return self
@@ -37,12 +47,35 @@ class QueryBuilder:
 
     def build(self) -> str:
         clauses: list[Clause] = self._sorted_clauses()
-        # Checked at build time: TOP and paging can both be set after the clauses were added.
+        self._check_combination(clauses)
+        return "\n".join(clause.build() for clause in clauses)
+
+    @staticmethod
+    def _check_combination(clauses: list[Clause]) -> None:
+        """Rules across clauses, checked at build time: clauses stay mutable after being added."""
         has_top: bool = any(isinstance(clause, Select) and clause.top is not None for clause in clauses)
         has_paging: bool = any(isinstance(clause, OrderBy) and clause.has_paging for clause in clauses)
         if has_top and has_paging:
             raise IncompatibleClausesException("TOP cannot be combined with OFFSET/FETCH in the same query.")
-        return "\n".join(clause.build() for clause in clauses)
+        if len(clauses) > 1 and any(isinstance(clause, Insert) for clause in clauses):
+            raise IncompatibleClausesException("INSERT cannot be combined with other clauses in the same query.")
+        deletes: list[Delete] = [clause for clause in clauses if isinstance(clause, Delete)]
+        if deletes:
+            if any(isinstance(clause, OrderBy) for clause in clauses):
+                raise IncompatibleClausesException("ORDER BY cannot be combined with DELETE in the same query.")
+            if deletes[0].where_required and not any(isinstance(clause, Where) for clause in clauses):
+                raise IncompatibleClausesException(
+                    "A DELETE needs a WHERE, unless built with Delete(table, where_required=False)."
+                )
+
+    def build_with_params(self, style: Literal["qmark", "format"] = "qmark") -> tuple[str, tuple[object, ...]]:
+        """Builds the query with a placeholder for each value, and returns it with the values, in order.
+
+        Pass both to the database driver, as in `cursor.execute(sql, params)`, so that values never enter
+        the SQL text. "qmark" (`?`) suits pyodbc; "format" (`%s`) suits pymssql, and doubles every other `%`.
+        NULL, `Raw` and fields stay in the SQL, as do the TOP, OFFSET and FETCH counts.
+        """
+        return parameterize(self.build, style)
 
     def _place_is_unavailable(self, clause: Clause) -> Clause | None:
         if clause.place in self.places and clause.is_exclusive:

sql_querystring_builder/tables.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Iterator
 from string import ascii_letters, digits
 
+from .conditions import Comparable
 from .exceptions import SqlQueryBuilderError
 
 
@@ -119,7 +120,7 @@ def validate_name(name: str, is_hashtag_allowed: bool = False) -> str:
         is_first_part = False
 
 
-class Aliasable(ABC):
+class Aliasable(Comparable):
     def __init__(self, name: str, alias: str | None) -> None:
         self.name: str = name
         self.alias: str | None = alias

sql_querystring_builder/values.py

@@ -0,0 +1,139 @@
+"""Python values written into SQL: as T-SQL literals by `build()`, or as parameters by `build_with_params()`."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Callable
+from contextvars import ContextVar
+from datetime import date, datetime, time
+from decimal import Decimal
+from uuid import UUID
+
+_PLACEHOLDERS: dict[str, str] = {"qmark": "?", "format": "%s"}
+
+# The values collected while parameterize() runs; None the rest of the time, when values become literals.
+_params: ContextVar[list[object] | None] = ContextVar("sql_querystring_builder_params", default=None)
+# Until the whole query is built, a collected value stands in the SQL as "\x00<index>\x00". The placeholders
+# then follow the order of the final SQL text, whatever order the clauses rendered their values in.
+_SLOT: re.Pattern[str] = re.compile("\x00([0-9]+)\x00")
+
+
+class Raw:
+    """SQL written verbatim where a value goes, such as `Raw("GETDATE()")`: never escaped."""
+
+    def __init__(self, sql: str) -> None:
+        if not isinstance(sql, str):
+            raise TypeError(f"Raw takes a str, got {type(sql).__name__}.")
+        self.sql: str = sql
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.sql!r})"
+
+
+class Str:
+    """A string value, written as an escaped literal: `'O''Brien'`, or `N'café'` when it is not ASCII.
+
+    Conditions already take a plain str as a value. Str is for the places where a plain str is raw SQL,
+    such as `Update`.
+    """
+
+    def __init__(self, text: str) -> None:
+        if not isinstance(text, str):
+            raise TypeError(f"{self.__class__.__name__} takes a str, got {type(text).__name__}.")
+        self.text: str = text
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.text!r})"
+
+
+class NStr(Str):
+    """A string value always written as a Unicode literal, `N'…'`, even when it is ASCII."""
+
+
+def check_value(value: object) -> None:
+    """Raises TypeError or ValueError now, rather than at build time, if `value` cannot be written into SQL."""
+    _literal(value)
+
+
+def render_value(value: object) -> str:
+    """Writes a value as a T-SQL literal, or as a parameter while parameterize() runs.
+
+    NULL and Raw stay in the SQL text: NULL holds no data, and Raw is SQL.
+    """
+    literal: str = _literal(value)  # checks the value in both modes
+    params: list[object] | None = _params.get()
+    if params is None or value is None or isinstance(value, Raw):
+        return literal
+    params.append(value.text if isinstance(value, Str) else value)
+    return f"\x00{len(params) - 1}\x00"
+
+
+def parameterize(build: Callable[[], str], style: str) -> tuple[str, tuple[object, ...]]:
+    """Runs `build` with its values collected as parameters: returns the SQL with placeholders, and the values.
+
+    The values are a tuple because pymssql, the driver for the "format" style, refuses a list.
+    """
+    if style not in _PLACEHOLDERS:
+        raise ValueError(f"style must be 'qmark' or 'format', got {style!r}.")
+    collected: list[object] = []
+    token = _params.set(collected)
+    try:
+        sql: str = build()
+    finally:
+        _params.reset(token)
+    if style == "format":
+        sql = sql.replace("%", "%%")  # pymssql reads a lone % as the start of a placeholder
+    params: list[object] = []
+
+    def placeholder(slot: re.Match[str]) -> str:
+        params.append(collected[int(slot.group(1))])
+        return _PLACEHOLDERS[style]
+
+    return _SLOT.sub(placeholder, sql), tuple(params)
+
+
+def _literal(value: object) -> str:
+    if value is None:
+        return "NULL"
+    if isinstance(value, Raw):
+        return value.sql
+    if isinstance(value, Str):
+        return _string(value.text, unicode=isinstance(value, NStr))
+    if isinstance(value, str):
+        return _string(value)
+    if isinstance(value, bool):  # before int: bool is a subclass of int
+        return "1" if value else "0"
+    if isinstance(value, int):
+        return str(int(value))  # int() turns an IntEnum member into its number
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"{value!r} is not a valid T-SQL number.")
+        return repr(float(value))
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError(f"{value!r} is not a valid T-SQL number.")
+        return format(value, "f")  # never an exponent, which T-SQL would read as a float
+    if isinstance(value, datetime):  # before date: datetime is a subclass of date
+        return _string(value.isoformat(timespec=_timespec(value.microsecond)))
+    if isinstance(value, date):
+        # Unlike 'YYYY-MM-DD', this form reads the same under every language setting.
+        return f"'{value.year:04}{value.month:02}{value.day:02}'"
+    if isinstance(value, time):
+        return _string(value.isoformat(timespec=_timespec(value.microsecond)))
+    if isinstance(value, bytes):
+        return "0x" + value.hex().upper()
+    if isinstance(value, UUID):
+        return _string(str(value))
+    raise TypeError(f"Unsupported value type: {type(value).__name__}.")
+
+
+def _string(text: str, unicode: bool = False) -> str:
+    return ("N" if unicode or not text.isascii() else "") + "'" + text.replace("'", "''") + "'"
+
+
+def _timespec(microsecond: int) -> str:
+    """Milliseconds when they are exact, as `datetime` columns accept no more; microseconds otherwise."""
+    if microsecond == 0:
+        return "seconds"
+    return "milliseconds" if microsecond % 1000 == 0 else "microseconds"

{sql_querystring_builder-0.2.0.dist-info → sql_querystring_builder-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.2.0
+Version: 0.4.0
 Summary: Wraps string building of MS SQL queries
 Author-email: Wael GRIBAA <g.wael@outlook.fr>
 License-Expression: GPL-3.0-only
@@ -30,24 +30,27 @@ It provides first level validation.
     - [x] Field
     - [x] Function on field
     - [x] String
+    - [x] Conditions: eq, ne, lt, le, gt, ge, like, in_, between, is_null, is_not_null, combined with & | ~
+    - [x] Values: text, numbers, booleans, None, dates and times, bytes, UUIDs, and Raw SQL
 2. Using:
     - [x] Select (with DISTINCT and TOP)
-    - [x] Update
+    - [x] Update (with typed values)
+    - [x] Insert (multi-row VALUES)
+    - [x] Delete (with joins; refused without a WHERE unless asked)
     - [x] From
-    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin, CrossJoin
-    - [x] Where
+    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin (on two fields or on any condition), CrossJoin
+    - [x] Where (with conditions)
     - [x] OrderBy (with OFFSET/FETCH paging)
 3. Handling automatically:
     - [x] Table aliases
     - [x] Field aliases
+    - [x] Escaped values: 'O''Brien', N'café'
+    - [x] Parameterized queries: build_with_params() writes ? (pyodbc) or %s (pymssql) and returns the values
 
 ## Not implemented (yet)
 In planned order:
-- [ ] Proper conditions: typed values, AND/OR/NOT, IN, BETWEEN, LIKE, IS NULL
-- [ ] Insert and Delete
 - [ ] Functions (aggregates and others), GROUP BY, HAVING, CASE
 - [ ] Compound queries (UNION, INTERSECT, EXCEPT) and sub-queries
-- [ ] Parameterized queries
 
 ## What it does not do
     Connect to a database server and run the queries by itself.
@@ -72,8 +75,8 @@ atemptable = select.to_temptable("a_temp_table")
 innerjoin = InnerJoin(accounts_table, accounts_table.fields.customerId, customers_table)
 # Defines an Order By a defined field
 orderby = OrderBy(customers_table.fields.customerId, descending=True)
-# Adds a Where filter
-where = Where(accounts_table.fields.accountId, "> 20000 AND", customers_table.fields.customerId, "LIKE 'A1C%'")
+# Adds a Where filter: conditions are methods of fields, combined with & (and_), | (or_) and ~ (not_)
+where = Where(accounts_table.fields.accountId.gt(20000) & customers_table.fields.customerId.like("A1C%"))
 ```
 2. Inspect what those elements are made of:
 ```
@@ -117,6 +120,38 @@ print(QueryBuilder(
 # > SELECT #a_temp_table.id, #a_temp_table.cid, #a_temp_table.mainPhone, #a_temp_table.accountId
 # > FROM #a_temp_table
 ```
+5. Send the values as parameters, so that they never enter the SQL text:
+```
+# Builds the same query with a placeholder for each value, and returns the values in order
+sql, params = query_builder.build_with_params()
+print(sql)
+# > SELECT Customers.id, Customers.customerId AS cid, Customers.mainPhone, acc.accountId
+# > INTO #a_temp_table
+# > FROM Customers
+# > INNER JOIN Accounts acc on acc.customerId = Customers.customerId
+# > WHERE acc.accountId > ? AND Customers.customerId LIKE ?
+# > ORDER BY cid DESC
+print(params)
+# > (20000, 'A1C%')
+# With pyodbc: cursor.execute(sql, params). For pymssql, build_with_params("format") writes %s instead.
+```
+6. Insert and delete rows:
+```
+# Inserts rows: one tuple per row, with the values in column order
+insert = Insert(customers_table.fields.customerId, customers_table.fields.mainPhone).values(
+    ("A1C42", "555-0100"), ("B7", None)
+)
+print(QueryBuilder(insert).build())
+# > INSERT INTO Customers (customerId, mainPhone)
+# > VALUES ('A1C42', '555-0100'), ('B7', NULL)
+
+# Deletes the accounts of customer B7; a DELETE needs a WHERE, unless built with where_required=False
+delete = QueryBuilder(Delete(accounts_table), From(accounts_table), Where(accounts_table.fields.customerId.eq("B7")))
+print(delete.build())
+# > DELETE acc
+# > FROM Accounts acc
+# > WHERE acc.customerId = 'B7'
+```
 
 (Find it directly in the module example.py)
 
@@ -127,6 +162,44 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 0.4.0
+Queries built with 0.3.0 produce the same SQL.
+- `Insert(*columns).values(*rows)` renders `INSERT INTO Customers (id, name)` and
+  `VALUES (1, 'Ann'), (2, 'O''Brien')`. The columns are fields of one table, or a whole table. Each row is a
+  tuple of values in column order, with at most 1000 rows per INSERT, as in T-SQL. Values are escaped as in
+  conditions, plain strings included, and `Raw("DEFAULT")` writes SQL. An Insert stands alone in its query.
+- `Delete(table)` renders `DELETE` and the table's alias, or its name, and works with `From`, joins and
+  `Where`: `DELETE acc FROM Accounts acc INNER JOIN ...`. A query with a DELETE but no WHERE raises
+  `IncompatibleClausesException`, unless written `Delete(table, where_required=False)`; so does a DELETE with
+  ORDER BY.
+- Both work with `build_with_params()`. SQL Server accepts about 2,100 parameters per query, so split big
+  parameterized inserts.
+
+### 0.3.0
+Queries built with 0.2.0 produce the same SQL, except for the fixed `Update` values below.
+- Conditions are methods of fields, functions on fields and strings: `eq`, `ne`, `lt`, `le`, `gt`, `ge`,
+  `like`, `in_`, `between`, `is_null` and `is_not_null`; `eq(None)` renders `IS NULL`. Combine them with
+  `&`, `|` and `~`, or with `and_()`, `or_()` and `not_()`; parentheses are added where T-SQL needs them.
+  Python's `and`, `or` and `not` raise `TypeError`, since `c1 and c2` would silently keep only `c2`.
+- Values are escaped: text becomes `'O''Brien'`, or `N'café'` when it is not ASCII (`NStr("...")` forces
+  `N'...'`). Numbers, `True`/`False` (1/0), `None` (`NULL`), dates (`'20261011'`), datetimes and times
+  (ISO), bytes (`0x...`) and UUIDs are supported; `Raw("GETDATE()")` is written verbatim.
+- `Where(condition)`, also next to raw strings, and `on=condition` on every join, for multi-column joins.
+- `QueryBuilder.build_with_params()` returns the SQL with `?` placeholders and the values, for
+  `cursor.execute(sql, params)` with pyodbc; `build_with_params("format")` writes `%s` for pymssql.
+- `Update` values: a plain string is still raw SQL (`{f: "'x'"}`), `Str("O'Brien")` is an escaped string,
+  and other values render as in conditions.
+- New top-level names: `Condition`, `Raw`, `Str` and `NStr`.
+
+Fixed:
+- `Update` values `None`, `True`/`False`, dates and fields rendered invalid or wrong SQL: `f=None`,
+  `f=True`, `f=2026-10-11` (a subtraction) or the field's description. They now render `NULL`, `1`/`0`,
+  `'20261011'` and the field's qualified name. A `Decimal` with an exponent is written in full (`1000`, not
+  `1E+3`, which T-SQL reads as a float).
+
+Breaking:
+- `Update` values of an unsupported type raise `TypeError` instead of being written with `str()`.
+
 ### 0.2.0
 Queries built with 0.1.x produce the same SQL; see "Breaking" for the few behavior changes.
 - `LeftJoin`, `RightJoin` and `FullJoin` (same arguments as `InnerJoin`), and `CrossJoin(table)`.

sql_querystring_builder-0.4.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sql_querystring_builder/__init__.py,sha256=SZd2MlbJBCH49T1eE2W3B6fIwspRQDq1isImmbyHOwM,719
+sql_querystring_builder/abstract_clause.py,sha256=l1dGyhsu-k4QoNU16kXfDxLS4lXc02TJtlaNoUpHJXw,261
+sql_querystring_builder/clauses.py,sha256=QF9iHWrd7gnQy9MD4fQ3oEbFXwIEXuOYDpMVwSJJPNc,14361
+sql_querystring_builder/conditions.py,sha256=UaaZe1HBxAXSK25icOe0gR84zfOO0zxIKnFNSmndICg,7017
+sql_querystring_builder/exceptions.py,sha256=hdKvQD0Waqc251fRoNy6-eAnFKhQFyNtWqCaeqwd4VQ,140
+sql_querystring_builder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sql_querystring_builder/query_builder.py,sha256=V5hi8M73TnzM5qohxi88oEhPqa6919SuBNKiE4EeWiY,4115
+sql_querystring_builder/tables.py,sha256=T7QQjMoxpe1Iu1D3dOm8W8tWX1Z0kYIprxpaK3iGSJE,10897
+sql_querystring_builder/values.py,sha256=ef326zMUVxUxGHZ7Y0uZBooqbU473_f-DMMW6A-DlKI,5691
+sql_querystring_builder-0.4.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+sql_querystring_builder-0.4.0.dist-info/METADATA,sha256=Vj0h59ZceCuUAGGpfCrBXGKsrjZy_vyHyVNTYnke4BI,11874
+sql_querystring_builder-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sql_querystring_builder-0.4.0.dist-info/top_level.txt,sha256=U1YNBUlpIiidNaXjnScKqzNgTNVIhucoRPG3f287txU,24
+sql_querystring_builder-0.4.0.dist-info/RECORD,,

sql_querystring_builder-0.2.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-sql_querystring_builder/__init__.py,sha256=55ATxTSWWCkAFkMWPQBZv-9wznXDFNyQi826MA9mhx8,622
-sql_querystring_builder/abstract_clause.py,sha256=l1dGyhsu-k4QoNU16kXfDxLS4lXc02TJtlaNoUpHJXw,261
-sql_querystring_builder/clauses.py,sha256=Rxmuypxbum-QGdGRmz4BqjoEDW3aneAHFRYg38JT_ow,8070
-sql_querystring_builder/exceptions.py,sha256=hdKvQD0Waqc251fRoNy6-eAnFKhQFyNtWqCaeqwd4VQ,140
-sql_querystring_builder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sql_querystring_builder/query_builder.py,sha256=10MUAVrUj9JJbQ_1aRt8H5YBJ9Xi3SgdWWFwRsX25U4,2275
-sql_querystring_builder/tables.py,sha256=1AKnPTDUeO8h3zYE9-UeJYMdmpDfgADsXRx1UrT1BMo,10859
-sql_querystring_builder-0.2.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-sql_querystring_builder-0.2.0.dist-info/METADATA,sha256=wfzcT-_QCjfzGOW76bIQjNbLUwqppCMA4Vzvv-H2w7o,7267
-sql_querystring_builder-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-sql_querystring_builder-0.2.0.dist-info/top_level.txt,sha256=U1YNBUlpIiidNaXjnScKqzNgTNVIhucoRPG3f287txU,24
-sql_querystring_builder-0.2.0.dist-info/RECORD,,