sql_querystring_builder 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

sql_querystring_builder/__init__.py

@@ -1,3 +1,30 @@
-from .clauses import From, InnerJoin, OrderBy, Select, Update, Where
-from .query_builder import QueryBuilder
-from .tables import AliasableString, Field, FunctionOnField, Table, TempTable
+from .clauses import (
+    CrossJoin,
+    From,
+    FullJoin,
+    IncorrectUpdateException,
+    InnerJoin,
+    LeftJoin,
+    OrderBy,
+    RightJoin,
+    Select,
+    Update,
+    Where,
+)
+from .conditions import Condition
+from .exceptions import SqlQueryBuilderError
+from .query_builder import IncompatibleClausesException, QueryBuilder, UnavailablePlaceException
+from .tables import (
+    AliasableString,
+    AliasException,
+    AlreadyExistingFieldException,
+    Field,
+    FunctionOnField,
+    InvalidNameException,
+    NonExistingAliasException,
+    NonExistingFieldException,
+    Table,
+    TableException,
+    TempTable,
+)
+from .values import NStr, Raw, Str

sql_querystring_builder/clauses.py

@@ -1,19 +1,34 @@
 from __future__ import annotations
 
+from collections.abc import Mapping
+
 from .abstract_clause import Clause
+from .conditions import Condition, Junction, check_operand, render_operand
+from .exceptions import SqlQueryBuilderError
 from .tables import Aliasable, Field, Fields, Table, TempTable
 
 
-class IncorrectUpdateException(Exception):
+class IncorrectUpdateException(SqlQueryBuilderError):
     pass
 
 
 # TODO  Add INSERT
