t-sql 4.11.0__tar.gz → 4.12.0__tar.gz

{t_sql-4.11.0 → t_sql-4.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 4.11.0
+Version: 4.12.0
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE

{t_sql-4.11.0 → t_sql-4.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "t-sql"
-version = "4.11.0"
+version = "4.12.0"
 description = "Safe SQL. SQL queries for python t-strings (PEP 750)"
 readme = "README.md"
 requires-python = ">=3.14"

{t_sql-4.11.0 → t_sql-4.12.0}/tests/test_query_builder.py

@@ -1,5 +1,5 @@
 import tsql
-from tsql.query_builder import Table, Column, Condition, InsertBuilder, UpdateBuilder, DeleteBuilder
+from tsql.query_builder import Table, Column, Condition, InsertBuilder, UpdateBuilder, DeleteBuilder, SelectQueryBuilder
 
 
 class Users(Table):
@@ -216,6 +216,57 @@ def test_left_join():
     assert 'LEFT JOIN posts ON users.id = posts.user_id' in sql
 
 
+def test_join_raw_template():
+    """join_raw() splices a raw t-string Template verbatim as a whole JOIN clause."""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+             .select(t't.*')
+             .join_raw(t'LEFT JOIN other o ON o.id = t.ref'))
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM dataset.records AS t LEFT JOIN other o ON o.id = t.ref'
+    assert params == []
+
+
+def test_join_raw_lateral_no_on():
+    """join_raw() handles join shapes the typed path can't: LATERAL, no ON."""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+             .select(t't.*')
+             .join_raw(t'CROSS JOIN LATERAL unnest(t.tags) AS tag'))
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM dataset.records AS t CROSS JOIN LATERAL unnest(t.tags) AS tag'
+    assert params == []
+
+
+def test_join_raw_template_carries_params():
+    """A parameterized raw join Template renumbers correctly in context."""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+             .select(t't.*')
+             .join_raw(t'LEFT JOIN other o ON o.id = t.ref AND o.kind = {"x"}')
+             .where(t't.active = {True}'))
+    sql, params = query.render(style=tsql.styles.NUMERIC_DOLLAR)
+
+    assert sql == (
+        'SELECT t.* FROM dataset.records AS t '
+        'LEFT JOIN other o ON o.id = t.ref AND o.kind = $1 '
+        'WHERE (t.active = $2)'
+    )
+    assert params == ['x', True]
+
+
+def test_join_raw_and_typed_mixed():
+    """Raw and typed joins compose in insertion order."""
+    query = (Posts.select(Posts.ALL)
+             .join(Users, Posts.user_id == Users.id)
+             .join_raw(t'LEFT JOIN tags tg ON tg.post_id = posts.id'))
+    sql, params = query.render()
+
+    assert 'INNER JOIN users ON posts.user_id = users.id' in sql
+    assert 'LEFT JOIN tags tg ON tg.post_id = posts.id' in sql
+    # typed join comes first (added first), raw second
+    assert sql.index('INNER JOIN users') < sql.index('LEFT JOIN tags')
+
+
 def test_order_by():
     """Test ORDER BY clause"""
     query = Users.select().order_by(Users.username)
@@ -1624,3 +1675,207 @@ def test_delete_where_with_bare_boolean_column():
     assert 'DELETE FROM contacts' in sql
     assert 'WHERE contacts.is_primary' in sql
     assert params == []
