t-sql 4.5.2__tar.gz → 4.6.0__tar.gz

t_sql-4.5.2/README.md → t_sql-4.6.0/PKG-INFO

@@ -1,3 +1,13 @@
+Metadata-Version: 2.4
+Name: t-sql
+Version: 4.6.0
+Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
+Project-URL: Homepage, https://github.com/nhumrich/t-sql
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: alembic>=1.17.0
+Description-Content-Type: text/markdown
+
 # t-sql
 
 A lightweight SQL templating library that leverages Python 3.14's t-strings (PEP 750).
@@ -436,6 +446,42 @@ The query builder is database-agnostic - all methods are available regardless of
 
 If you use an unsupported method, your database will raise a syntax error when you execute the query.
 
+## String-Based Query Builder
+
+t-sql also supports building queries with string table/column names instead of Table class definitions:
+
+```python
+from tsql.query_builder import SelectQueryBuilder, InsertBuilder, UpdateBuilder, DeleteBuilder
+
+# SELECT
+user_id = 123
+status = 'active'
+query = SelectQueryBuilder.from_table('users', schema='public') \
+    .select('id', 'name', 'email') \
+    .where(t'id = {user_id} AND status = {status}') \
+    .order_by('created_at', direction='DESC') \
+    .limit(10)
+
+sql, params = query.render()
+
+# INSERT
+query = InsertBuilder.into_table('users', {'name': 'Bob', 'email': 'bob@test.com'}) \
+    .on_conflict_do_nothing('email') \
+    .returning('id')
+
+# UPDATE
+cutoff_date = '2024-01-01'
+query = UpdateBuilder.table('users', {'status': 'inactive'}) \
+    .where(t'last_login < {cutoff_date}')
+
+# DELETE
+cutoff = '2023-01-01'
+query = DeleteBuilder.from_table('users') \
+    .where(t'created_at < {cutoff}')
+```
+
+String identifiers are validated using the same `:literal` format spec as the core library, providing the same SQL injection protection.
+
 ## Mixing Query Builder with T-Strings
 
 You can combine the query builder with raw t-strings for complex logic:

t_sql-4.5.2/PKG-INFO → t_sql-4.6.0/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.4
-Name: t-sql
-Version: 4.5.2
-Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
-Project-URL: Homepage, https://github.com/nhumrich/t-sql
-License-File: LICENSE
-Requires-Python: >=3.14
-Requires-Dist: alembic>=1.17.0
-Description-Content-Type: text/markdown
-
 # t-sql
 
 A lightweight SQL templating library that leverages Python 3.14's t-strings (PEP 750).
@@ -446,6 +436,42 @@ The query builder is database-agnostic - all methods are available regardless of
 
 If you use an unsupported method, your database will raise a syntax error when you execute the query.
 
+## String-Based Query Builder
+
+t-sql also supports building queries with string table/column names instead of Table class definitions:
+
+```python
+from tsql.query_builder import SelectQueryBuilder, InsertBuilder, UpdateBuilder, DeleteBuilder
+
+# SELECT
+user_id = 123
+status = 'active'
+query = SelectQueryBuilder.from_table('users', schema='public') \
+    .select('id', 'name', 'email') \
+    .where(t'id = {user_id} AND status = {status}') \
+    .order_by('created_at', direction='DESC') \
+    .limit(10)
+
+sql, params = query.render()
+
+# INSERT
+query = InsertBuilder.into_table('users', {'name': 'Bob', 'email': 'bob@test.com'}) \
+    .on_conflict_do_nothing('email') \
+    .returning('id')
+
+# UPDATE
+cutoff_date = '2024-01-01'
+query = UpdateBuilder.table('users', {'status': 'inactive'}) \
+    .where(t'last_login < {cutoff_date}')
+
+# DELETE
+cutoff = '2023-01-01'
+query = DeleteBuilder.from_table('users') \
+    .where(t'created_at < {cutoff}')
+```
+
+String identifiers are validated using the same `:literal` format spec as the core library, providing the same SQL injection protection.
+
 ## Mixing Query Builder with T-Strings
 
 You can combine the query builder with raw t-strings for complex logic:

{t_sql-4.5.2 → t_sql-4.6.0}/pyproject.toml

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

t_sql-4.6.0/tests/test_string_based_builders.py