-# TODO  Add concept of condition
+
+
+def _row_count(keyword: str, value: int, minimum: int) -> int:
+    """Validates a row count for TOP, OFFSET or FETCH."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{keyword} must be an int, got {type(value).__name__}.")
+    if value < minimum:
+        expected: str = "zero or more" if minimum == 0 else f"at least {minimum}"
+        raise ValueError(f"{keyword} must be {expected}, got {value}.")
+    return value
 
 
 class Select(Clause):
-    def __init__(self, *fields: Fields | Aliasable | Table) -> None:
+    def __init__(self, *fields: Fields | Aliasable | Table, distinct: bool = False, top: int | None = None) -> None:
+        if top is not None:
+            _row_count("TOP", top, minimum=0)
         self.fields: list[Aliasable] = []
         for el in fields:
             if isinstance(el, Fields):
@@ -22,6 +37,8 @@ class Select(Clause):
                 self.fields.extend(el.fields.as_list())
             else:
                 self.fields.append(el)
+        self.distinct: bool = distinct
+        self.top: int | None = top
         self.temp_table: TempTable | None = None
 
     @property
@@ -29,9 +46,13 @@ class Select(Clause):
         return 0
 
     def build(self) -> str:
-        ret: str = "SELECT " if self.fields else "SELECT *"
-        ret += ", ".join([field.build(True, True) for field in self.fields])
-        if self.temp_table:
+        head: str = "SELECT"
+        if self.distinct:
+            head += " DISTINCT"
+        if self.top is not None:
+            head += f" TOP ({self.top})"
+        ret: str = f"{head} " + (", ".join([field.build(True, True) for field in self.fields]) if self.fields else "*")
+        if self.temp_table is not None:
             ret += "\nINTO " + self.temp_table.build()
         return ret
 
@@ -40,7 +61,10 @@ class Select(Clause):
         return self.temp_table
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}(fields={self.fields})"
+        options: str = (", distinct=True" if self.distinct else "") + (
+            f", top={self.top}" if self.top is not None else ""
+        )
+        return f"{self.__class__.__name__}(fields={self.fields}{options})"
 
 
 class From(Clause):
@@ -59,8 +83,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:
@@ -69,20 +95,44 @@ 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:
         return f"{self.__class__.__name__}(conditions={self.conditions})"
 
 
-class InnerJoin(Clause):
-    def __init__(self, table: Table, on_left: Field, on_right: Field | Table) -> None:
+class Join(Clause):
+    """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 | 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.__getattr__(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:
@@ -93,17 +143,60 @@ class InnerJoin(Clause):
         return False
 
     def build(self) -> str:
-        return f"INNER JOIN {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})"
 
 
+class InnerJoin(Join):
+    keyword = "INNER JOIN"
+
+
+class LeftJoin(Join):
+    keyword = "LEFT JOIN"
+
+
+class RightJoin(Join):
+    keyword = "RIGHT JOIN"
+
+
+class FullJoin(Join):
+    keyword = "FULL JOIN"
+
+
+class CrossJoin(Clause):
+    def __init__(self, table: Table) -> None:
+        self.table: Table = table
+
+    @property
+    def place(self) -> int:
+        return 3
+
+    @property
+    def is_exclusive(self) -> bool:
+        return False
+
+    def build(self) -> str:
+        return f"CROSS JOIN {self.table.build(use_name=True)}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(table={self.table})"
+
+
 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:
@@ -116,7 +209,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
@@ -124,7 +217,11 @@ 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:
@@ -134,20 +231,43 @@ class Update(Clause):
 class OrderBy(Clause):
     def __init__(self, field: Aliasable, descending: bool = False) -> None:
         self.ordering: list[tuple[Aliasable, bool]] = [(field, descending)]
+        self.offset_rows: int | None = None
+        self.fetch_rows: int | None = None
 
     @property
     def place(self) -> int:
         return 5
 
+    @property
+    def has_paging(self) -> bool:
+        return self.offset_rows is not None or self.fetch_rows is not None
+
     def add(self, field: Aliasable, descending: bool = False) -> OrderBy:
         self.ordering.append((field, descending))
         return self
 
+    def offset(self, rows: int) -> OrderBy:
+        self.offset_rows = _row_count("OFFSET", rows, minimum=0)
+        return self
+
+    def fetch(self, rows: int) -> OrderBy:
+        self.fetch_rows = _row_count("FETCH", rows, minimum=1)
+        return self
+
     def build(self) -> str:
         ret_list: list[str] = []
         for field, desc in self.ordering:
             ret_list.append(f"{field.build(use_name=False, use_alias=True)}{' DESC' if desc else ''}")
-        return "ORDER BY " + ", ".join(ret_list)
+        ret: str = "ORDER BY " + ", ".join(ret_list)
+        if self.has_paging:
+            # T-SQL requires OFFSET before FETCH: fetch() alone starts at the first row.
+            ret += f"\nOFFSET {self.offset_rows or 0} ROWS"
+            if self.fetch_rows is not None:
+                ret += f" FETCH NEXT {self.fetch_rows} ROWS ONLY"
+        return ret
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}(ordering={self.ordering})"
+        paging: str = (f", offset={self.offset_rows}" if self.offset_rows is not None else "") + (
+            f", fetch={self.fetch_rows}" if self.fetch_rows is not None else ""
+        )
+        return f"{self.__class__.__name__}(ordering={self.ordering}{paging})"

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/exceptions.py

@@ -0,0 +1,2 @@
+class SqlQueryBuilderError(Exception):
+    """Base class of every exception the library raises, so callers can catch them all at once."""

sql_querystring_builder/query_builder.py

@@ -1,11 +1,19 @@
 from __future__ import annotations
 
 from collections.abc import Iterable
+from typing import Literal
 
 from .abstract_clause import Clause
+from .clauses import OrderBy, Select
+from .exceptions import SqlQueryBuilderError
+from .values import parameterize
 
 
-class UnavailablePlaceException(Exception):
+class UnavailablePlaceException(SqlQueryBuilderError):
+    pass
+
+
+class IncompatibleClausesException(SqlQueryBuilderError):
     pass
 
 
@@ -17,7 +25,7 @@ class QueryBuilder:
 
     def add(self, clause: Clause) -> QueryBuilder:
         old_clause: Clause | None = self._place_is_unavailable(clause)
-        if old_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()}'"
             )
@@ -30,7 +38,22 @@ class QueryBuilder:
         return self
 
     def build(self) -> str:
-        return "\n".join(clause.build() for clause in self._sorted_clauses())
+        clauses: list[Clause] = self._sorted_clauses()
+        # Checked at build time: TOP and paging can both be set after the clauses were 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)
+
+    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,30 +1,34 @@
 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
 
-class AliasException(Exception):
+
+class AliasException(SqlQueryBuilderError):
     pass
 
 
