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

sql_querystring_builder/__init__.py

@@ -1,9 +1,11 @@
 from .clauses import (
     CrossJoin,
+    Delete,
     From,
     FullJoin,
     IncorrectUpdateException,
     InnerJoin,
+    Insert,
     LeftJoin,
     OrderBy,
     RightJoin,

sql_querystring_builder/clauses.py

@@ -1,18 +1,23 @@
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 
 from .abstract_clause import Clause
-from .conditions import Condition, Junction, check_operand, render_operand
+from .conditions import Comparable, Condition, Junction, check_operand, render_operand
 from .exceptions import SqlQueryBuilderError
 from .tables import Aliasable, Field, Fields, Table, TempTable
+from .values import render_value
 
 
 class IncorrectUpdateException(SqlQueryBuilderError):
     pass
 
 
-# TODO  Add INSERT
+def _insert_value(value: object) -> object:
+    # VALUES cannot read columns: unlike in a condition, a field or expression is no value here.
+    if isinstance(value, Comparable):
+        raise TypeError(f"Unsupported value type: {type(value).__name__}.")
+    return check_operand(value)
 
 
 def _row_count(keyword: str, value: int, minimum: int) -> int:
@@ -228,6 +233,93 @@ class Update(Clause):
         return f"{self.__class__.__name__}(updates={self.updates})"
 
 
+class Insert(Clause):
+    """`INSERT INTO table (columns)` and `VALUES (…), (…)`, with the rows added by `values()`.
+
+    The columns are fields of one table, or whole tables, as `Select` takes them. Unlike in `Update`, a plain
+    str is a value here. An Insert stands alone in its query (see `QueryBuilder.build()`).
+    """
+
+    def __init__(self, *columns: Field | Table) -> None:
+        tables: list[Table] = []
+        self.columns: list[Field] = []
+        for column in columns:
+            if isinstance(column, Table):
+                tables.append(column)
+                self.columns.extend(column.fields.as_list())
+            elif isinstance(column, Field):
+                tables.append(column.table)
+                self.columns.append(column)
+            else:
+                raise TypeError(f"Insert takes fields or tables, got {type(column).__name__}.")
+        if not self.columns:
+            raise ValueError("Insert needs at least one column.")
+        for table in tables[1:]:
+            if table.name != tables[0].name:
+                raise ValueError(f"Insert columns must come from one table, got '{tables[0].name}' and '{table.name}'.")
+        names: set[str] = set()
+        for column in self.columns:
+            if column.name in names:
+                raise ValueError(f"Insert column '{column.name}' appears twice.")
+            names.add(column.name)
+        self.table: Table = tables[0]
+        self.rows: list[tuple[object, ...]] = []
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def values(self, *rows: Sequence[object]) -> Insert:
+        """Adds rows, each a tuple or list of values in column order, and returns the Insert."""
+        if len(self.rows) + len(rows) > 1000:
+            raise ValueError(f"An INSERT takes at most 1000 rows, got {len(self.rows) + len(rows)}.")
+        checked: list[tuple[object, ...]] = []
+        expected: str = f"{len(self.columns)} value{'s' if len(self.columns) > 1 else ''}"
+        for number, row in enumerate(rows, start=len(self.rows) + 1):
+            if isinstance(row, (str, bytes)) or not isinstance(row, Sequence):
+                raise TypeError(f"An Insert row must be a tuple or list of values, got {type(row).__name__}.")
+            if len(row) != len(self.columns):
+                raise ValueError(f"Insert row {number} needs {expected}, got {len(row)}.")
+            checked.append(tuple(_insert_value(value) for value in row))
+        self.rows.extend(checked)
+        return self
+
+    def build(self) -> str:
+        if not self.rows:
+            raise ValueError("The Insert has no rows: add them with values().")
+        # T-SQL refuses an alias after INSERT INTO, and qualified column names.
+        columns: str = ", ".join(column.name for column in self.columns)
+        rows: str = ", ".join(f"({', '.join(render_value(value) for value in row)})" for row in self.rows)
+        return f"INSERT INTO {self.table.name} ({columns})\nVALUES {rows}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(columns={self.columns}, rows={len(self.rows)})"
+
+
+class Delete(Clause):
+    """`DELETE` and the table's alias, or its name; T-SQL reads an alias from `From(table)`, as for `Update`.
+
+    A query with a Delete needs a Where unless `where_required=False`: an empty filter would delete every row.
+    """
+
+    def __init__(self, table: Table, *, where_required: bool = True) -> None:
+        if not isinstance(table, Table):
+            raise TypeError(f"Delete takes a Table, got {type(table).__name__}.")
+        self.table: Table = table
+        self.where_required: bool = where_required
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def build(self) -> str:
+        return f"DELETE {self.table.build(use_name=False, use_alias=True)}"
+
+    def __repr__(self) -> str:
+        option: str = "" if self.where_required else ", where_required=False"
+        return f"{self.__class__.__name__}(table={self.table}{option})"
+
+
 class OrderBy(Clause):
     def __init__(self, field: Aliasable, descending: bool = False) -> None:
         self.ordering: list[tuple[Aliasable, bool]] = [(field, descending)]

sql_querystring_builder/query_builder.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.3.0
+Version: 0.4.0
 Summary: Wraps string building of MS SQL queries
 Author-email: Wael GRIBAA <g.wael@outlook.fr>
 License-Expression: GPL-3.0-only
@@ -35,6 +35,8 @@ It provides first level validation.
 2. Using:
     - [x] Select (with DISTINCT and TOP)
     - [x] Update (with typed values)
+    - [x] Insert (multi-row VALUES)
+    - [x] Delete (with joins; refused without a WHERE unless asked)
     - [x] From
     - [x] InnerJoin, LeftJoin, RightJoin, FullJoin (on two fields or on any condition), CrossJoin
     - [x] Where (with conditions)
@@ -47,7 +49,6 @@ It provides first level validation.
 
 ## Not implemented (yet)
 In planned order:
-- [ ] Insert and Delete
 - [ ] Functions (aggregates and others), GROUP BY, HAVING, CASE
 - [ ] Compound queries (UNION, INTERSECT, EXCEPT) and sub-queries
 
@@ -134,6 +135,23 @@ print(params)
 # > (20000, 'A1C%')
 # With pyodbc: cursor.execute(sql, params). For pymssql, build_with_params("format") writes %s instead.
 ```
+6. Insert and delete rows:
+```
+# Inserts rows: one tuple per row, with the values in column order
+insert = Insert(customers_table.fields.customerId, customers_table.fields.mainPhone).values(
+    ("A1C42", "555-0100"), ("B7", None)
+)
+print(QueryBuilder(insert).build())
+# > INSERT INTO Customers (customerId, mainPhone)
+# > VALUES ('A1C42', '555-0100'), ('B7', NULL)
+
+# Deletes the accounts of customer B7; a DELETE needs a WHERE, unless built with where_required=False
+delete = QueryBuilder(Delete(accounts_table), From(accounts_table), Where(accounts_table.fields.customerId.eq("B7")))
+print(delete.build())
+# > DELETE acc
+# > FROM Accounts acc
+# > WHERE acc.customerId = 'B7'
+```
 
 (Find it directly in the module example.py)
 
@@ -144,6 +162,19 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 0.4.0
+Queries built with 0.3.0 produce the same SQL.
+- `Insert(*columns).values(*rows)` renders `INSERT INTO Customers (id, name)` and
+  `VALUES (1, 'Ann'), (2, 'O''Brien')`. The columns are fields of one table, or a whole table. Each row is a
+  tuple of values in column order, with at most 1000 rows per INSERT, as in T-SQL. Values are escaped as in
+  conditions, plain strings included, and `Raw("DEFAULT")` writes SQL. An Insert stands alone in its query.
+- `Delete(table)` renders `DELETE` and the table's alias, or its name, and works with `From`, joins and
+  `Where`: `DELETE acc FROM Accounts acc INNER JOIN ...`. A query with a DELETE but no WHERE raises
+  `IncompatibleClausesException`, unless written `Delete(table, where_required=False)`; so does a DELETE with
+  ORDER BY.
+- Both work with `build_with_params()`. SQL Server accepts about 2,100 parameters per query, so split big
+  parameterized inserts.
+
 ### 0.3.0
 Queries built with 0.2.0 produce the same SQL, except for the fixed `Update` values below.
 - Conditions are methods of fields, functions on fields and strings: `eq`, `ne`, `lt`, `le`, `gt`, `ge`,

{sql_querystring_builder-0.3.0.dist-info → sql_querystring_builder-0.4.0.dist-info}/RECORD

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