@@ -0,0 +1,183 @@
+"""Test string-based query builders (dynamic table/column names)"""
+from tsql.query_builder import SelectQueryBuilder, InsertBuilder, UpdateBuilder, DeleteBuilder
+
+
+def test_select_from_string_table():
+    """Test SELECT query with string table name"""
+    query = SelectQueryBuilder.from_table('users').select('id', 'name', 'email')
+    sql, params = query.render()
+
+    assert 'SELECT id, name, email' in sql
+    assert 'FROM users' in sql
+    assert params == []
+
+
+def test_select_with_schema():
+    """Test SELECT with schema qualification"""
+    query = SelectQueryBuilder.from_table('users', schema='public').select('id', 'name')
+    sql, params = query.render()
+
+    assert 'FROM public.users' in sql
+
+
+def test_select_with_where_tstring():
+    """Test SELECT with t-string WHERE clause"""
+    user_id = 123
+    status = 'active'
+    query = SelectQueryBuilder.from_table('users').select('name').where(t'id = {user_id} AND status = {status}')
+    sql, params = query.render()
+
+    assert 'WHERE' in sql
+    assert params == [123, 'active']
+
+
+def test_select_order_by_string():
+    """Test ORDER BY with string column names"""
+    query = SelectQueryBuilder.from_table('users').select('id', 'name').order_by('created_at', direction='DESC')
+    sql, params = query.render()
+
+    assert 'ORDER BY created_at DESC' in sql
+
+
+def test_select_order_by_multiple():
+    """Test ORDER BY with multiple columns (chained calls)"""
+    query = SelectQueryBuilder.from_table('users') \
+        .select('id', 'name') \
+        .order_by('username') \
+        .order_by('created_at', direction='DESC')
+    sql, params = query.render()
+
+    assert 'ORDER BY username ASC, created_at DESC' in sql
+
+
+def test_select_group_by_string():
+    """Test GROUP BY with string column names"""
+    query = SelectQueryBuilder.from_table('orders').select('user_id', t'COUNT(*) as count').group_by('user_id')
+    sql, params = query.render()
+
+    assert 'GROUP BY user_id' in sql
+
+
+def test_select_limit_offset():
+    """Test LIMIT and OFFSET with string-based query"""
+    query = SelectQueryBuilder.from_table('users').select('id').limit(10).offset(20)
+    sql, params = query.render()
+
+    assert 'LIMIT' in sql
+    assert 'OFFSET' in sql
+    assert params == [10, 20]
+
+
+def test_insert_into_string_table():
+    """Test INSERT with string table name"""
+    query = InsertBuilder.into_table('users', {'name': 'Bob', 'email': 'bob@test.com'})
+    sql, params = query.render()
+
+    assert 'INSERT INTO users' in sql
+    assert 'name' in sql
+    assert 'email' in sql
+    assert 'Bob' in params
+    assert 'bob@test.com' in params
+
+
+def test_insert_with_schema():
+    """Test INSERT with schema qualification"""
+    query = InsertBuilder.into_table('users', {'name': 'Alice'}, schema='public')
+    sql, params = query.render()
+
+    assert 'INSERT INTO public.users' in sql
+
+
+def test_insert_with_returning():
+    """Test INSERT with RETURNING clause"""
+    query = InsertBuilder.into_table('users', {'name': 'Bob'}).returning('id')
+    sql, params = query.render()
+
+    assert 'RETURNING id' in sql
+
+
+def test_insert_on_conflict_do_nothing():
+    """Test INSERT with ON CONFLICT DO NOTHING"""
+    query = InsertBuilder.into_table('users', {'email': 'test@example.com'}).on_conflict_do_nothing('email')
+    sql, params = query.render()
+
+    assert 'ON CONFLICT' in sql
+    assert 'DO NOTHING' in sql
+
+
+def test_update_string_table():
+    """Test UPDATE with string table name"""
+    cutoff_date = '2024-01-01'
+    query = UpdateBuilder.table('users', {'status': 'inactive'}).where(t'last_login < {cutoff_date}')
+    sql, params = query.render()
+
+    assert 'UPDATE users' in sql
+    assert 'SET status' in sql
+    assert 'WHERE' in sql
+    assert 'inactive' in params
+    assert '2024-01-01' in params
+
+
+def test_update_with_schema():
+    """Test UPDATE with schema qualification"""
+    status = 'active'
+    query = UpdateBuilder.table('users', {'status': 'inactive'}, schema='public').where(t'status = {status}')
+    sql, params = query.render()
+
+    assert 'UPDATE public.users' in sql
+
+
+def test_delete_from_string_table():
+    """Test DELETE with string table name"""
+    cutoff = '2023-01-01'
+    query = DeleteBuilder.from_table('users').where(t'created_at < {cutoff}')
+    sql, params = query.render()
+
+    assert 'DELETE FROM users' in sql
+    assert 'WHERE' in sql
+    assert '2023-01-01' in params
+
+
+def test_delete_with_schema():
+    """Test DELETE with schema qualification"""
+    user_id = 999
+    query = DeleteBuilder.from_table('users', schema='public').where(t'id = {user_id}')
+    sql, params = query.render()
+
+    assert 'DELETE FROM public.users' in sql
+
+
+def test_string_based_prevents_injection():
+    """Test that invalid identifiers raise errors via :literal validation"""
+    import pytest
+
+    # Invalid table name
+    with pytest.raises(ValueError):
+        query = SelectQueryBuilder.from_table('users; DROP TABLE users--')
+        query.render()
+
+    # Invalid column name
+    with pytest.raises(ValueError):
+        query = SelectQueryBuilder.from_table('users').select('id; DROP TABLE users--')
+        query.render()
+
+    # Invalid schema name (too many dots)
+    with pytest.raises(ValueError):
+        query = SelectQueryBuilder.from_table('users', schema='a.b.c.d')
+        query.render()
+
+
+def test_mixed_string_and_tstring_columns():
+    """Test mixing string columns with t-string expressions"""
+    query = SelectQueryBuilder.from_table('users').select('id', 'name', t'UPPER(email) AS email_upper')
+    sql, params = query.render()
+
+    assert 'SELECT id, name, UPPER(email) AS email_upper' in sql
+
+
+def test_string_select_star():
+    """Test SELECT * with string-based table"""
+    query = SelectQueryBuilder.from_table('users')
+    sql, params = query.render()
+
+    assert 'SELECT * FROM users' in sql

