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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 2.2.1
+Version: 3.1.0
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE
@@ -159,8 +159,7 @@ sql, params = query.render()
 Quick INSERT queries:
 
 ```python
-values = {'id': 'abc123', 'name': 'bob', 'email': 'bob@example.com'}
-query = tsql.insert('users', values)
+query = tsql.insert('users', id='abc123', name='bob', email='bob@example.com')
 sql, params = query.render()
 # ('INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['abc123', 'bob', 'bob@example.com'])
 ```
@@ -171,14 +170,9 @@ Quick UPDATE queries:
 
 ```python
 # Update by ID
-query = tsql.update('users', {'email': 'new@example.com'}, id_value='abc123')
+query = tsql.update('users', 'abc123', email='new@example.com')
 sql, params = query.render()
 # ('UPDATE users SET email = ? WHERE id = ?', ['new@example.com', 'abc123'])
-
-# Update with custom WHERE
-query = tsql.update('users', {'email': 'new@example.com'}, where={'age': 25})
-sql, params = query.render()
-# ('UPDATE users SET email = ? WHERE age = ?', ['new@example.com', 25])
 ```
 
 #### delete
@@ -271,8 +265,9 @@ query = Users.select().where(Users.id.in_([1, 2, 3]))
 query = Users.select().where(Users.username.like('%john%'))
 
 # ORDER BY
-query = Posts.select().order_by(Posts.id)
-query = Posts.select().order_by((Posts.id, 'DESC'))
+query = Posts.select().order_by(Posts.id)  # defaults to ASC
+query = Posts.select().order_by(Posts.id.desc())
+query = Posts.select().order_by(Posts.created_at.asc(), Posts.id.desc())
 
 # LIMIT and OFFSET
 query = Posts.select().limit(10).offset(20)
@@ -291,47 +286,46 @@ The query builder supports INSERT, UPDATE, and DELETE with database-agnostic con
 
 ```python
 # Basic insert
-values = {'id': 'abc123', 'username': 'john', 'email': 'john@example.com'}
-query = Users.insert(values)
+query = Users.insert(id='abc123', username='john', email='john@example.com')
 sql, params = query.render()
 # ('INSERT INTO users (id, username, email) VALUES (?, ?, ?)', ['abc123', 'john', 'john@example.com'])
 
 # INSERT with RETURNING (Postgres/SQLite)
-query = Users.insert(values).returning()
+query = Users.insert(id='abc123', username='john', email='john@example.com').returning()
 sql, params = query.render()
 # ('INSERT INTO users (id, username, email) VALUES (?, ?, ?) RETURNING *', [...])
 
 # INSERT IGNORE (MySQL)
-query = Users.insert(values).ignore()
+query = Users.insert(id='abc123', username='john', email='john@example.com').ignore()
 sql, params = query.render()
 # ('INSERT IGNORE INTO users (id, username, email) VALUES (?, ?, ?)', [...])
 
 # ON CONFLICT DO NOTHING (Postgres/SQLite)
-query = Users.insert(values).on_conflict_do_nothing()
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_do_nothing()
 # ('INSERT INTO users (...) VALUES (...) ON CONFLICT DO NOTHING', [...])
 
 # ON CONFLICT DO NOTHING with specific conflict target (Postgres/SQLite)
-query = Users.insert(values).on_conflict_do_nothing(conflict_on='email')
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_do_nothing(conflict_on='email')
 # ('INSERT INTO users (...) VALUES (...) ON CONFLICT (email) DO NOTHING', [...])
 
 # ON CONFLICT DO UPDATE (Postgres/SQLite upsert)
-query = Users.insert(values).on_conflict_update(conflict_on='id')
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_update(conflict_on='id')
 # ('INSERT INTO users (...) VALUES (...)
 #   ON CONFLICT (id) DO UPDATE SET username = EXCLUDED.username, email = EXCLUDED.email', [...])
 
 # ON CONFLICT with custom update
-query = Users.insert(values).on_conflict_update(
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_update(
     conflict_on='id',
     update={'username': 'updated_name'}
 )
 
 # ON DUPLICATE KEY UPDATE (MySQL)
-query = Users.insert(values).on_duplicate_key_update()
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_duplicate_key_update()
 # ('INSERT INTO users (...) VALUES (...)
 #   ON DUPLICATE KEY UPDATE id = VALUES(id), username = VALUES(username), ...', [...])
 
 # Chain multiple modifiers
-query = (Users.insert(values)
+query = (Users.insert(id='abc123', username='john', email='john@example.com')
          .on_conflict_update(conflict_on='id')
          .returning('id', 'username'))
 ```