+
+
+# --------------------------------------------------------------------------- #
+# DISTINCT ON
+# --------------------------------------------------------------------------- #
+
+
+def test_distinct_on_string_column():
+    """distinct_on() with a string column emits SELECT DISTINCT ON (col)"""
+    query = Users.select(Users.id, Users.username).distinct_on('username')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (username) users.id, users.username FROM users'
+    assert params == []
+
+
+def test_distinct_on_multiple_columns():
+    """distinct_on() accepts multiple columns, comma-joined inside the parens"""
+    query = Users.select(Users.id).distinct_on('username', 'email')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (username, email) users.id FROM users'
+    assert params == []
+
+
+def test_distinct_on_column_object():
+    """distinct_on() accepts Column objects, coerced like select()"""
+    query = Users.select(Users.id).distinct_on(Users.username)
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (users.username) users.id FROM users'
+    assert params == []
+
+
+def test_distinct_on_template_fragment():
+    """distinct_on() accepts raw t-string fragments (the field-type seam)"""
+    query = Users.select(Users.id).distinct_on(t'users.username')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (users.username) users.id FROM users'
+    assert params == []
+
+
+def test_distinct_on_select_star():
+    """distinct_on() works with SELECT * (no explicit columns)"""
+    query = Users.select().distinct_on('username')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (username) * FROM users'
+    assert params == []
+
+
+def test_no_distinct_on_unaffected():
+    """A query without distinct_on() is unchanged"""
+    query = Users.select(Users.id)
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users'
+    assert params == []
+
+
+# --------------------------------------------------------------------------- #
+# FROM ONLY  (Postgres table inheritance)
+# --------------------------------------------------------------------------- #
+
+
+def test_from_only_flag():
+    """from_table(only=True) makes the builder emit FROM ONLY {table}"""
+    query = SelectQueryBuilder.from_table('users', only=True).select('id')
+    sql, params = query.render()
+
+    assert sql == 'SELECT id FROM ONLY users'
+    assert params == []
+
+
+def test_from_only_with_schema():
+    """FROM ONLY respects the schema-qualified table name"""
+    query = SelectQueryBuilder.from_table('records', schema='dataset', only=True)
+    sql, params = query.render()
+
+    assert sql == 'SELECT * FROM ONLY dataset.records'
+    assert params == []
+
+
+def test_from_only_default_off():
+    """Without only=True, FROM is unchanged (no ONLY keyword)"""
+    query = SelectQueryBuilder.from_table('users').select('id')
+    sql, params = query.render()
+
+    assert 'FROM ONLY' not in sql
+    assert 'FROM users' in sql
+
+
+def test_distinct_on_and_from_only_together():
+    """DISTINCT ON and FROM ONLY compose"""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', only=True)
+             .select(t't.*')
+             .distinct_on('t.id'))
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (t.id) t.* FROM ONLY dataset.records'
+    assert params == []
+
+
+# --------------------------------------------------------------------------- #
+# FROM table alias
+# --------------------------------------------------------------------------- #
+
+
+def test_from_table_alias():
+    """from_table(alias=...) emits FROM {table} AS {alias}"""
+    query = SelectQueryBuilder.from_table('records', schema='dataset', alias='t').select(t't.*')
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM dataset.records AS t'
+    assert params == []
+
+
+def test_from_table_alias_and_only():
+    """alias and only compose: FROM ONLY {table} AS {alias}"""
+    query = SelectQueryBuilder.from_table('records', schema='dataset', alias='t', only=True).select(
+        t't.*'
+    )
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM ONLY dataset.records AS t'
+    assert params == []
+
+
+def test_from_table_alias_default_none():
+    """Without alias, no AS clause is emitted"""
+    query = SelectQueryBuilder.from_table('users')
+    sql, params = query.render()
+
+    assert ' AS ' not in sql
+    assert sql == 'SELECT * FROM users'
+
+
+def test_from_table_alias_rejects_injection():
+    """alias goes through :literal and rejects a non-identifier"""
+    import pytest
+
+    query = SelectQueryBuilder.from_table('users', alias='t; DROP TABLE x')
+    with pytest.raises(ValueError):
+        query.render()
+
+
+# --------------------------------------------------------------------------- #
+# Template-aware ORDER BY / GROUP BY  (parity with where/having/select)
+# --------------------------------------------------------------------------- #
+
+
+def test_order_by_template_fragment():
+    """order_by() accepts a raw t-string fragment, emitted verbatim (no added direction)."""
+    query = Users.select(Users.id).order_by(t'lower(users.username) DESC NULLS LAST')
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users ORDER BY lower(users.username) DESC NULLS LAST'
+    assert params == []
+
+
+def test_order_by_template_carries_params():
+    """A parameterized ORDER BY fragment renumbers correctly in context."""
+    query = (Users.select(Users.id)
+             .where(Users.id > 5)
+             .order_by(t'(users.username = {"vip"}) DESC'))
+    sql, params = query.render(style=tsql.styles.NUMERIC_DOLLAR)
+
+    assert sql == 'SELECT users.id FROM users WHERE users.id > $1 ORDER BY (users.username = $2) DESC'
+    assert params == [5, 'vip']
+
+
+def test_order_by_mixed_template_and_column():
+    """Template fragments and Column/str order_by entries compose in order."""
+    query = (Users.select(Users.id)
+             .order_by(t'lower(users.username) ASC')
+             .order_by(Users.id.desc()))
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users ORDER BY lower(users.username) ASC, users.id DESC'
+    assert params == []
+
+
+def test_group_by_template_fragment():
+    """group_by() accepts a raw t-string fragment, emitted verbatim."""
+    query = Users.select(t'date_trunc({"day":unsafe}, users.created_at)').group_by(
+        t'date_trunc(day, users.created_at)'
+    )
+    sql, params = query.render()
+
+    assert sql == (
+        'SELECT date_trunc(day, users.created_at) FROM users '
+        'GROUP BY date_trunc(day, users.created_at)'
+    )
+    assert params == []
+
+
+def test_group_by_mixed_template_and_column():
+    """Template fragments and Column/str group_by entries compose in order."""
+    query = Users.select(Users.id).group_by(Users.id).group_by(t'lower(users.email)')
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users GROUP BY users.id, lower(users.email)'
+    assert params == []