-class AlreadyExistingFieldException(Exception):
+class AlreadyExistingFieldException(SqlQueryBuilderError):
     pass
 
 
-class InvalidNameException(Exception):
+class InvalidNameException(SqlQueryBuilderError):
     pass
 
 
-class NonExistingAliasException(Exception):
+class NonExistingAliasException(SqlQueryBuilderError):
     pass
 
 
-class NonExistingFieldException(AttributeError):
+class NonExistingFieldException(SqlQueryBuilderError, AttributeError):
     pass
 
 
-class TableException(Exception):
+class TableException(SqlQueryBuilderError):
     pass
 
 
@@ -50,8 +54,18 @@ def validate_name(name: str, is_hashtag_allowed: bool = False) -> str:
     ------
     InvalidNameException
         Raised if the name cannot reprensent an element in a strict MS SQL conventions.
+
+    Notes
+    -----
+    Each dot-separated part is either a regular identifier (letters, digits and underscores) or a
+    bracketed one (`[My Table]`), which may hold any character, dots included; `]]` stands for `]`.
     """
 
+    def forbidden_character(pos: int) -> InvalidNameException:
+        return InvalidNameException(
+            f"Forbidden character '{name[pos]}' was found in the name '{name}' at position {pos}. Only letters, digits and undersores are allowed."
+        )
+
     def validate_subname(subname: str, startpos: int = 0, is_temp_table_start: bool = False) -> None:
         max_length: int = 116 if is_temp_table_start else 128
         if len(subname) > max_length:
@@ -62,25 +76,51 @@ def validate_name(name: str, is_hashtag_allowed: bool = False) -> str:
             if is_temp_table_start and pos == 0 and c == "#":
                 continue  # is indeed a temp table starting with #
             if c not in NAMEABLE_CHARS:
-                if (c != "[" or pos != 0) and (c != "]" or pos != len(subname) - 1):
-                    raise InvalidNameException(
-                        f"Forbidden character '{c}' was found in the name '{name}' at position {pos + startpos}. Only letters, digits and undersores are allowed."
-                    )
+                raise forbidden_character(pos + startpos)
+
+    def bracketed_end(start: int) -> int:
+        """Returns the position just after the `]` that closes the `[` at `start`."""
+        pos: int = start + 1
+        while True:
+            close: int = name.find("]", pos)
+            if close == -1:
+                raise InvalidNameException(f"The name {name} has an unclosed '[' at position {start}.")
+            if not name.startswith("]]", close):
+                return close + 1
+            pos = close + 2  # "]]" is an escaped "]" inside the brackets
 
     if not name:
         raise InvalidNameException("Empty names are forbidden.")
-    if name[0] not in ascii_letters:
+    if name[0] not in ascii_letters and name[0] != "[":
         if not is_hashtag_allowed or name[0] != "#":
             raise InvalidNameException(f"The name {name} does not start with a letter.")
-    absolute_pos: int = 0
-    for i_split, subname in enumerate(name.split(".")):
-        is_temp_table_start: bool = i_split == 0 and is_hashtag_allowed
-        validate_subname(subname, startpos=absolute_pos, is_temp_table_start=is_temp_table_start)
-        absolute_pos += len(subname) + 1  # +1 to account for the '.'
-    return name
-
-
-class Aliasable(ABC):
+    pos: int = 0
+    is_first_part: bool = True
+    while True:
+        if name.startswith("[", pos):
+            end: int = bracketed_end(pos)
+            content: str = name[pos + 1 : end - 1].replace("]]", "]")
+            if not content:
+                raise InvalidNameException(f"The name {name} has an empty bracketed part at position {pos}.")
+            if len(content) > 128:
+                raise InvalidNameException(
+                    f"The name {name} is too long or has a component that is too long (got {len(content)}, max is 128)."
+                )
+        else:
+            end = name.find(".", pos)
+            if end == -1:
+                end = len(name)
+            validate_subname(name[pos:end], startpos=pos, is_temp_table_start=is_first_part and is_hashtag_allowed)
+        pos = end
+        if pos == len(name):
+            return name
+        if name[pos] != ".":
+            raise forbidden_character(pos)
+        pos += 1
+        is_first_part = False
+
+
+class Aliasable(Comparable):
     def __init__(self, name: str, alias: str | None) -> None:
         self.name: str = name
         self.alias: str | None = alias
@@ -166,31 +206,52 @@ class Fields:
 
     def __getattr__(self, attr_name: str) -> Field:
         # copy and pickle look attributes up on instances whose __init__ never ran, so `fields` may be missing.
-        fields: dict[str, Field] | None = self.__dict__.get("fields")
-        if fields is None:
+        if "fields" not in self.__dict__:
             raise AttributeError(attr_name)
-        res: Field | None = fields.get(attr_name)
+        return self[attr_name]
+
+    # Only dunder methods below: a new public method name would shadow fields named like it.
+    def __getitem__(self, name: str) -> Field:
+        res: Field | None = self.fields.get(name)
         if res is None:
-            raise NonExistingFieldException(f"No field named '{attr_name}' in the table {self.table}.")
+            raise NonExistingFieldException(f"No field named '{name}' in the table {self.table}.")
         return res
 
+    def __contains__(self, item: object) -> bool:
+        if isinstance(item, Field):
+            return self.fields.get(item.name) is item
+        return isinstance(item, str) and item in self.fields
+
+    def __iter__(self) -> Iterator[Field]:
+        return iter(self.fields.values())
+
+    def __len__(self) -> int:
+        return len(self.fields)
+
     def __repr__(self) -> str:
         return f"Fields(table='{self.table.name}', [{','.join(repr(field) for field in self.fields.values())}])"
 
 
 class Table:
-    def __init__(self, name: str, alias: str | None = None, field_names: list[str] | None = None, **kwargs) -> None:
-        self.name: str = validate_name(name, kwargs.get("is_hashtag_allowed", False))
+    def __init__(
+        self,
+        name: str,
+        alias: str | None = None,
+        field_names: list[str] | None = None,
+        *,
+        is_hashtag_allowed: bool = False,
+    ) -> None:
+        self.name: str = validate_name(name, is_hashtag_allowed)
         self.alias: str | None = alias
         self.fields: Fields = Fields(self)
         if field_names:
             self.add(*field_names)
 
-    def with_fields(self, *args, **kwargs) -> Table:
+    def with_fields(self, *fields: Field | str) -> Table:
         """
         Alias to self.add()
         """
-        return self.add(*args, **kwargs)
+        return self.add(*fields)
 
     def add(self, *fields: Field | str) -> Table:
         self.fields.add(*fields)
@@ -220,8 +281,7 @@ class Table:
 class TempTable(Table):
     def __init__(self, name: str, *fields: str | Aliasable | Fields) -> None:
         if not isinstance(name, str):
-            # A bare Exception is public behavior, pinned by test_characterization.
-            raise Exception("Argument 'name' is not a string.")  # noqa: TRY002, TRY004
+            raise TypeError("Argument 'name' is not a string.")
         super().__init__(name=f"#{name}", is_hashtag_allowed=True)
         field_names: list[str] = []
         # Columns are named as SELECT ... INTO names them: after the alias when there is one.

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.1.1.dist-info → sql_querystring_builder-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.1.1
+Version: 0.3.0
 Summary: Wraps string building of MS SQL queries
 Author-email: Wael GRIBAA <g.wael@outlook.fr>
 License-Expression: GPL-3.0-only
@@ -30,25 +30,26 @@ 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
-    - [x] Update
+    - [x] Select (with DISTINCT and TOP)
+    - [x] Update (with typed values)
     - [x] From
-    - [x] InnerJoin
-    - [x] Where
-    - [x] OrderBy
+    - [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:
-- [ ] LEFT, RIGHT, FULL and CROSS joins; SELECT DISTINCT and TOP; paging (OFFSET/FETCH)
-- [ ] 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.
@@ -73,8 +74,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, "gt 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:
 ```
@@ -97,7 +98,7 @@ print(query_str)
 # > INTO #a_temp_table
 # > FROM Customers
 # > INNER JOIN Accounts acc on acc.customerId = Customers.customerId
-# > WHERE acc.accountId gt 20000 AND Customers.customerId LIKE 'A1C%'
+# > WHERE acc.accountId > 20000 AND Customers.customerId LIKE 'A1C%'
 # > ORDER BY cid DESC
 ```
 4. Manipulate temporary tables whose components are inferred:
@@ -118,6 +119,21 @@ 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.
+```
 
 (Find it directly in the module example.py)
 
@@ -128,6 +144,49 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 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)`.
+- `Select(..., distinct=True, top=10)` renders `SELECT DISTINCT TOP (10) ...`.
+- `OrderBy(...).offset(20).fetch(10)` adds `OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY`. Combining paging with
+  TOP raises `IncompatibleClausesException`.
+- Every exception derives from `SqlQueryBuilderError` and can be imported from `sql_querystring_builder`.
+- `table.fields["name"]`, `"name" in table.fields`, iteration and `len()`. `table.fields["add"]` also
+  reaches fields whose names clash with `Fields` methods.
+- Table names accept bracketed parts anywhere: `[Order]`, `dbo.[My Table]` (`]]` stands for `]`).
+- The README example uses `>` instead of `gt`, which is not a T-SQL operator.
+
+Breaking:
+- `TempTable(3)` raises `TypeError` instead of a bare `Exception` (same message).
+- Unknown keyword arguments to `Table`, such as `fields=[...]`, raise `TypeError` instead of being ignored.
+- Malformed bracketed names such as `dbo.Order]` or `dbo.[Order` are rejected.
+- An empty `table.fields` is now falsy.
+
 ### 0.1.1
 No change to the generated SQL.
 - The package ships a `py.typed` marker, so type checkers such as mypy now use its type hints.

sql_querystring_builder-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sql_querystring_builder/__init__.py,sha256=led5wLchgLCroLb3he49GPCuQImWlSZ5hhVVcuDg2x8,693
+sql_querystring_builder/abstract_clause.py,sha256=l1dGyhsu-k4QoNU16kXfDxLS4lXc02TJtlaNoUpHJXw,261
+sql_querystring_builder/clauses.py,sha256=uSvCv7m3JSsM3THEH__JsUkintgdyxLNqsirR68tPVw,9956
+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=MxWzmISZBNzNlFmpbTLENQWSPAzZsts1BZHrjAuzE4k,2928
+sql_querystring_builder/tables.py,sha256=T7QQjMoxpe1Iu1D3dOm8W8tWX1Z0kYIprxpaK3iGSJE,10897
+sql_querystring_builder/values.py,sha256=ef326zMUVxUxGHZ7Y0uZBooqbU473_f-DMMW6A-DlKI,5691
+sql_querystring_builder-0.3.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+sql_querystring_builder-0.3.0.dist-info/METADATA,sha256=7L53tLZwnT18Gwcl31vL6Q3gG3c83LkqRWX6Ut-4n_4,10159
+sql_querystring_builder-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sql_querystring_builder-0.3.0.dist-info/top_level.txt,sha256=U1YNBUlpIiidNaXjnScKqzNgTNVIhucoRPG3f287txU,24
+sql_querystring_builder-0.3.0.dist-info/RECORD,,

sql_querystring_builder-0.1.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-sql_querystring_builder/__init__.py,sha256=Vyiejs1sPHpZC9Qzo97TQVFDHurW8eGraFeWyUe46I0,190
-sql_querystring_builder/abstract_clause.py,sha256=l1dGyhsu-k4QoNU16kXfDxLS4lXc02TJtlaNoUpHJXw,261
-sql_querystring_builder/clauses.py,sha256=G4XCk2ssmUYIQBctTle_tz6qwZ946jmL62dFqgz-ZsQ,5294
-sql_querystring_builder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sql_querystring_builder/query_builder.py,sha256=n9kkifkAXTJos--T2wlGcsqA9xIXRzYa-SjPPpi0qxk,1601
-sql_querystring_builder/tables.py,sha256=e_FFuc44o4ZAkM3iy37f61ddPp7xdGBiBgsOmMCIv6A,8831
-sql_querystring_builder-0.1.1.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-sql_querystring_builder-0.1.1.dist-info/METADATA,sha256=5wVbwJqPLg8QFLh1uU940n4HcEUebqQMdgJfz8GN5_E,6053
-sql_querystring_builder-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-sql_querystring_builder-0.1.1.dist-info/top_level.txt,sha256=U1YNBUlpIiidNaXjnScKqzNgTNVIhucoRPG3f287txU,24
-sql_querystring_builder-0.1.1.dist-info/RECORD,,