{t_sql-4.5.2 → t_sql-4.6.0}/tsql/query_builder.py

@@ -14,6 +14,18 @@ class UnsafeQueryError(Exception):
     """
     pass
 
+
+class _StringTable:
+    """Minimal table representation for string-based queries.
+
+    This acts like a Table class but without the Column descriptors.
+    Used internally when queries are built with string table names.
+    """
+    def __init__(self, table_name: str, schema: Optional[str] = None):
+        self.table_name = table_name
+        self.schema = schema
+        self._type_processors = {}
+
 # Optional SQLAlchemy support
 try:
     from sqlalchemy import MetaData, Table as SATable, Column as SAColumn
@@ -620,7 +632,7 @@ class QueryBuilder(ABC):
 class InsertBuilder(QueryBuilder):
     """Fluent interface for building INSERT queries"""
 
-    def __init__(self, base_table: type['Table'], values: dict[str, Any]):
+    def __init__(self, base_table: Union[type['Table'], _StringTable], values: dict[str, Any]):
         self.base_table = base_table
 
         # Apply defaults from SQLAlchemy columns if available
@@ -650,6 +662,26 @@ class InsertBuilder(QueryBuilder):
         self._update_cols: Optional[dict[str, Any]] = None
         self._returning_cols: Optional[List[str]] = None
 
+    @classmethod
+    def into_table(cls, table_name: str, values: dict[str, Any], schema: Optional[str] = None) -> 'InsertBuilder':
+        """Create an InsertBuilder from a string table name.
+
+        Args:
+            table_name: Name of the table
+            values: Dictionary of column names and values
+            schema: Optional schema name
+
+        Returns:
+            InsertBuilder instance
+
+        Example:
+            InsertBuilder.into_table('users', {'name': 'Bob', 'email': 'bob@test.com'}) \\
+                .on_conflict_do_nothing('email') \\
+                .returning('id')
+        """
+        string_table = _StringTable(table_name, schema)
+        return cls(string_table, values)
+
     def ignore(self) -> 'InsertBuilder':
         """Add INSERT IGNORE (MySQL)"""
         self._ignore = True
@@ -848,7 +880,7 @@ def _process_value_for_builder(value: Any, type_processor: Any = None) -> Any:
 class UpdateBuilder(QueryBuilder):
     """Fluent interface for building UPDATE queries"""
 
-    def __init__(self, base_table: type['Table'], values: dict[str, Any]):
+    def __init__(self, base_table: Union[type['Table'], _StringTable], values: dict[str, Any]):
         self.base_table = base_table
 
         # Apply onupdate defaults from SQLAlchemy columns if available
@@ -876,6 +908,25 @@ class UpdateBuilder(QueryBuilder):
         self._returning_cols: Optional[List[str]] = None
         self._requires_where: bool = True
 
+    @classmethod
+    def table(cls, table_name: str, values: dict[str, Any], schema: Optional[str] = None) -> 'UpdateBuilder':
+        """Create an UpdateBuilder from a string table name.
+
+        Args:
+            table_name: Name of the table
+            values: Dictionary of column names and values to update
+            schema: Optional schema name
+
+        Returns:
+            UpdateBuilder instance
+
+        Example:
+            UpdateBuilder.table('users', {'status': 'inactive'}, schema='public') \\
+                .where(t'last_login < {cutoff_date}')
+        """
+        string_table = _StringTable(table_name, schema)
+        return cls(string_table, values)
+
     def where(self, condition: Union[Condition, Template]) -> 'UpdateBuilder':
         """Add a WHERE condition (multiple calls are ANDed together)"""
         self._conditions.append(condition)
@@ -977,12 +1028,30 @@ class UpdateBuilder(QueryBuilder):
 class DeleteBuilder(QueryBuilder):
     """Fluent interface for building DELETE queries"""
 
-    def __init__(self, base_table: type['Table']):
+    def __init__(self, base_table: Union[type['Table'], _StringTable]):
         self.base_table = base_table
         self._conditions: List[Union[Condition, Template]] = []
         self._returning_cols: Optional[List[str]] = None
         self._requires_where: bool = True
 
+    @classmethod
+    def from_table(cls, table_name: str, schema: Optional[str] = None) -> 'DeleteBuilder':
+        """Create a DeleteBuilder from a string table name.
+
+        Args:
+            table_name: Name of the table
+            schema: Optional schema name
+
+        Returns:
+            DeleteBuilder instance
+
+        Example:
+            DeleteBuilder.from_table('users', schema='public') \\
+                .where(t'created_at < {cutoff}')
+        """
+        string_table = _StringTable(table_name, schema)
+        return cls(string_table)
+
     def where(self, condition: Union[Condition, Template]) -> 'DeleteBuilder':
         """Add a WHERE condition (multiple calls are ANDed together)"""
         self._conditions.append(condition)
@@ -1077,22 +1146,41 @@ class DeleteBuilder(QueryBuilder):
 class SelectQueryBuilder(QueryBuilder):
     """Fluent interface for building SQL SELECT queries"""
 
-    def __init__(self, base_table: type['Table']):
+    def __init__(self, base_table: Union[type['Table'], _StringTable]):
         self.base_table = base_table
-        self._columns: Optional[List[Column]] = None
-        self._conditions: List[Condition] = []
+        self._columns: Optional[List[Union[Column, str]]] = None
+        self._conditions: List[Union[Condition, Template]] = []
         self._joins: List[Join] = []
-        self._group_by_columns: List[Column] = []
+        self._group_by_columns: List[Union[Column, str]] = []
         self._having_conditions: List[Union[Condition, Template]] = []
-        self._order_by_columns: List[tuple[Column, str]] = []
+        self._order_by_columns: List[tuple[Union[Column, str], str]] = []
         self._limit_value: Optional[int] = None
         self._offset_value: Optional[int] = None
 
-    def select(self, *columns: Union[Column, Template]) -> 'SelectQueryBuilder':
+    @classmethod
+    def from_table(cls, table_name: str, schema: Optional[str] = None) -> 'SelectQueryBuilder':
+        """Create a SelectQueryBuilder from a string table name.
+
+        Args:
+            table_name: Name of the table
+            schema: Optional schema name
+
+        Returns:
+            SelectQueryBuilder instance
+
+        Example:
+            SelectQueryBuilder.from_table('users', schema='public') \\
+                .select('id', 'name') \\
+                .where(t'status = {status}')
+        """
+        string_table = _StringTable(table_name, schema)
+        return cls(string_table)
+
+    def select(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
         """Specify columns to select
 
         Args:
-            columns: Column objects (optionally with .as_() aliases) or raw t-string Templates
+            columns: Column objects (optionally with .as_() aliases), raw t-string Templates, or string column names
 
         Examples:
             # Using Column.as_() for aliases
@@ -1101,6 +1189,9 @@ class SelectQueryBuilder(QueryBuilder):
             # Mixing Column objects and raw t-strings
             users.select(users.id, users.email, t'users.first_name AS first')
 
+            # String-based columns
+            SelectQueryBuilder.from_table('users').select('id', 'name', 'email')
+
             # No columns specified selects all (SELECT *)
             users.select()
         """
@@ -1128,11 +1219,12 @@ class SelectQueryBuilder(QueryBuilder):
         """Add a RIGHT JOIN clause"""
         return self.join(table, on, 'RIGHT')
 
-    def order_by(self, *columns: Union[Column, OrderByClause]) -> 'SelectQueryBuilder':
+    def order_by(self, *columns: Union[Column, OrderByClause, str], direction: str = 'ASC') -> 'SelectQueryBuilder':
         """Add ORDER BY clause
 
         Args:
-            columns: Column objects or OrderByClause objects (from .asc()/.desc())
+            columns: Column objects, OrderByClause objects (from .asc()/.desc()), or string column names
+            direction: Sort direction ('ASC' or 'DESC') for columns that don't have explicit direction
 
         Examples:
             # Using .asc() and .desc() methods
