sql_querystring_builder 0.1.0__tar.gz → 0.2.0__tar.gz

{sql_querystring_builder-0.1.0 → sql_querystring_builder-0.2.0}/PKG-INFO

@@ -1,12 +1,19 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.1.0
+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
 Keywords: sql,query,string
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -24,25 +31,27 @@ 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)
-- [ ] Insert
-- [ ] Compound (sub-)queries
-- [ ] Functions
-- [ ] Proper Conditions
+In planned order:
+- [ ] Proper conditions: typed values, AND/OR/NOT, IN, BETWEEN, LIKE, IS NULL
+- [ ] Insert and Delete
+- [ ] Functions (aggregates and others), GROUP BY, HAVING, CASE
+- [ ] Compound queries (UNION, INTERSECT, EXCEPT) and sub-queries
+- [ ] Parameterized queries
 
 ## What it does not do
     Connect to a database server and run the queries by itself.
-    It gives you the query as a string, it's then up to yopu to pass it to a SQL engine.
+    It gives you the query as a string, it's then up to you to pass it to a SQL engine.
 
 ## Example
 1. Define the elements of your query:
@@ -55,7 +64,7 @@ accounts_table = Table("Accounts", "acc").add("id", "customerId", "accountId")
 select = Select(customers_table, accounts_table.fields.accountId)
 # Sets an alias for an existing field
 customers_table.fields.customerId.set_alias("cid")
-# Specifies the table to takes as a FROM
+# Specifies the table to take as a FROM
 from_ = From(customers_table)
 # Specifies a temporary table for the select
 atemptable = select.to_temptable("a_temp_table")
@@ -64,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:
 ```
@@ -87,10 +96,10 @@ 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 which components are inferred:
+4. Manipulate temporary tables whose components are inferred:
 ```
 # Is able to infer fields from temporary tables and use it as with a regular table.
 temp_select = Select(atemptable)
@@ -118,6 +127,30 @@ 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.
+- PyPI classifiers for the supported Python versions (3.10 to 3.14), typing and topic.
+- The "Not implemented (yet)" list shows the planned features in order; typo fixes.
+
 ### 0.1.0
 This release changes the generated SQL: check your queries when upgrading.
 - WHERE conditions and the right side of `INNER JOIN ... on` use the field's qualified name (`t1.KeyId`)

sql_querystring_builder-0.1.0/src/sql_querystring_builder.egg-info/PKG-INFO → sql_querystring_builder-0.2.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: sql_querystring_builder
-Version: 0.1.0
-Summary: Wraps string building of MS SQL queries
-Author-email: Wael GRIBAA <g.wael@outlook.fr>
-License-Expression: GPL-3.0-only
-Keywords: sql,query,string
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
 # SqlQueryBuilder
 Wraps string building of MS SQL queries.
 It provides first level validation.
@@ -24,25 +10,27 @@ 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)
-- [ ] Insert
-- [ ] Compound (sub-)queries
-- [ ] Functions
-- [ ] Proper Conditions
+In planned order:
+- [ ] Proper conditions: typed values, AND/OR/NOT, IN, BETWEEN, LIKE, IS NULL
+- [ ] Insert and Delete
+- [ ] Functions (aggregates and others), GROUP BY, HAVING, CASE
+- [ ] Compound queries (UNION, INTERSECT, EXCEPT) and sub-queries
+- [ ] Parameterized queries
 
 ## What it does not do
     Connect to a database server and run the queries by itself.
-    It gives you the query as a string, it's then up to yopu to pass it to a SQL engine.
+    It gives you the query as a string, it's then up to you to pass it to a SQL engine.
 
 ## Example
 1. Define the elements of your query:
@@ -55,7 +43,7 @@ accounts_table = Table("Accounts", "acc").add("id", "customerId", "accountId")
 select = Select(customers_table, accounts_table.fields.accountId)
 # Sets an alias for an existing field
 customers_table.fields.customerId.set_alias("cid")
-# Specifies the table to takes as a FROM
+# Specifies the table to take as a FROM
 from_ = From(customers_table)
 # Specifies a temporary table for the select
 atemptable = select.to_temptable("a_temp_table")
@@ -64,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:
 ```
@@ -87,10 +75,10 @@ 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 which components are inferred:
+4. Manipulate temporary tables whose components are inferred:
 ```
 # Is able to infer fields from temporary tables and use it as with a regular table.
 temp_select = Select(atemptable)
@@ -118,6 +106,30 @@ 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.
+- PyPI classifiers for the supported Python versions (3.10 to 3.14), typing and topic.
+- The "Not implemented (yet)" list shows the planned features in order; typo fixes.
+
 ### 0.1.0
 This release changes the generated SQL: check your queries when upgrading.
 - WHERE conditions and the right side of `INNER JOIN ... on` use the field's qualified name (`t1.KeyId`)
@@ -136,4 +148,4 @@ This release changes the generated SQL: check your queries when upgrading.
 ## Authors
 Wael GRIBAA
 Contact: g.wael@outlook.fr
-Made in September 2024
+Made in September 2024

{sql_querystring_builder-0.1.0 → 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.0"
+version = "0.2.0"
 authors = [
   { name="Wael GRIBAA", email="g.wael@outlook.fr" },
 ]
@@ -15,7 +15,14 @@ license = "GPL-3.0-only"
 license-files = ["LICENSE"]
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Operating System :: OS Independent"
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Database",
+    "Typing :: Typed",
 ]
 keywords = ["sql", "query", "string"]
 
@@ -27,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.0 → 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.0 → 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: