t-sql 2.1.2__tar.gz → 2.1.3__tar.gz

{t_sql-2.1.2 → t_sql-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 2.1.2
+Version: 2.1.3
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE
@@ -515,17 +515,47 @@ class Users(Table, table_name='user_accounts', schema='public'):
     name: Column
 ```
 
-# Note on Usage
+# Rendering Queries
 
-This library should ideally be used in middleware or library code right before making a query. It can enforce the use of t-strings and prevent raw strings:
+All query types (t-strings, TSQL objects, and QueryBuilder objects) can be rendered using `tsql.render()`:
 
 ```python
-from string.templatelib import Template
 import tsql
+from tsql.query_builder import Table, Column
+
+class Users(Table):
+    id: Column
+    name: Column
+
+# All of these work with tsql.render():
+sql, params = tsql.render(t"SELECT * FROM users WHERE id = {user_id}")
+sql, params = tsql.render(Users.select().where(Users.id == user_id))
+sql, params = tsql.render(tsql.select('users', user_id))
+
+# Or call .render() directly on TSQL/QueryBuilder objects:
+query = Users.select().where(Users.age > 18)
+sql, params = query.render()
+```
+
+# Type Safety & Preventing SQL Injection
+
+This library should ideally be used in middleware or library code to enforce safe query construction. Use the `TSQLQuery` type to prevent raw strings:
 
-def execute_sql_query(query):
-    if not isinstance(query, Template):
-        raise TypeError('Cannot make a query without using t-strings')
+```python
+from tsql import TSQLQuery, render
+
+def execute_sql_query(query: TSQLQuery):
+    """Only accepts safe, parameterized queries"""
+    sql, params = render(query)
+    return sql_engine.execute(sql, params)
 
-    return sql_engine.execute(*tsql.render(query))
+# Type checker allows these:
+execute_sql_query(t"SELECT * FROM users WHERE id = {user_id}")  # ✓
+execute_sql_query(Users.select())  # ✓
+execute_sql_query(tsql.select('users'))  # ✓
+
+# Type checker rejects raw strings:
+execute_sql_query("SELECT * FROM users")  # ✗ Type error!
 ```
+
+The `TSQLQuery` type is a union of `TSQL`, `Template` (t-strings), and `QueryBuilder`, ensuring all queries are safe from SQL injection.

{t_sql-2.1.2 → t_sql-2.1.3}/README.md

@@ -505,17 +505,47 @@ class Users(Table, table_name='user_accounts', schema='public'):
     name: Column
 ```
 
-# Note on Usage
+# Rendering Queries
 
-This library should ideally be used in middleware or library code right before making a query. It can enforce the use of t-strings and prevent raw strings:
+All query types (t-strings, TSQL objects, and QueryBuilder objects) can be rendered using `tsql.render()`:
 
 ```python
-from string.templatelib import Template
 import tsql
+from tsql.query_builder import Table, Column
+
+class Users(Table):
+    id: Column
+    name: Column
+
+# All of these work with tsql.render():
+sql, params = tsql.render(t"SELECT * FROM users WHERE id = {user_id}")
+sql, params = tsql.render(Users.select().where(Users.id == user_id))
+sql, params = tsql.render(tsql.select('users', user_id))
+
+# Or call .render() directly on TSQL/QueryBuilder objects:
+query = Users.select().where(Users.age > 18)
+sql, params = query.render()
+```
+
+# Type Safety & Preventing SQL Injection
+
+This library should ideally be used in middleware or library code to enforce safe query construction. Use the `TSQLQuery` type to prevent raw strings:
 
-def execute_sql_query(query):
-    if not isinstance(query, Template):
-        raise TypeError('Cannot make a query without using t-strings')
+```python
+from tsql import TSQLQuery, render
+
+def execute_sql_query(query: TSQLQuery):
+    """Only accepts safe, parameterized queries"""
+    sql, params = render(query)
+    return sql_engine.execute(sql, params)
 
-    return sql_engine.execute(*tsql.render(query))
+# Type checker allows these:
+execute_sql_query(t"SELECT * FROM users WHERE id = {user_id}")  # ✓
+execute_sql_query(Users.select())  # ✓
+execute_sql_query(tsql.select('users'))  # ✓
+
+# Type checker rejects raw strings:
+execute_sql_query("SELECT * FROM users")  # ✗ Type error!
 ```
+
+The `TSQLQuery` type is a union of `TSQL`, `Template` (t-strings), and `QueryBuilder`, ensuring all queries are safe from SQL injection.

{t_sql-2.1.2 → t_sql-2.1.3}/pyproject.toml

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

{t_sql-2.1.2 → t_sql-2.1.3}/tsql/__init__.py

@@ -1,10 +1,13 @@
 import re
 import string
-from typing import NamedTuple, Tuple, Any, List, Dict, Iterable
+from typing import NamedTuple, Tuple, Any, List, Dict, Iterable, Union, TYPE_CHECKING
 from string.templatelib import Template, Interpolation
 
 from tsql.styles import ParamStyle, QMARK
 
+if TYPE_CHECKING:
+    from tsql.query_builder import QueryBuilder
+
 default_style = QMARK
 
 def set_style(style: type[ParamStyle]):
@@ -213,7 +216,57 @@ def as_set(value_dict: dict[str, Any]):
     return tsql_obj
 
 
-def render(query: Template|TSQL, style=None) -> RenderedQuery:
+# Type alias for safe, parameterized queries
+TSQLQuery = Union[TSQL, Template, 'QueryBuilder']
+"""Type alias representing safe, parameterized SQL queries.
+
+This type includes all valid ways to construct safe queries in tsql:
+- TSQL: Rendered t-string queries
+- Template: Raw t-string templates (PEP 750)
+- QueryBuilder: Type-safe query builder objects
+
+Use this type to ensure functions only accept safe, parameterized queries
+and never raw strings that could be vulnerable to SQL injection.
+
+Examples:
+    Accept any safe query type::
+
+        def execute_query(query: TSQLQuery) -> None:
+            sql, params = render(query)
+            cursor.execute(sql, params)
+
+    Type checking prevents unsafe usage::
+
+        execute_query(t"SELECT * FROM users WHERE id = {user_id}")  # OK
+        execute_query(select("users"))  # OK
+        execute_query(User.select().where(User.id == 1))  # OK
+        execute_query("SELECT * FROM users")  # Type error!
+"""
+
+
+def render(query: TSQLQuery, style=None) -> RenderedQuery:
+    """Render a safe query to SQL and parameters.
+
+    Args:
+        query: A TSQLQuery (TSQL, Template, or QueryBuilder)
+        style: Optional parameter style (defaults to global default_style)
+
+    Returns:
+        RenderedQuery with sql string and parameter values
+
+    Raises:
+        TypeError: If query is a raw string (use t-strings instead)
+    """
+    # Handle QueryBuilder (duck typing to avoid circular import)
+    if hasattr(query, 'build') and callable(query.build):
+        query = query.build()
+
+    if isinstance(query, str):
+        raise TypeError(
+            "Cannot render raw strings - they are vulnerable to SQL injection. "
+            "Use t-strings instead: t'SELECT * FROM users WHERE id = {user_id}'"
+        )
+
     if not isinstance(query, TSQL):
         query = TSQL(query)
 
@@ -305,6 +358,7 @@ def delete(table: str, id: str | int) -> TSQL:
 
 __all__ = [
     'TSQL',
+    'TSQLQuery',
     'render',
     't_join',
     'select',