@@ -1140,16 +1232,31 @@ class SelectQueryBuilder(QueryBuilder):
 
             # Bare column defaults to ASC
             Users.select().order_by(Users.username)
+
+            # String-based ordering with explicit direction
+            SelectQueryBuilder.from_table('users').order_by('username', direction='DESC')
+
+            # Multiple columns in one call
+            Users.select().order_by(Users.username, Users.id.desc())
         """
-        for col in columns:
-            if isinstance(col, OrderByClause):
-                self._order_by_columns.append((col.column, col.direction))
+        for column in columns:
+            if isinstance(column, OrderByClause):
+                self._order_by_columns.append((column.column, column.direction))
             else:
-                self._order_by_columns.append((col, 'ASC'))
+                # Column or string with direction
+                self._order_by_columns.append((column, direction.upper()))
         return self
 
-    def group_by(self, *columns: Column) -> 'SelectQueryBuilder':
-        """Add GROUP BY clause"""
+    def group_by(self, *columns: Union[Column, str]) -> 'SelectQueryBuilder':
+        """Add GROUP BY clause
+
+        Args:
+            columns: Column objects or string column names
+
+        Examples:
+            # String-based GROUP BY
+            SelectQueryBuilder.from_table('orders').select('user_id', 'COUNT(*)').group_by('user_id')
+        """
         self._group_by_columns.extend(columns)
         return self
 
@@ -1176,11 +1283,14 @@ class SelectQueryBuilder(QueryBuilder):
         parts: List[Template] = []
 
         if self._columns:
-            # Build column list, handling both Column objects and Template (t-string) objects
+            # 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}')
@@ -1210,9 +1320,15 @@ class SelectQueryBuilder(QueryBuilder):
             parts.append(t'WHERE {combined_where}')
 
         if self._group_by_columns:
-            group_by_strs = [str(col) for col in self._group_by_columns]
-            group_by_str = ', '.join(group_by_strs)
-            parts.append(t'GROUP BY {group_by_str:unsafe}')
+            group_by_parts = []
+            for col in self._group_by_columns:
+                if isinstance(col, str):
+                    group_by_parts.append(t'{col:literal}')
+                else:
+                    col_str = str(col)
+                    group_by_parts.append(t'{col_str:unsafe}')
+            group_by_template = t_join(t', ', group_by_parts)
+            parts.append(t'GROUP BY {group_by_template}')
 
         if self._having_conditions:
             having_parts = []
@@ -1225,9 +1341,17 @@ class SelectQueryBuilder(QueryBuilder):
             parts.append(t'HAVING {combined_having}')
 
         if self._order_by_columns:
-            order_strs = [f"{col} {direction}" for col, direction in self._order_by_columns]
-            order_by_str = ', '.join(order_strs)
-            parts.append(t'ORDER BY {order_by_str:unsafe}')
+            order_parts = []
+            for col, direction in self._order_by_columns:
+                if isinstance(col, str):
+                    # String column name - validate with :literal
+                    order_parts.append(t'{col:literal} {direction:unsafe}')
+                else:
+                    # Column object - convert to string
+                    col_str = str(col)
+                    order_parts.append(t'{col_str:unsafe} {direction:unsafe}')
+            order_by_template = t_join(t', ', order_parts)
+            parts.append(t'ORDER BY {order_by_template}')
 
         if self._limit_value is not None:
             limit_val = self._limit_value