{t_sql-4.11.0 → t_sql-4.12.0}/tsql/query_builder.py

@@ -614,10 +614,11 @@ class QueryBuilder(ABC):
                     result_key = col.alias if col.alias else col.column_name
                     processors[result_key] = col.type_processor
         else:
-            # SELECT * - check all tables involved (base table + joins)
+            # SELECT * - check all tables involved (base table + joins).
+            # Raw-Template joins carry no introspectable table, so skip them.
             tables = [self.base_table]
             if hasattr(self, '_joins'):
-                tables.extend(join.table for join in self._joins)
+                tables.extend(join.table for join in self._joins if not isinstance(join, Template))
 
             for table in tables:
                 processors.update(table._type_processors)
@@ -1166,32 +1167,48 @@ class SelectQueryBuilder(QueryBuilder):
         self.base_table = base_table
         self._columns: Optional[List[Union[Column, str]]] = None
         self._conditions: List[Union[Condition, Template]] = []
-        self._joins: List[Join] = []
-        self._group_by_columns: List[Union[Column, str]] = []
+        self._joins: List[Union[Join, Template]] = []
+        self._group_by_columns: List[Union[Column, Template, str]] = []
         self._having_conditions: List[Union[Condition, Template]] = []
-        self._order_by_columns: List[tuple[Union[Column, str], str]] = []
+        self._order_by_columns: List[tuple[Union[Column, Template, str], str]] = []
         self._limit_value: Optional[int] = None
         self._offset_value: Optional[int] = None
         self._ctes: List[tuple[str, Union[Template, TSQL, 'SelectQueryBuilder'], bool]] = []
+        self._distinct_on_columns: List[Union[Column, Template, str]] = []
+        self._only: bool = False
+        self._alias: Optional[str] = None
 
     @classmethod
-    def from_table(cls, table_name: str, schema: Optional[str] = None) -> 'SelectQueryBuilder':
+    def from_table(
+        cls,
+        table_name: str,
+        schema: Optional[str] = None,
+        *,
+        only: bool = False,
+        alias: Optional[str] = None,
+    ) -> 'SelectQueryBuilder':
         """Create a SelectQueryBuilder from a string table name.
 
         Args:
             table_name: Name of the table
             schema: Optional schema name
+            only: Emit ``FROM ONLY {table}`` to exclude inheriting child tables (PostgreSQL)
+            alias: Optional FROM-clause alias, emitted as ``FROM {table} AS {alias}``
+                (validated as an identifier)
 
         Returns:
             SelectQueryBuilder instance
 
         Example:
-            SelectQueryBuilder.from_table('users', schema='public') \\
-                .select('id', 'name') \\
-                .where(t'status = {status}')
+            SelectQueryBuilder.from_table('users', schema='public', alias='u') \\
+                .select('u.id', 'u.name') \\
+                .where(t'u.status = {status}')
         """
         string_table = _StringTable(table_name, schema)