@@ -340,22 +334,22 @@ query = (Users.insert(values)
 
 ```python
 # Basic update (no WHERE = updates all rows!)
-query = Users.update({'email': 'newemail@example.com'})
+query = Users.update(email='newemail@example.com')
 sql, params = query.render()
 # ('UPDATE users SET email = ?', ['newemail@example.com'])
 
 # UPDATE with WHERE
-query = Users.update({'email': 'newemail@example.com'}).where(Users.id == 'abc123')
+query = Users.update(email='newemail@example.com').where(Users.id == 'abc123')
 sql, params = query.render()
 # ('UPDATE users SET email = ? WHERE users.id = ?', ['newemail@example.com', 'abc123'])
 
 # Multiple WHERE conditions
-query = (Users.update({'email': 'newemail@example.com'})
+query = (Users.update(email='newemail@example.com')
          .where(Users.id == 'abc123')
          .where(Users.age > 18))
 
 # With RETURNING (Postgres/SQLite)
-query = (Users.update({'email': 'new@example.com'})
+query = (Users.update(email='new@example.com')
          .where(Users.id == 'abc123')
          .returning())
 # ('UPDATE users SET email = ? WHERE users.id = ? RETURNING *', [...])
@@ -559,3 +553,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.1.0}/README.md

@@ -149,8 +149,7 @@ sql, params = query.render()
 Quick INSERT queries:
 
 ```python
-values = {'id': 'abc123', 'name': 'bob', 'email': 'bob@example.com'}
-query = tsql.insert('users', values)
+query = tsql.insert('users', id='abc123', name='bob', email='bob@example.com')
 sql, params = query.render()
 # ('INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['abc123', 'bob', 'bob@example.com'])
 ```
@@ -161,14 +160,9 @@ Quick UPDATE queries:
 
 ```python
 # Update by ID
-query = tsql.update('users', {'email': 'new@example.com'}, id_value='abc123')
+query = tsql.update('users', 'abc123', email='new@example.com')
 sql, params = query.render()
 # ('UPDATE users SET email = ? WHERE id = ?', ['new@example.com', 'abc123'])
-
-# Update with custom WHERE
-query = tsql.update('users', {'email': 'new@example.com'}, where={'age': 25})
-sql, params = query.render()
-# ('UPDATE users SET email = ? WHERE age = ?', ['new@example.com', 25])
 ```
 
 #### delete
@@ -261,8 +255,9 @@ query = Users.select().where(Users.id.in_([1, 2, 3]))
 query = Users.select().where(Users.username.like('%john%'))
 
 # ORDER BY
-query = Posts.select().order_by(Posts.id)
-query = Posts.select().order_by((Posts.id, 'DESC'))
+query = Posts.select().order_by(Posts.id)  # defaults to ASC
+query = Posts.select().order_by(Posts.id.desc())
+query = Posts.select().order_by(Posts.created_at.asc(), Posts.id.desc())
 
 # LIMIT and OFFSET
 query = Posts.select().limit(10).offset(20)
@@ -281,47 +276,46 @@ The query builder supports INSERT, UPDATE, and DELETE with database-agnostic con
 
 ```python
 # Basic insert
-values = {'id': 'abc123', 'username': 'john', 'email': 'john@example.com'}
-query = Users.insert(values)
+query = Users.insert(id='abc123', username='john', email='john@example.com')
 sql, params = query.render()
 # ('INSERT INTO users (id, username, email) VALUES (?, ?, ?)', ['abc123', 'john', 'john@example.com'])
 
 # INSERT with RETURNING (Postgres/SQLite)
-query = Users.insert(values).returning()
+query = Users.insert(id='abc123', username='john', email='john@example.com').returning()
 sql, params = query.render()
 # ('INSERT INTO users (id, username, email) VALUES (?, ?, ?) RETURNING *', [...])
 
 # INSERT IGNORE (MySQL)
-query = Users.insert(values).ignore()
+query = Users.insert(id='abc123', username='john', email='john@example.com').ignore()
 sql, params = query.render()
 # ('INSERT IGNORE INTO users (id, username, email) VALUES (?, ?, ?)', [...])
 
 # ON CONFLICT DO NOTHING (Postgres/SQLite)
-query = Users.insert(values).on_conflict_do_nothing()
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_do_nothing()
 # ('INSERT INTO users (...) VALUES (...) ON CONFLICT DO NOTHING', [...])
 
 # ON CONFLICT DO NOTHING with specific conflict target (Postgres/SQLite)
-query = Users.insert(values).on_conflict_do_nothing(conflict_on='email')
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_do_nothing(conflict_on='email')
 # ('INSERT INTO users (...) VALUES (...) ON CONFLICT (email) DO NOTHING', [...])
 
 # ON CONFLICT DO UPDATE (Postgres/SQLite upsert)
-query = Users.insert(values).on_conflict_update(conflict_on='id')
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_update(conflict_on='id')
 # ('INSERT INTO users (...) VALUES (...)
 #   ON CONFLICT (id) DO UPDATE SET username = EXCLUDED.username, email = EXCLUDED.email', [...])
 
 # ON CONFLICT with custom update
-query = Users.insert(values).on_conflict_update(
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_conflict_update(
     conflict_on='id',
     update={'username': 'updated_name'}
 )
 
 # ON DUPLICATE KEY UPDATE (MySQL)
-query = Users.insert(values).on_duplicate_key_update()
+query = Users.insert(id='abc123', username='john', email='john@example.com').on_duplicate_key_update()
 # ('INSERT INTO users (...) VALUES (...)
 #   ON DUPLICATE KEY UPDATE id = VALUES(id), username = VALUES(username), ...', [...])
 
 # Chain multiple modifiers
-query = (Users.insert(values)
+query = (Users.insert(id='abc123', username='john', email='john@example.com')
          .on_conflict_update(conflict_on='id')
          .returning('id', 'username'))
 ```
@@ -330,22 +324,22 @@ query = (Users.insert(values)
 
 ```python
 # Basic update (no WHERE = updates all rows!)
-query = Users.update({'email': 'newemail@example.com'})
+query = Users.update(email='newemail@example.com')
 sql, params = query.render()
 # ('UPDATE users SET email = ?', ['newemail@example.com'])
 
 # UPDATE with WHERE
-query = Users.update({'email': 'newemail@example.com'}).where(Users.id == 'abc123')
+query = Users.update(email='newemail@example.com').where(Users.id == 'abc123')
 sql, params = query.render()
 # ('UPDATE users SET email = ? WHERE users.id = ?', ['newemail@example.com', 'abc123'])
 
 # Multiple WHERE conditions
-query = (Users.update({'email': 'newemail@example.com'})
+query = (Users.update(email='newemail@example.com')
          .where(Users.id == 'abc123')
          .where(Users.age > 18))
 
 # With RETURNING (Postgres/SQLite)
-query = (Users.update({'email': 'new@example.com'})
+query = (Users.update(email='new@example.com')
          .where(Users.id == 'abc123')
          .returning())
 # ('UPDATE users SET email = ? WHERE users.id = ? RETURNING *', [...])
@@ -549,3 +543,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.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "t-sql"
-version = "2.2.1"
+version = "3.1.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.1.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.1.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.1.0}/tests/test_query_builder.py

@@ -213,7 +213,7 @@ def test_order_by():
 
 def test_order_by_desc():
     """Test ORDER BY with DESC"""
-    query = Users.select().order_by((Users.id, 'DESC'))
+    query = Users.select().order_by(Users.id.desc())
     sql, params = query.render()
 
     assert 'ORDER BY users.id DESC' in sql
@@ -221,7 +221,39 @@ def test_order_by_desc():
 
 def test_order_by_multiple():
     """Test ORDER BY with multiple columns"""
-    query = Users.select().order_by(Users.username, (Users.id, 'DESC'))
+    query = Users.select().order_by(Users.username, Users.id.desc())
+    sql, params = query.render()
+
+    assert 'ORDER BY users.username ASC, users.id DESC' in sql
+
+
+def test_order_by_asc_method():
+    """Test ORDER BY with .asc() method"""
+    query = Users.select().order_by(Users.username.asc())
+    sql, params = query.render()
+
+    assert 'ORDER BY users.username ASC' in sql
+
+
+def test_order_by_desc_method():
+    """Test ORDER BY with .desc() method"""
+    query = Users.select().order_by(Users.id.desc())
+    sql, params = query.render()
+
+    assert 'ORDER BY users.id DESC' in sql
+
+
+def test_order_by_mixed_methods():
+    """Test ORDER BY with mixed .asc() and .desc() methods"""
+    query = Users.select().order_by(Users.username.asc(), Users.id.desc())
+    sql, params = query.render()
+
+    assert 'ORDER BY users.username ASC, users.id DESC' in sql
+
+
+def test_order_by_mixed_syntax():
+    """Test ORDER BY with mixed method calls and bare columns"""
+    query = Users.select().order_by(Users.username, Users.id.desc())
     sql, params = query.render()
 
     assert 'ORDER BY users.username ASC, users.id DESC' in sql
@@ -242,7 +274,7 @@ def test_complex_query():
              .join(Users, Posts.user_id == Users.id)
              .where(Posts.id > 100)
              .where(Users.id >= 5)
-             .order_by((Posts.id, 'DESC'))
+             .order_by(Posts.id.desc())
              .limit(20))
     sql, params = query.render()
 
@@ -351,7 +383,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
@@ -480,7 +512,7 @@ def test_complex_aggregation_query():
              .where(Posts.id > 100)
              .group_by(Posts.user_id)
              .having(Posts.id > 5)
-             .order_by((Posts.user_id, 'DESC'))
+             .order_by(Posts.user_id.desc())
              .limit(10)
              .offset(5))
     sql, params = query.render()
@@ -601,7 +633,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 +647,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 +662,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 +713,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 +1094,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 +1114,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 +1172,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.1.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)
@@ -331,7 +331,7 @@ async def test_query_builder_select(conn):
     assert rows[0][0] == 'Alice'
 
     # Test ORDER BY
-    query = TestUsers.select().order_by((TestUsers.age, 'DESC'))
+    query = TestUsers.select().order_by(TestUsers.age.desc())
     sql, params = query.render()
 
     cursor = await conn.execute(sql, params)

{t_sql-2.2.1 → t_sql-3.1.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.1.0}/tsql/query_builder.py

@@ -16,6 +16,17 @@ except ImportError:
     SAColumnType = None
 
 
+class OrderByClause:
+    """Represents a column with an ORDER BY direction (ASC/DESC)"""
+
+    def __init__(self, column: 'Column', direction: str):
+        self.column = column
+        self.direction = direction.upper()
+
+    def __repr__(self) -> str:
+        return f"OrderByClause({self.column!r}, {self.direction!r})"
+
+
 class Column:
     """Represents a bound column (table + column name) for building queries"""
 
@@ -140,6 +151,28 @@ class Column:
         """Create an IS NOT NULL condition"""
         return Condition(self, 'IS NOT', None)
 
+    def asc(self) -> OrderByClause:
+        """Create an ascending ORDER BY clause
+
+        Returns:
+            OrderByClause for use in order_by()
+
+        Example:
+            Users.select().order_by(Users.username.asc())
+        """
+        return OrderByClause(self, 'ASC')
+
+    def desc(self) -> OrderByClause:
+        """Create a descending ORDER BY clause
+
+        Returns:
+            OrderByClause for use in order_by()
+
+        Example:
+            Users.select().order_by(Users.created_at.desc())
+        """
+        return OrderByClause(self, 'DESC')
+
 
 class Table:
     """Base class for all table definitions. Provides query builder methods.
@@ -298,14 +331,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)
 
@@ -834,11 +871,22 @@ class SelectQueryBuilder(QueryBuilder):
         """Add a RIGHT JOIN clause"""
         return self.join(table, on, 'RIGHT')
 
-    def order_by(self, *columns: Union[Column, tuple[Column, str]]) -> 'SelectQueryBuilder':
-        """Add ORDER BY clause. Pass (column, 'DESC') for descending"""
+    def order_by(self, *columns: Union[Column, OrderByClause]) -> 'SelectQueryBuilder':
+        """Add ORDER BY clause
+
+        Args:
+            columns: Column objects or OrderByClause objects (from .asc()/.desc())
+
+        Examples:
+            # Using .asc() and .desc() methods
+            Users.select().order_by(Users.username.asc(), Users.id.desc())
+
+            # Bare column defaults to ASC
+            Users.select().order_by(Users.username)
+        """
         for col in columns:
-            if isinstance(col, tuple):
-                self._order_by_columns.append(col)
+            if isinstance(col, OrderByClause):
+                self._order_by_columns.append((col.column, col.direction))
             else:
                 self._order_by_columns.append((col, 'ASC'))
         return self