sql_querystring_builder 0.1.1__tar.gz → 0.2.0__tar.gz

{sql_querystring_builder-0.1.1/src/sql_querystring_builder.egg-info → sql_querystring_builder-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.1.1
+Version: 0.2.0
 Summary: Wraps string building of MS SQL queries
 Author-email: Wael GRIBAA <g.wael@outlook.fr>
 License-Expression: GPL-3.0-only
@@ -31,19 +31,18 @@ It provides first level validation.
     - [x] Function on field
     - [x] String
 2. Using:
-    - [x] Select
+    - [x] Select (with DISTINCT and TOP)
     - [x] Update
     - [x] From
-    - [x] InnerJoin
+    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin, CrossJoin
     - [x] Where
-    - [x] OrderBy
+    - [x] OrderBy (with OFFSET/FETCH paging)
 3. Handling automatically:
     - [x] Table aliases
     - [x] Field aliases
 
 ## 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
@@ -74,7 +73,7 @@ innerjoin = InnerJoin(accounts_table, accounts_table.fields.customerId, customer
 # 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%'")
+where = Where(accounts_table.fields.accountId, "> 20000 AND", customers_table.fields.customerId, "LIKE 'A1C%'")
 ```
 2. Inspect what those elements are made of:
 ```
@@ -97,7 +96,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:
@@ -128,6 +127,24 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 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.1.1 → sql_querystring_builder-0.2.0}/README.md

@@ -10,19 +10,18 @@ It provides first level validation.
     - [x] Function on field
     - [x] String
 2. Using:
-    - [x] Select
+    - [x] Select (with DISTINCT and TOP)
     - [x] Update
     - [x] From
-    - [x] InnerJoin
+    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin, CrossJoin
     - [x] Where
-    - [x] OrderBy
+    - [x] OrderBy (with OFFSET/FETCH paging)
 3. Handling automatically:
     - [x] Table aliases
     - [x] Field aliases
 
 ## 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
@@ -53,7 +52,7 @@ innerjoin = InnerJoin(accounts_table, accounts_table.fields.customerId, customer
 # 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%'")
+where = Where(accounts_table.fields.accountId, "> 20000 AND", customers_table.fields.customerId, "LIKE 'A1C%'")
 ```
 2. Inspect what those elements are made of:
 ```
@@ -76,7 +75,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:
@@ -107,6 +106,24 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 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.1.1 → sql_querystring_builder-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sql_querystring_builder"
-version = "0.1.1"
+version = "0.2.0"
 authors = [
   { name="Wael GRIBAA", email="g.wael@outlook.fr" },
 ]
@@ -34,6 +34,7 @@ dev = [
     "mypy>=2.4.0",
     "pytest>=9.1.1",
     "ruff>=0.17.0",
+    "sqlglot==30.19.0",
 ]
 
 [tool.ruff]

sql_querystring_builder-0.2.0/src/sql_querystring_builder/__init__.py

@@ -0,0 +1,28 @@
+from .clauses import (
+    CrossJoin,
+    From,
+    FullJoin,
+    IncorrectUpdateException,
+    InnerJoin,
+    LeftJoin,
+    OrderBy,
+    RightJoin,
+    Select,
+    Update,
+    Where,
+)
+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,
+)

{sql_querystring_builder-0.1.1 → sql_querystring_builder-0.2.0}/src/sql_querystring_builder/clauses.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 from .abstract_clause import Clause
+from .exceptions import SqlQueryBuilderError
 from .tables import Aliasable, Field, Fields, Table, TempTable
 
 
-class IncorrectUpdateException(Exception):
+class IncorrectUpdateException(SqlQueryBuilderError):
     pass
 
 
@@ -12,8 +13,20 @@ class IncorrectUpdateException(Exception):
 # 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 +35,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 +44,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 +59,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):
@@ -76,13 +98,15 @@ class Where(Clause):
         return f"{self.__class__.__name__}(conditions={self.conditions})"
 
 
-class InnerJoin(Clause):
+class Join(Clause):
+    """A join on `on_left = on_right`; each subclass only sets its `keyword`."""
+
+    keyword: str
+
     def __init__(self, table: Table, on_left: Field, on_right: Field | Table) -> None:
         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_right: Field = on_right if isinstance(on_right, Aliasable) else on_right.fields[on_left.name]
 
     @property
     def place(self) -> int:
@@ -93,12 +117,47 @@ 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_left.build()} = {self.on_right.build()}"
 
     def __repr__(self) -> str:
         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:
         if not updates:
@@ -134,20 +193,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-0.2.0/src/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-0.1.1 → sql_querystring_builder-0.2.0}/src/sql_querystring_builder/query_builder.py

@@ -3,9 +3,15 @@ from __future__ import annotations
 from collections.abc import Iterable
 
 from .abstract_clause import Clause
+from .clauses import OrderBy, Select
+from .exceptions import SqlQueryBuilderError
 
 
-class UnavailablePlaceException(Exception):
+class UnavailablePlaceException(SqlQueryBuilderError):
+    pass
+
+
+class IncompatibleClausesException(SqlQueryBuilderError):
     pass
 
 
@@ -17,7 +23,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 +36,13 @@ 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 _place_is_unavailable(self, clause: Clause) -> Clause | None:
         if clause.place in self.places and clause.is_exclusive:

{sql_querystring_builder-0.1.1 → sql_querystring_builder-0.2.0}/src/sql_querystring_builder/tables.py

@@ -1,30 +1,33 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from collections.abc import Iterator
 from string import ascii_letters, digits
 
+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 +53,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,22 +75,48 @@ 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
+    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(ABC):
@@ -166,31 +205,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 +280,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-0.1.1 → sql_querystring_builder-0.2.0/src/sql_querystring_builder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.1.1
+Version: 0.2.0
 Summary: Wraps string building of MS SQL queries
 Author-email: Wael GRIBAA <g.wael@outlook.fr>
 License-Expression: GPL-3.0-only
@@ -31,19 +31,18 @@ It provides first level validation.
     - [x] Function on field
     - [x] String
 2. Using:
-    - [x] Select
+    - [x] Select (with DISTINCT and TOP)
     - [x] Update
     - [x] From
-    - [x] InnerJoin
+    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin, CrossJoin
     - [x] Where
-    - [x] OrderBy
+    - [x] OrderBy (with OFFSET/FETCH paging)
 3. Handling automatically:
     - [x] Table aliases
     - [x] Field aliases
 
 ## 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
@@ -74,7 +73,7 @@ innerjoin = InnerJoin(accounts_table, accounts_table.fields.customerId, customer
 # 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%'")
+where = Where(accounts_table.fields.accountId, "> 20000 AND", customers_table.fields.customerId, "LIKE 'A1C%'")
 ```
 2. Inspect what those elements are made of:
 ```
@@ -97,7 +96,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:
@@ -128,6 +127,24 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 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.1.1 → sql_querystring_builder-0.2.0}/src/sql_querystring_builder.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/sql_querystring_builder/__init__.py
 src/sql_querystring_builder/abstract_clause.py
 src/sql_querystring_builder/clauses.py
+src/sql_querystring_builder/exceptions.py
 src/sql_querystring_builder/py.typed
 src/sql_querystring_builder/query_builder.py
 src/sql_querystring_builder/tables.py
@@ -15,4 +16,5 @@ tests/test_characterization.py
 tests/test_clauses.py
 tests/test_queries.py
 tests/test_readme.py
+tests/test_sql_syntax.py
 tests/test_tables.py

{sql_querystring_builder-0.1.1 → sql_querystring_builder-0.2.0}/tests/test_characterization.py

@@ -2,7 +2,7 @@
 
 A failure here means rendered output or behavior changed. If that is intended, update the
 expectation in the same commit and say so in the commit message. Some tests pin surprising behavior
-on purpose (verbatim strings, ignored keyword arguments, shadowed field names); changing it is the
+on purpose (verbatim strings, shadowed field names); changing it is the
 owner's call.
 """
 
@@ -30,17 +30,32 @@ class TestPublicApi(TestCase):
     def test_top_level_names(self):
         expected_names: set[str] = {
             "AliasableString",
+            "CrossJoin",
             "Field",
             "From",
+            "FullJoin",
             "FunctionOnField",
             "InnerJoin",
+            "LeftJoin",
             "OrderBy",
+            "RightJoin",
             "QueryBuilder",
             "Select",
             "Table",
             "TempTable",
             "Update",
             "Where",
+            # Exceptions, also importable from their submodules.
+            "AliasException",
+            "AlreadyExistingFieldException",
+            "IncompatibleClausesException",
+            "IncorrectUpdateException",
+            "InvalidNameException",
+            "NonExistingAliasException",
+            "NonExistingFieldException",
+            "SqlQueryBuilderError",
+            "TableException",
+            "UnavailablePlaceException",
         }
         actual_names: set[str] = {name for name in dir(sql_querystring_builder) if name[0].isupper()}
         self.assertEqual(actual_names, expected_names)
@@ -56,12 +71,14 @@ class TestPublicApi(TestCase):
                 "TableException",
             ],
             clauses: ["IncorrectUpdateException"],
-            query_builder: ["UnavailablePlaceException"],
+            query_builder: ["IncompatibleClausesException", "UnavailablePlaceException"],
         }
         for module, names in expected_exceptions.items():
             for name in names:
                 with self.subTest(module=module.__name__, name=name):
-                    self.assertTrue(issubclass(getattr(module, name), Exception))
+                    exception = getattr(module, name)
+                    self.assertTrue(issubclass(exception, sql_querystring_builder.SqlQueryBuilderError))
+                    self.assertIs(getattr(sql_querystring_builder, name), exception)
 
 
 class TestLateBinding(TestCase):
@@ -105,9 +122,8 @@ class TestTempTables(TestCase):
         self.assertEqual(str(exc.exception), "The field '#d.field.card' already exists.")
 
     def test_name_must_be_a_string(self):
-        with self.assertRaises(Exception) as exc:
+        with self.assertRaises(TypeError) as exc:
             TempTable(3)
-        self.assertIs(type(exc.exception), Exception)
         self.assertEqual(str(exc.exception), "Argument 'name' is not a string.")
 
     def test_empty_select(self):
@@ -214,17 +230,34 @@ class TestRendering(TestCase):
 
 class TestNameValidation(TestCase):
     def test_accepted_names(self):
-        for name in ["dbo.Customers", "dbo.[Order]", "a..b", "a."]:
+        names: list[str] = [
+            "dbo.Customers",
+            "dbo.[Order]",
+            "a..b",
+            "a.",
+            "[Order]",
+            "dbo.[My Table]",
+            "[dbo].[My Table]",
+            "[my.table]",  # dots are allowed inside brackets
+            "[a]]b]",  # "]]" is an escaped "]"
+        ]
+        for name in names:
             with self.subTest(name=name):
                 self.assertEqual(Table(name).name, name)
 
     def test_rejected_names(self):
         expected_err_msgs: dict[str, str] = {
-            "[Order]": "The name [Order] does not start with a letter.",
-            "dbo.[My Table]": "Forbidden character ' ' was found in the name 'dbo.[My Table]' at position 7. "
-            "Only letters, digits and undersores are allowed.",
             "dbo.Cust-omers": "Forbidden character '-' was found in the name 'dbo.Cust-omers' at position 8. "
             "Only letters, digits and undersores are allowed.",
+            "[Order": "The name [Order has an unclosed '[' at position 0.",
+            "dbo.[x": "The name dbo.[x has an unclosed '[' at position 4.",
+            "[]": "The name [] has an empty bracketed part at position 0.",
+            "[a]b": "Forbidden character 'b' was found in the name '[a]b' at position 3. "
+            "Only letters, digits and undersores are allowed.",
+            "dbo.Order]": "Forbidden character ']' was found in the name 'dbo.Order]' at position 9. "
+            "Only letters, digits and undersores are allowed.",
+            "x[y]": "Forbidden character '[' was found in the name 'x[y]' at position 1. "
+            "Only letters, digits and undersores are allowed.",
         }
         for name, expected_err_msg in expected_err_msgs.items():
             with self.subTest(name=name):
@@ -232,6 +265,15 @@ class TestNameValidation(TestCase):
                     Table(name)
                 self.assertEqual(str(exc.exception), expected_err_msg)
 
+    def test_too_long_bracketed_part(self):
+        name: str = "[" + "b" * 129 + "]"
+        with self.assertRaises(InvalidNameException) as exc:
+            Table(name)
+        self.assertEqual(
+            str(exc.exception),
+            f"The name {name} is too long or has a component that is too long (got 129, max is 128).",
+        )
+
     def test_too_long_second_component(self):
         name: str = "a." + "b" * 129
         with self.assertRaises(InvalidNameException) as exc:
@@ -283,5 +325,8 @@ class TestFieldsQuirks(TestCase):
         self.assertEqual(Select(copied_table).build(), "SELECT tt.a")
         self.assertEqual(list(copy.copy(table.fields).fields), ["a"])
 
-    def test_unknown_keyword_argument_is_ignored(self):
-        self.assertEqual(list(Table("x", fields=["a"]).fields.fields), [])
+    def test_unknown_keyword_argument_is_rejected(self):
+        with self.assertRaises(TypeError) as exc:
+            Table("x", fields=["a"])
+        # Python writes this message itself, and its prefix varies between versions.
+        self.assertIn("unexpected keyword argument 'fields'", str(exc.exception))

sql_querystring_builder-0.2.0/tests/test_clauses.py

@@ -0,0 +1,233 @@
+from unittest import TestCase
+
+from sql_querystring_builder.clauses import (
+    CrossJoin,
+    From,
+    FullJoin,
+    IncorrectUpdateException,
+    InnerJoin,
+    LeftJoin,
+    OrderBy,
+    RightJoin,
+    Select,
+    Update,
+    Where,
+)
+from sql_querystring_builder.query_builder import IncompatibleClausesException, QueryBuilder
+from sql_querystring_builder.tables import Field, NonExistingFieldException, Table, TempTable
+
+
+class TestClauses(TestCase):
+    def setUp(self) -> None:
+        self.maxDiff = None
+
+        self.table1: Table = Table(name="TestTable", alias="TT", field_names=["TestField1", "TestField2"])
+        self.table2: Table = Table(name="TestTable2", alias="TT2", field_names=["TestField21", "TestField22"])
+
+        self.select: Select = Select(self.table1.fields.TestField2, self.table2)
+        self.testtemptable: TempTable = self.select.to_temptable("ttt")
+        self.table1field1: Field = self.table1.fields.TestField1
+        self.table1field2: Field = self.table1.fields.TestField2
+        self.table2field21: Field = self.table2.fields.TestField21
+        self.table2field22: Field = self.table2.fields.TestField22
+
+    def test_init_select(self):
+        self.assertEqual(self.select.fields, [self.table1field2, self.table2field21, self.table2field22])
+
+    def test_select_build(self):
+        expected_result: str = "SELECT TT.TestField1, TT.TestField2, TT2.TestField21"
+        actual_result: str = Select(self.table1, self.table2.fields.TestField21).build()
+        self.assertEqual(actual_result, expected_result)
+
+    def test_from_build(self):
+        expected_result: str = "WHERE TT.TestField2 has a very unique condition"
+        actual_result: str = Where(self.table1field2, "has a very unique condition").build()
+        self.assertEqual(actual_result, expected_result)
+
+    def test_innerjoin_ok(self):
+        expected_result: str = "INNER JOIN TestTable2 TT2 on TT2.TestField22 = TT.TestField2"
+        actual_result: str = InnerJoin(self.table2, self.table2field22, self.table1field2).build()
+        self.assertEqual(actual_result, expected_result)
+
+    def test_innerjoin_unexisting_infered_field(self):
+        expected_err_msg: str = (
+            "No field named 'TestField22' in the table "
+            "Table(name='TestTable', alias='TT', fields=Fields(table='TestTable', "
+            "[Field(name='TestField1', alias='None', table='TestTable'),"
+            "Field(name='TestField2', alias='None', table='TestTable')]))."
+        )
+        with self.assertRaises(NonExistingFieldException) as exc:
+            InnerJoin(self.table2, self.table2field22, self.table1)
+        self.assertEqual(str(exc.exception), expected_err_msg)
+
+    def test_update_ok(self):
+        expected_result: str = "UPDATE TT\nSET TT.TestField1='hello', TT.TestField2='world'"
+        actual_result: str = Update({self.table1field1: "'hello'", self.table1field2: "'world'"}).build()
+        self.assertEqual(actual_result, expected_result)
+
+    def test_different_tables(self):
+        expected_err_msg: str = (
+            "Two different tables cannot be updated in the same Update: 'TestTable' and 'TestTable2'."
+        )
+        with self.assertRaises(IncorrectUpdateException) as exc:
+            Update({self.table1field1: "'hello'", self.table2field21: "'world'"}).build()
+        self.assertEqual(str(exc.exception), expected_err_msg)
+
+    def test_descending(self):
+        anonymous_field: Field = Field("anonymous", self.table1)
+        anonymous_field2: Field = Field("anonymous2", self.table2)
+
+        self.assertEqual(
+            OrderBy(self.table1field1, True).add(anonymous_field2).build(),
+            "ORDER BY TT.TestField1 DESC, TT2.anonymous2",
+        )
+        self.assertEqual(
+            OrderBy(self.table2field21).add(anonymous_field, True).build(),
+            "ORDER BY TT2.TestField21, TT.anonymous DESC",
+        )
+
+
+class TestSelectOptions(TestCase):
+    def setUp(self) -> None:
+        self.table: Table = Table("Customers", "c", field_names=["id", "name"])
+
+    def test_distinct_and_top(self):
+        expected_results: dict[str, str] = {
+            "distinct": "SELECT DISTINCT c.id, c.name",
+            "top": "SELECT TOP (10) c.id, c.name",
+            "both": "SELECT DISTINCT TOP (5) c.id, c.name",
+        }
+        selects: dict[str, Select] = {
+            "distinct": Select(self.table, distinct=True),
+            "top": Select(self.table, top=10),
+            "both": Select(self.table, distinct=True, top=5),
+        }
+        for name, expected_result in expected_results.items():
+            with self.subTest(name=name):
+                self.assertEqual(selects[name].build(), expected_result)
+
+    def test_top_without_fields_and_with_into(self):
+        self.assertEqual(Select(top=3).build(), "SELECT TOP (3) *")
+        select = Select(self.table, top=1)
+        select.to_temptable("first")
+        self.assertEqual(select.build(), "SELECT TOP (1) c.id, c.name\nINTO #first")
+
+    def test_top_zero_is_allowed(self):
+        self.assertEqual(Select(self.table, top=0).build(), "SELECT TOP (0) c.id, c.name")
+
+    def test_invalid_top(self):
+        with self.assertRaises(ValueError) as exc:
+            Select(self.table, top=-1)
+        self.assertEqual(str(exc.exception), "TOP must be zero or more, got -1.")
+        for top in ("10", 2.5, True):
+            with self.subTest(top=top):
+                with self.assertRaises(TypeError) as exc:
+                    Select(self.table, top=top)
+                self.assertEqual(str(exc.exception), f"TOP must be an int, got {type(top).__name__}.")
+
+    def test_repr_shows_options(self):
+        self.assertTrue(repr(Select(self.table, distinct=True, top=2)).endswith(", distinct=True, top=2)"))
+        self.assertTrue(repr(Select(self.table)).endswith("table='Customers')])"))
+
+
+class TestPaging(TestCase):
+    def setUp(self) -> None:
+        self.table: Table = Table("Customers", "c", field_names=["id", "name"])
+
+    def test_offset_and_fetch(self):
+        expected_results: dict[str, str] = {
+            "offset": "ORDER BY c.id\nOFFSET 20 ROWS",
+            "offset and fetch": "ORDER BY c.id DESC\nOFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY",
+            "fetch alone": "ORDER BY c.id\nOFFSET 0 ROWS FETCH NEXT 5 ROWS ONLY",
+        }
+        orderings: dict[str, OrderBy] = {
+            "offset": OrderBy(self.table.fields.id).offset(20),
+            "offset and fetch": OrderBy(self.table.fields.id, True).offset(20).fetch(10),
+            "fetch alone": OrderBy(self.table.fields.id).fetch(5),
+        }
+        for name, expected_result in expected_results.items():
+            with self.subTest(name=name):
+                self.assertEqual(orderings[name].build(), expected_result)
+
+    def test_fields_added_after_paging(self):
+        order_by = OrderBy(self.table.fields.id).offset(1)
+        order_by.add(self.table.fields.name)
+        self.assertEqual(order_by.build(), "ORDER BY c.id, c.name\nOFFSET 1 ROWS")
+
+    def test_invalid_counts(self):
+        with self.assertRaises(ValueError) as exc:
+            OrderBy(self.table.fields.id).offset(-1)
+        self.assertEqual(str(exc.exception), "OFFSET must be zero or more, got -1.")
+        with self.assertRaises(ValueError) as exc:
+            OrderBy(self.table.fields.id).fetch(0)
+        self.assertEqual(str(exc.exception), "FETCH must be at least 1, got 0.")
+        with self.assertRaises(TypeError) as exc:
+            OrderBy(self.table.fields.id).offset("1")
+        self.assertEqual(str(exc.exception), "OFFSET must be an int, got str.")
+
+    def test_paged_query(self):
+        expected_result: str = """SELECT c.id, c.name
+FROM Customers c
+ORDER BY c.name
+OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY"""
+        actual_result: str = QueryBuilder(
+            Select(self.table), From(self.table), OrderBy(self.table.fields.name).offset(40).fetch(20)
+        ).build()
+        self.assertEqual(actual_result, expected_result)
+
+    def test_top_and_paging_are_incompatible(self):
+        order_by = OrderBy(self.table.fields.id)
+        query_builder = QueryBuilder(Select(self.table, top=5), From(self.table), order_by)
+        self.assertEqual(query_builder.build(), "SELECT TOP (5) c.id, c.name\nFROM Customers c\nORDER BY c.id")
+        order_by.fetch(10)  # paging set after the clause was added is still caught
+        with self.assertRaises(IncompatibleClausesException) as exc:
+            query_builder.build()
+        self.assertEqual(str(exc.exception), "TOP cannot be combined with OFFSET/FETCH in the same query.")
+
+    def test_repr_shows_paging(self):
+        self.assertTrue(repr(OrderBy(self.table.fields.id).offset(2).fetch(3)).endswith(", offset=2, fetch=3)"))
+
+
+class TestJoins(TestCase):
+    def setUp(self) -> None:
+        self.customers: Table = Table("Customers", "c", field_names=["id", "name"])
+        self.accounts: Table = Table("Accounts", "a", field_names=["id", "customerId"])
+        self.branches: Table = Table("Branches", field_names=["id"])
+
+    def test_join_keywords(self):
+        expected_results: dict[type, str] = {
+            InnerJoin: "INNER JOIN Accounts a on a.customerId = c.id",
+            LeftJoin: "LEFT JOIN Accounts a on a.customerId = c.id",
+            RightJoin: "RIGHT JOIN Accounts a on a.customerId = c.id",
+            FullJoin: "FULL JOIN Accounts a on a.customerId = c.id",
+        }
+        for join, expected_result in expected_results.items():
+            with self.subTest(join=join.__name__):
+                actual_result: str = join(
+                    self.accounts, self.accounts.fields.customerId, self.customers.fields.id
+                ).build()
+                self.assertEqual(actual_result, expected_result)
+
+    def test_join_infers_the_same_named_field(self):
+        expected_result: str = "LEFT JOIN Accounts a on a.id = c.id"
+        actual_result: str = LeftJoin(self.accounts, self.accounts.fields.id, self.customers).build()
+        self.assertEqual(actual_result, expected_result)
+
+    def test_cross_join(self):
+        self.assertEqual(CrossJoin(self.branches).build(), "CROSS JOIN Branches")
+        self.assertEqual(repr(CrossJoin(self.branches)).split("(")[0], "CrossJoin")
+
+    def test_joins_keep_their_order(self):
+        expected_result: str = """SELECT c.name
+FROM Customers c
+LEFT JOIN Accounts a on a.customerId = c.id
+INNER JOIN Accounts a on a.id = c.id
+CROSS JOIN Branches"""
+        actual_result: str = QueryBuilder(
+            Select(self.customers.fields.name),
+            From(self.customers),
+            LeftJoin(self.accounts, self.accounts.fields.customerId, self.customers.fields.id),
+            InnerJoin(self.accounts, self.accounts.fields.id, self.customers),
+            CrossJoin(self.branches),
+        ).build()
+        self.assertEqual(actual_result, expected_result)

sql_querystring_builder-0.2.0/tests/test_sql_syntax.py

@@ -0,0 +1,93 @@
+"""Every kind of query the library builds must parse as T-SQL (checked with sqlglot, a dev-only dependency).
+
+This catches syntax errors such as the old `SET acc.a AS A=1`. It has blind spots: sqlglot accepts a JOIN
+without ON and a malformed OFFSET, and it does not know which names are in scope, so a SELECT alias used
+in WHERE parses fine. Only a real SQL Server would catch those.
+"""
+
+from unittest import TestCase
+
+import sqlglot
+from sqlglot.errors import ParseError
+
+from sql_querystring_builder import (
+    AliasableString,
+    CrossJoin,
+    From,
+    FullJoin,
+    FunctionOnField,
+    InnerJoin,
+    LeftJoin,
+    OrderBy,
+    QueryBuilder,
+    RightJoin,
+    Select,
+    Table,
+    Update,
+    Where,
+)
+
+
+class TestSqlSyntax(TestCase):
+    def setUp(self) -> None:
+        self.customers: Table = Table("Customers", field_names=["id", "customerId", "mainPhone"])
+        self.accounts: Table = Table("Accounts", "acc", field_names=["id", "customerId", "accountId", "card"])
+        self.branches: Table = Table("Branches", "b", field_names=["id"])
+
+    def build_queries(self) -> dict[str, str]:
+        customers, accounts = self.customers, self.accounts
+        select = Select(customers, accounts.fields.accountId)
+        customers.fields.customerId.set_alias("cid")
+        temp_table = select.to_temptable("a_temp_table")
+        bracketed = Table("dbo.[My Table]", "m", field_names=["x"])
+        # A temp table named from this function's name instead of its alias would hold `#totals.sum of card`,
+        # which does not parse (unlike `#totals.total card`, which reads as a column with an alias).
+        total = FunctionOnField("sum of card", "SUM(", accounts.fields.card, ")", "total_card")
+        totals_table = Select(accounts.fields.id, total).to_temptable("totals")
+        return {
+            "readme flow": QueryBuilder(
+                select,
+                From(customers),
+                InnerJoin(accounts, accounts.fields.customerId, customers),
+                Where(accounts.fields.accountId, "> 20000 AND", customers.fields.customerId, "LIKE 'A1C%'"),
+                OrderBy(customers.fields.customerId, descending=True),
+            ).build(),
+            "temp table": QueryBuilder(Select(temp_table), From(temp_table)).build(),
+            "temp table from a function": QueryBuilder(Select(totals_table), From(totals_table)).build(),
+            "update with join": QueryBuilder(
+                Update({customers.fields.customerId: "'x'"}),  # an aliased field: SET must not write AS cid
+                From(customers),
+                InnerJoin(accounts, accounts.fields.customerId, customers),
+                Where(accounts.fields.id, "= 1"),
+            ).build(),
+            "all join kinds": QueryBuilder(
+                Select(customers.fields.id),
+                From(customers),
+                LeftJoin(accounts, accounts.fields.customerId, customers),
+                RightJoin(self.branches, self.branches.fields.id, accounts.fields.id),
+                FullJoin(accounts, accounts.fields.id, customers),
+                CrossJoin(self.branches),
+            ).build(),
+            "distinct top into": QueryBuilder(Select(customers, distinct=True, top=10), From(customers)).build(),
+            "paging": QueryBuilder(
+                Select(customers), From(customers), OrderBy(customers.fields.id).offset(20).fetch(10)
+            ).build(),
+            "bracketed names": QueryBuilder(
+                Select(bracketed), From(bracketed), Where(bracketed.fields.x, "= 1")
+            ).build(),
+            "functions and strings": QueryBuilder(
+                Select(total, AliasableString("one", "1", "one")), From(accounts), OrderBy(total)
+            ).build(),
+            "select star": QueryBuilder(Select(), From(customers)).build(),
+        }
+
+    def test_known_bad_output_is_rejected(self):
+        # Outputs the library produced before 0.1.0: if these parsed, the test below would prove nothing.
+        for sql in ("UPDATE acc\nSET acc.a AS A=1, acc.b=2", "SELECT #tt.id, #tt.sum of card\nFROM #tt"):
+            with self.subTest(sql=sql), self.assertRaises(ParseError):
+                sqlglot.parse_one(sql, read="tsql")
+
+    def test_generated_queries_parse_as_tsql(self):
+        for name, sql in self.build_queries().items():
+            with self.subTest(name=name):
+                sqlglot.parse_one(sql, read="tsql")  # raises ParseError on invalid syntax

{sql_querystring_builder-0.1.1 → sql_querystring_builder-0.2.0}/tests/test_tables.py

@@ -4,6 +4,7 @@ from sql_querystring_builder.clauses import Select
 from sql_querystring_builder.tables import (
     AliasableString,
     AlreadyExistingFieldException,
+    Field,
     FunctionOnField,
     InvalidNameException,
     NonExistingFieldException,
@@ -111,3 +112,36 @@ class TestTables(TestCase):
 
         expected_result: str = "SELECT testtable.field1, testtable.field2"
         self.assertEqual(select.build(), expected_result)
+
+
+class TestFieldsAccess(TestCase):
+    def setUp(self):
+        self.table: Table = Table("t", field_names=["id", "add", "table"])
+
+    def test_item_access_reaches_shadowed_names(self):
+        self.assertNotIsInstance(self.table.fields.add, Field)  # the attribute is the Fields.add method
+        self.assertIs(self.table.fields["add"], self.table.fields.fields["add"])
+        self.assertEqual(self.table.fields["table"].build(), "t.table")
+
+    def test_missing_item(self):
+        with self.assertRaises(NonExistingFieldException) as exc:
+            _ = self.table.fields["missing"]
+        self.assertEqual(
+            str(exc.exception),
+            "No field named 'missing' in the table Table(name='t', alias='None', fields=Fields(table='t', "
+            "[Field(name='id', alias='None', table='t'),Field(name='add', alias='None', table='t'),"
+            "Field(name='table', alias='None', table='t')])).",
+        )
+
+    def test_membership(self):
+        other_table: Table = Table("u", field_names=["id"])
+        self.assertIn("id", self.table.fields)
+        self.assertNotIn("missing", self.table.fields)
+        self.assertIn(self.table.fields["id"], self.table.fields)
+        self.assertNotIn(other_table.fields["id"], self.table.fields)  # same name, other table
+        self.assertNotIn(42, self.table.fields)
+
+    def test_iteration_and_length(self):
+        self.assertEqual([field.name for field in self.table.fields], ["id", "add", "table"])
+        self.assertEqual(len(self.table.fields), 3)
+        self.assertFalse(Table("empty").fields)  # an empty Fields is falsy now that it has a length

sql_querystring_builder-0.1.1/src/sql_querystring_builder/__init__.py

@@ -1,3 +0,0 @@
-from .clauses import From, InnerJoin, OrderBy, Select, Update, Where
-from .query_builder import QueryBuilder
-from .tables import AliasableString, Field, FunctionOnField, Table, TempTable

sql_querystring_builder-0.1.1/tests/test_clauses.py

@@ -1,74 +0,0 @@
-from unittest import TestCase
-
-from sql_querystring_builder.clauses import IncorrectUpdateException, InnerJoin, OrderBy, Select, Update, Where
-from sql_querystring_builder.tables import Field, NonExistingFieldException, Table, TempTable
-
-
-class TestClauses(TestCase):
-    def setUp(self) -> None:
-        self.maxDiff = None
-
-        self.table1: Table = Table(name="TestTable", alias="TT", field_names=["TestField1", "TestField2"])
-        self.table2: Table = Table(name="TestTable2", alias="TT2", field_names=["TestField21", "TestField22"])
-
-        self.select: Select = Select(self.table1.fields.TestField2, self.table2)
-        self.testtemptable: TempTable = self.select.to_temptable("ttt")
-        self.table1field1: Field = self.table1.fields.TestField1
-        self.table1field2: Field = self.table1.fields.TestField2
-        self.table2field21: Field = self.table2.fields.TestField21
-        self.table2field22: Field = self.table2.fields.TestField22
-
-    def test_init_select(self):
-        self.assertEqual(self.select.fields, [self.table1field2, self.table2field21, self.table2field22])
-
-    def test_select_build(self):
-        expected_result: str = "SELECT TT.TestField1, TT.TestField2, TT2.TestField21"
-        actual_result: str = Select(self.table1, self.table2.fields.TestField21).build()
-        self.assertEqual(actual_result, expected_result)
-
-    def test_from_build(self):
-        expected_result: str = "WHERE TT.TestField2 has a very unique condition"
-        actual_result: str = Where(self.table1field2, "has a very unique condition").build()
-        self.assertEqual(actual_result, expected_result)
-
-    def test_innerjoin_ok(self):
-        expected_result: str = "INNER JOIN TestTable2 TT2 on TT2.TestField22 = TT.TestField2"
-        actual_result: str = InnerJoin(self.table2, self.table2field22, self.table1field2).build()
-        self.assertEqual(actual_result, expected_result)
-
-    def test_innerjoin_unexisting_infered_field(self):
-        expected_err_msg: str = (
-            "No field named 'TestField22' in the table "
-            "Table(name='TestTable', alias='TT', fields=Fields(table='TestTable', "
-            "[Field(name='TestField1', alias='None', table='TestTable'),"
-            "Field(name='TestField2', alias='None', table='TestTable')]))."
-        )
-        with self.assertRaises(NonExistingFieldException) as exc:
-            InnerJoin(self.table2, self.table2field22, self.table1)
-        self.assertEqual(str(exc.exception), expected_err_msg)
-
-    def test_update_ok(self):
-        expected_result: str = "UPDATE TT\nSET TT.TestField1='hello', TT.TestField2='world'"
-        actual_result: str = Update({self.table1field1: "'hello'", self.table1field2: "'world'"}).build()
-        self.assertEqual(actual_result, expected_result)
-
-    def test_different_tables(self):
-        expected_err_msg: str = (
-            "Two different tables cannot be updated in the same Update: 'TestTable' and 'TestTable2'."
-        )
-        with self.assertRaises(IncorrectUpdateException) as exc:
-            Update({self.table1field1: "'hello'", self.table2field21: "'world'"}).build()
-        self.assertEqual(str(exc.exception), expected_err_msg)
-
-    def test_descending(self):
-        anonymous_field: Field = Field("anonymous", self.table1)
-        anonymous_field2: Field = Field("anonymous2", self.table2)
-
-        self.assertEqual(
-            OrderBy(self.table1field1, True).add(anonymous_field2).build(),
-            "ORDER BY TT.TestField1 DESC, TT2.anonymous2",
-        )
-        self.assertEqual(
-            OrderBy(self.table2field21).add(anonymous_field, True).build(),
-            "ORDER BY TT2.TestField21, TT.anonymous DESC",
-        )