-        return cls(string_table)
+        builder = cls(string_table)
+        builder._only = only
+        builder._alias = alias
+        return builder
 
     def select(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
         """Specify columns to select
@@ -1221,6 +1238,20 @@ class SelectQueryBuilder(QueryBuilder):
             self._columns = None
         return self
 
+    def distinct_on(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
+        """Add a DISTINCT ON (...) clause (PostgreSQL).
+
+        Args:
+            columns: Column objects, raw t-string Templates, or string column names,
+                coerced exactly like select().
+
+        Example:
+            SelectQueryBuilder.from_table('events').distinct_on('user_id')
+            # SELECT DISTINCT ON (user_id) * FROM events
+        """
+        self._distinct_on_columns.extend(columns)
+        return self
+
     def where(self, condition: Union[Condition, Template, Column]) -> 'SelectQueryBuilder':
         """Add a WHERE condition (multiple calls are ANDed together)
 
@@ -1234,6 +1265,23 @@ class SelectQueryBuilder(QueryBuilder):
         self._joins.append(Join(table, on, join_type))
         return self
 
+    def join_raw(self, clause: Template) -> 'SelectQueryBuilder':
+        """Splice a raw t-string Template as a complete JOIN clause, verbatim.
+
+        The Template must carry the *whole* clause including the join keyword, e.g.
+        ``t'LEFT JOIN LATERAL (SELECT ...) x ON TRUE'`` or
+        ``t'CROSS JOIN LATERAL unnest({col}) AS y'``. Unlike join(), nothing is added
+        around it — no join type, no ON.
+
+        NOT ADVISED: this is an escape hatch for join shapes the typed join() can't
+        express (LATERAL subqueries, ON-less cross joins, correlated set-returning
+        functions). It bypasses every safety/structure the builder provides. Prefer
+        join()/left_join()/right_join() with a Table + Condition. This method may be
+        removed if those typed paths grow to cover the remaining cases.
+        """
+        self._joins.append(clause)
+        return self
+
     def left_join(self, table: type['Table'], on: Condition) -> 'SelectQueryBuilder':
         """Add a LEFT JOIN clause"""
         return self.join(table, on, 'LEFT')
@@ -1242,11 +1290,13 @@ class SelectQueryBuilder(QueryBuilder):
         """Add a RIGHT JOIN clause"""
         return self.join(table, on, 'RIGHT')
 
-    def order_by(self, *columns: Union[Column, OrderByClause, str], direction: str = 'ASC') -> 'SelectQueryBuilder':
+    def order_by(self, *columns: Union[Column, OrderByClause, Template, str], direction: str = 'ASC') -> 'SelectQueryBuilder':
         """Add ORDER BY clause
 
         Args:
-            columns: Column objects, OrderByClause objects (from .asc()/.desc()), or string column names
+            columns: Column objects, OrderByClause objects (from .asc()/.desc()), raw
+                t-string Templates (emitted verbatim — bake the direction in yourself),
+                or string column names
             direction: Sort direction ('ASC' or 'DESC') for columns that don't have explicit direction
 
         Examples:
@@ -1270,15 +1320,19 @@ class SelectQueryBuilder(QueryBuilder):
                 self._order_by_columns.append((column, direction.upper()))
         return self
 
-    def group_by(self, *columns: Union[Column, str]) -> 'SelectQueryBuilder':
+    def group_by(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
         """Add GROUP BY clause
 
         Args:
-            columns: Column objects or string column names
+            columns: Column objects, raw t-string Templates (emitted verbatim), or
+                string column names
 
         Examples:
             # String-based GROUP BY
             SelectQueryBuilder.from_table('orders').select('user_id', 'COUNT(*)').group_by('user_id')
+
+            # Raw expression via t-string
+            Orders.select().group_by(t'date_trunc({"day":unsafe}, orders.created_at)')
         """
         self._group_by_columns.extend(columns)
         return self
@@ -1350,6 +1404,18 @@ class SelectQueryBuilder(QueryBuilder):
         self._ctes.append((name, query, recursive))
         return self
 
+    @staticmethod
+    def _coerce_column(col: Union['Column', Template, str]) -> Template:
+        """Coerce a SELECT/DISTINCT ON column into a t-string fragment."""
+        if isinstance(col, Template):
+            return col
+        elif isinstance(col, str):
+            # String column name, use :literal for validation
+            return t'{col:literal}'
+        else:
+            # Column object, convert to string
+            return t'{str(col):unsafe}'
+
     def to_tsql(self) -> TSQL:
         """Build the final TSQL object"""
         parts: List[Template] = []
@@ -1380,32 +1446,32 @@ class SelectQueryBuilder(QueryBuilder):
             else:
                 parts.append(t'WITH {cte_clause}')
 
-        if self._columns:
-            # Build column list, handling Column objects, Template (t-string) objects, and strings
-            column_parts = []
-            for col in self._columns:
-                if isinstance(col, Template):
-                    column_parts.append(col)
-                elif isinstance(col, str):
-                    # String column name, use :literal for validation
-                    column_parts.append(t'{col:literal}')
-                else:
-                    # Column object, convert to string
-                    column_parts.append(t'{str(col):unsafe}')
+        # DISTINCT ON (...) clause, coercing columns exactly like the SELECT list
+        if self._distinct_on_columns:
+            distinct_on_template = t_join(t', ', [self._coerce_column(c) for c in self._distinct_on_columns])
+            distinct_clause = t'DISTINCT ON ({distinct_on_template}) '
+        else:
+            distinct_clause = t''
 
+        if self._columns:
+            column_parts = [self._coerce_column(col) for col in self._columns]
             columns_template = t_join(t', ', column_parts)
-            parts.append(t'SELECT {columns_template}')
+            parts.append(t'SELECT {distinct_clause}{columns_template}')
         else:
-            parts.append(t'SELECT *')
+            parts.append(t'SELECT {distinct_clause}*')
 
         if self.base_table.schema:
             table_name = f"{self.base_table.schema}.{self.base_table.table_name}"
         else:
             table_name = self.base_table.table_name
-        parts.append(t'FROM {table_name:literal}')
+        only_kw = t'ONLY ' if self._only else t''
+        if self._alias is not None:
+            parts.append(t'FROM {only_kw}{table_name:literal} AS {self._alias:literal}')
+        else:
+            parts.append(t'FROM {only_kw}{table_name:literal}')
 
         for join in self._joins:
-            parts.append(join.to_tsql())
+            parts.append(join if isinstance(join, Template) else join.to_tsql())
 
         if self._conditions:
             where_parts = []
@@ -1423,7 +1489,9 @@ class SelectQueryBuilder(QueryBuilder):
         if self._group_by_columns:
             group_by_parts = []
             for col in self._group_by_columns:
-                if isinstance(col, str):
+                if isinstance(col, Template):
+                    group_by_parts.append(col)
+                elif isinstance(col, str):
                     group_by_parts.append(t'{col:literal}')
                 else:
                     col_str = str(col)
@@ -1444,7 +1512,10 @@ class SelectQueryBuilder(QueryBuilder):
         if self._order_by_columns:
             order_parts = []
             for col, direction in self._order_by_columns:
-                if isinstance(col, str):
+                if isinstance(col, Template):
+                    # Raw fragment is self-contained (direction baked in); emit verbatim
+                    order_parts.append(col)
+                elif isinstance(col, str):
                     # String column name - validate with :literal
                     order_parts.append(t'{col:literal} {direction:unsafe}')
                 else: