t-sql 2.2.1__tar.gz → 3.0.0__tar.gz

{t_sql-2.2.1 → t_sql-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 2.2.1
+Version: 3.0.0
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE
@@ -559,3 +559,99 @@ 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.
+
+# Security Considerations
+
+## Overview
+
+SQL injection is one of the most critical web application security risks (OWASP Top 10). This library is designed from the ground up to prevent SQL injection attacks through multiple layers of protection. However, understanding how these protections work—and where they can be bypassed—is essential for secure usage.
+
+## How t-sql Prevents SQL Injection
+
+### 1. Automatic Parameterization (Primary Defense)
+
+By default, all interpolated values in t-strings are converted to parameterized queries:
+
+```python
+# User input (potentially malicious)
+user_input = "admin' OR 1=1 --"
+
+# t-sql automatically parameterizes this
+sql, params = tsql.render(t"SELECT * FROM users WHERE name = {user_input}")
+# Result: ('SELECT * FROM users WHERE name = ?', ["admin' OR 1=1 --"])
+```
+
+The malicious SQL becomes **literal string data** in the parameter, not executable SQL code. The database treats it as a string value to match, not as SQL syntax.
+
+**Attack vectors prevented:**
+- Classic injection: `' OR 1=1 --`
+- Union-based: `' UNION SELECT * FROM secrets --`
+- Stacked queries: `'; DROP TABLE users; --`
+- Boolean-based blind: `' AND SLEEP(5) --`
+- Authentication bypass: `admin'--`
+
+### 2. Literal Validation (Identifier Safety)
+
+For table and column names that cannot be parameterized, use `:literal`:
+
+```python
+table = "users"
+col = "name"
+sql, params = tsql.render(t"SELECT * FROM {table:literal} WHERE {col:literal} = {value}")
+```
+
+**Validation rules:**
+- Must be valid Python identifiers (`str.isidentifier()`)
+- Supports qualified names: `table.column` or `schema.table.column` (max 3 parts)
+- Rejects anything with spaces, quotes, or special characters
+
+```python
+# These are REJECTED with ValueError:
+bad_table = "users; DROP TABLE secrets"  # Contains semicolon
+bad_col = "name' OR 1=1"  # Contains quote
+bad_schema = "schema.table.column.extra"  # Too many parts
+
+tsql.render(t"SELECT * FROM {bad_table:literal}")  # Raises ValueError
+```
+
+**Attack vectors prevented:**
+- Table/column injection: `users; DROP TABLE secrets`
+- Second-order injection via identifiers
+- Schema manipulation
+
+### 3. Escape-based Protection (ESCAPED Style)
+
+For databases or scenarios where parameterization isn't available, the `ESCAPED` style properly escapes values:
+
+```python
+malicious = "'; DROP TABLE users; --"
+sql, _ = tsql.render(t"SELECT * FROM users WHERE name = {malicious}", style=tsql.styles.ESCAPED)
+# Result: "SELECT * FROM users WHERE name = '''; DROP TABLE users; --'"
+#         (single quotes are doubled, making it literal data)
+```
+
+**Important:** While effective, parameterization is always preferred when available. Use `ESCAPED` only when necessary.
+
+## Danger Zones: Where You Can Still Get Hurt
+
+### The :unsafe Format Spec
+
+The `:unsafe` format spec **bypasses all safety mechanisms**:
+
+```python
+# DANGEROUS - no validation or parameterization!
+dynamic_sql = "age > 18 OR role = 'admin'"  # If this comes from user input, you're vulnerable
+sql, params = tsql.render(t"SELECT * FROM users WHERE {dynamic_sql:unsafe}")
+```
+
+**When :unsafe is acceptable:**
+- Hard-coded SQL fragments in your own code
+- SQL generated by trusted, validated builder logic
+- Dynamic ORDER BY clauses (after validation)
+
+**When :unsafe is DANGEROUS:**
+- **Never** with user input (even "validated" input)
+- Dynamic WHERE clauses from external sources
+- Any data from forms, APIs, or databases
+
+**Recommendation:** Treat `:unsafe` like `eval()` in your code reviews. Every usage should be scrutinized and documented.

{t_sql-2.2.1 → t_sql-3.0.0}/README.md

@@ -549,3 +549,99 @@ 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.
+
+# Security Considerations
+
+## Overview
+
+SQL injection is one of the most critical web application security risks (OWASP Top 10). This library is designed from the ground up to prevent SQL injection attacks through multiple layers of protection. However, understanding how these protections work—and where they can be bypassed—is essential for secure usage.
+
+## How t-sql Prevents SQL Injection
+
+### 1. Automatic Parameterization (Primary Defense)
+
+By default, all interpolated values in t-strings are converted to parameterized queries:
+
+```python
+# User input (potentially malicious)
+user_input = "admin' OR 1=1 --"
+
+# t-sql automatically parameterizes this
+sql, params = tsql.render(t"SELECT * FROM users WHERE name = {user_input}")
+# Result: ('SELECT * FROM users WHERE name = ?', ["admin' OR 1=1 --"])
+```
+
+The malicious SQL becomes **literal string data** in the parameter, not executable SQL code. The database treats it as a string value to match, not as SQL syntax.
+
+**Attack vectors prevented:**
+- Classic injection: `' OR 1=1 --`
+- Union-based: `' UNION SELECT * FROM secrets --`
+- Stacked queries: `'; DROP TABLE users; --`
+- Boolean-based blind: `' AND SLEEP(5) --`
+- Authentication bypass: `admin'--`
+
+### 2. Literal Validation (Identifier Safety)
+
+For table and column names that cannot be parameterized, use `:literal`:
+
+```python
+table = "users"
+col = "name"
+sql, params = tsql.render(t"SELECT * FROM {table:literal} WHERE {col:literal} = {value}")
+```
+
+**Validation rules:**
+- Must be valid Python identifiers (`str.isidentifier()`)
+- Supports qualified names: `table.column` or `schema.table.column` (max 3 parts)
+- Rejects anything with spaces, quotes, or special characters
+
+```python
+# These are REJECTED with ValueError:
+bad_table = "users; DROP TABLE secrets"  # Contains semicolon
+bad_col = "name' OR 1=1"  # Contains quote
+bad_schema = "schema.table.column.extra"  # Too many parts
+
+tsql.render(t"SELECT * FROM {bad_table:literal}")  # Raises ValueError
+```
+
+**Attack vectors prevented:**
+- Table/column injection: `users; DROP TABLE secrets`
+- Second-order injection via identifiers
+- Schema manipulation
+
+### 3. Escape-based Protection (ESCAPED Style)
+
+For databases or scenarios where parameterization isn't available, the `ESCAPED` style properly escapes values:
+
+```python
+malicious = "'; DROP TABLE users; --"
+sql, _ = tsql.render(t"SELECT * FROM users WHERE name = {malicious}", style=tsql.styles.ESCAPED)
+# Result: "SELECT * FROM users WHERE name = '''; DROP TABLE users; --'"
+#         (single quotes are doubled, making it literal data)
+```
+
+**Important:** While effective, parameterization is always preferred when available. Use `ESCAPED` only when necessary.
+
+## Danger Zones: Where You Can Still Get Hurt
+
+### The :unsafe Format Spec
+
+The `:unsafe` format spec **bypasses all safety mechanisms**:
+
+```python
+# DANGEROUS - no validation or parameterization!
+dynamic_sql = "age > 18 OR role = 'admin'"  # If this comes from user input, you're vulnerable
+sql, params = tsql.render(t"SELECT * FROM users WHERE {dynamic_sql:unsafe}")
+```
+
+**When :unsafe is acceptable:**
+- Hard-coded SQL fragments in your own code
+- SQL generated by trusted, validated builder logic
+- Dynamic ORDER BY clauses (after validation)
+
+**When :unsafe is DANGEROUS:**
+- **Never** with user input (even "validated" input)
+- Dynamic WHERE clauses from external sources
+- Any data from forms, APIs, or databases
+
+**Recommendation:** Treat `:unsafe` like `eval()` in your code reviews. Every usage should be scrutinized and documented.

{t_sql-2.2.1 → t_sql-3.0.0}/pyproject.toml

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

{t_sql-2.2.1 → t_sql-3.0.0}/tests/test_helper_functions.py

@@ -59,14 +59,9 @@ def test_insert():
 
 
 def test_update():
-    values = {
-        'name': 'Bob Updated',
-        'age': 35
-    }
-    
-    query = tsql.update('users', values, 123)
+    query = tsql.update('users', 123, name='Bob Updated', age=35)
     result = tsql.render(query)
-    
+
     assert "UPDATE users SET" in result[0]
     assert "name = ?" in result[0]
     assert "age = ?" in result[0]

{t_sql-2.2.1 → t_sql-3.0.0}/tests/test_mysql_integration.py

@@ -170,7 +170,7 @@ async def test_update_without_returning(conn):
         age: int
 
     # Update without RETURNING
-    query = TestUsers.update({'age': 31}).where(TestUsers.name == 'Alice')
+    query = TestUsers.update(age=31).where(TestUsers.name == 'Alice')
     sql, params = query.render(style=tsql.styles.FORMAT)
 
     # Should NOT have RETURNING clause
@@ -262,7 +262,7 @@ async def test_helper_functions(conn):
     assert row[1] == 25
 
     # Test update
-    query = tsql.update('test_users', {'age': 26}, 1)
+    query = tsql.update('test_users', 1, age=26)
     sql, params = query.render(style=tsql.styles.FORMAT)
 
     await cursor.execute(sql, params)

{t_sql-2.2.1 → t_sql-3.0.0}/tests/test_query_builder.py

@@ -351,7 +351,7 @@ def test_schema_in_update():
         id: Column
         name: Column
 
-    query = Accounts.update({'name': 'Updated Account'}).where(Accounts.id == '1')
+    query = Accounts.update(name='Updated Account').where(Accounts.id == '1')
     sql, params = query.render()
 
     assert 'UPDATE other.accounts SET' in sql
@@ -601,7 +601,7 @@ def test_table_insert_chained_with_returning():
 
 def test_table_update_with_where():
     """Test table.update() with WHERE clause"""
-    builder = Users.update({'username': 'bob_updated'}).where(Users.id == 5)
+    builder = Users.update(username='bob_updated').where(Users.id == 5)
     assert isinstance(builder, UpdateBuilder)
 
     sql, params = builder.render()
@@ -615,7 +615,7 @@ def test_table_update_with_where():
 
 def test_table_update_multiple_conditions():
     """Test table.update() with multiple WHERE conditions"""
-    builder = (Users.update({'username': 'bob_updated', 'email': 'new@example.com'})
+    builder = (Users.update(username='bob_updated', email='new@example.com')
                .where(Users.id > 10)
                .where(Users.created_at == None))
 
@@ -630,7 +630,7 @@ def test_table_update_multiple_conditions():
 
 def test_table_update_with_returning():
     """Test table.update() with RETURNING"""
-    builder = Users.update({'username': 'bob_updated'}).where(Users.id == 5).returning()
+    builder = Users.update(username='bob_updated').where(Users.id == 5).returning()
     sql, params = builder.render()
 
     assert 'UPDATE users SET' in sql
@@ -681,7 +681,7 @@ def test_table_delete_with_returning():
 def test_update_with_t_string_where():
     """Test UpdateBuilder with raw t-string WHERE clause"""
     min_age = 18
-    builder = Users.update({'username': 'adult'}).where(t"age >= {min_age}")
+    builder = Users.update(username='adult').where(t"age >= {min_age}")
 
     sql, params = builder.render()
 
@@ -1062,7 +1062,7 @@ def test_update_with_onupdate_default():
         title = SAColumn(String)
         updated_at = SAColumn(String, onupdate=lambda: 'updated_timestamp')
 
-    query = Articles.update({'title': 'Updated Title'}).where(Articles.id == '123')
+    query = Articles.update(title='Updated Title').where(Articles.id == '123')
     sql, params = query.render()
 
     assert 'UPDATE articles SET' in sql
@@ -1082,7 +1082,7 @@ def test_update_overrides_onupdate():
         title = SAColumn(String)
         updated_at = SAColumn(String, onupdate=lambda: 'auto_timestamp')
 
-    query = Articles.update({'title': 'Updated', 'updated_at': 'manual_timestamp'}).where(Articles.id == '123')
+    query = Articles.update(title='Updated', updated_at='manual_timestamp').where(Articles.id == '123')
     sql, params = query.render()
 
     assert 'UPDATE articles SET' in sql
@@ -1140,14 +1140,14 @@ def test_returning_cols_validation_update():
     import pytest
 
     # Test with malicious returning column
-    query = Users.update({'username': 'hacked'})
+    query = Users.update(username='hacked')
     builder = query.returning("id, (SELECT password FROM admin_users LIMIT 1) AS stolen")
 
     with pytest.raises(ValueError, match="Invalid RETURNING column name"):
         builder.render()
 
     # Test with valid returning columns (should work)
-    query2 = Users.update({'username': 'updated'})
+    query2 = Users.update(username='updated')
     builder2 = query2.where(Users.id == 5).returning("id", "username")
     sql, params = builder2.render()
 

{t_sql-2.2.1 → t_sql-3.0.0}/tests/test_sqlite_integration.py

@@ -136,7 +136,7 @@ async def test_update_with_returning(conn):
         age: int
 
     # Update with RETURNING
-    query = TestUsers.update({'age': 31}).where(TestUsers.name == 'Alice').returning()
+    query = TestUsers.update(age=31).where(TestUsers.name == 'Alice').returning()
     sql, params = query.render()
 
     assert 'RETURNING *' in sql
@@ -196,7 +196,7 @@ async def test_update_without_returning(conn):
         age: int
 
     # Update without RETURNING
-    query = TestUsers.update({'age': 31}).where(TestUsers.name == 'Alice')
+    query = TestUsers.update(age=31).where(TestUsers.name == 'Alice')
     sql, params = query.render()
 
     # Should NOT have RETURNING clause
@@ -278,7 +278,7 @@ async def test_helper_functions(conn):
     assert row[1] == 25
 
     # Test update
-    query = tsql.update('test_users', {'age': 26}, 1)
+    query = tsql.update('test_users', 1, age=26)
     sql, params = query.render()
 
     await conn.execute(sql, params)

{t_sql-2.2.1 → t_sql-3.0.0}/tsql/__init__.py

@@ -326,19 +326,23 @@ def insert(table: str, **values: Any) -> TSQL:
     return TSQL(t"INSERT INTO {table:literal} {values:as_values}")
 
 
-def update(table: str, values: dict[str, Any], id: str | int) -> TSQL:
+def update(table: str, id: str | int, **values: Any) -> TSQL:
     """Helper function to build UPDATE queries for a single row
 
     Args:
         table: Table name
-        values: Dictionary of column names and values to update
         id: ID value to update
+        **values: Column names and values to update as keyword arguments
 
     Returns:
         TSQL object representing the UPDATE query
+
+    Example:
+        update('users', 123, name='Bob', age=35)
+        Or with dict unpacking: update('users', 123, **my_dict)
     """
-    if not isinstance(values, dict):
-        raise ValueError("values must be a dictionary")
+    if not values:
+        raise ValueError("update requires at least one column value")
 
     return TSQL(t"UPDATE {table:literal} SET {values:as_set} WHERE id = {id}")
 

{t_sql-2.2.1 → t_sql-3.0.0}/tsql/query_builder.py

@@ -298,14 +298,18 @@ class Table:
         return InsertBuilder(cls, values)
 
     @classmethod
-    def update(cls, values: dict[str, Any]) -> 'UpdateBuilder':
+    def update(cls, **values: Any) -> 'UpdateBuilder':
         """Start building an UPDATE query
 
         Args:
-            values: Dictionary of column names and values to update
+            **values: Column names and values to update as keyword arguments
 
         Returns:
             UpdateBuilder for adding WHERE conditions
+
+        Example:
+            Users.update(username='bob', email='bob@example.com')
+            Or with dict unpacking: Users.update(**my_dict)
         """
         return UpdateBuilder(cls, values)