t-sql 4.2.1__tar.gz → 4.4.0__tar.gz

{t_sql-4.2.1 → t_sql-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 4.2.1
+Version: 4.4.0
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE
@@ -526,6 +526,124 @@ query = Users.select().where(Users.age > 18)
 
 The `SAColumn` wrapper tells type checkers it returns a tsql `Column`, while at runtime it creates a SQLAlchemy `Column`. This gives you proper IDE completions for methods like `.is_null()`, `.like()`, etc.
 
+### Table Constraints
+
+For Alembic migrations, you can define table-level constraints using the `constraints` attribute:
+
+```python
+from sqlalchemy import MetaData, String, UniqueConstraint, CheckConstraint, Index
+from tsql.query_builder import Table, SAColumn
+
+metadata = MetaData()
+
+class Clients(Table, table_name='clients', metadata=metadata):
+    id = SAColumn(String, primary_key=True)
+    tenant_id = SAColumn(String)
+    email = SAColumn(String, nullable=False)
+
+    # Define table-level constraints
+    constraints = [
+        UniqueConstraint('tenant_id', 'email', name='uq_clients_tenant_email'),
+        CheckConstraint('length(email) > 0', name='ck_clients_email_not_empty'),
+        Index('ix_clients_tenant', 'tenant_id')
+    ]
+```
+
+The `constraints` attribute accepts both lists and tuples, and supports all SQLAlchemy constraint types:
+- `UniqueConstraint` - Multi-column unique constraints
+- `CheckConstraint` - Table-level check constraints
+- `Index` - Multi-column indexes
+- `ForeignKeyConstraint` - Table-level foreign keys
+
+**Note:** Single-column constraints like unique indexes and foreign keys can still be defined directly on `SAColumn` (e.g., `SAColumn(String, unique=True, index=True)`).
+
+### Table Comments
+
+Add database-level documentation with the `comment` parameter:
+
+```python
+class Users(Table, metadata=metadata, comment='Application user accounts'):
+    id = SAColumn(Integer, primary_key=True)
+    email = SAColumn(String(255), nullable=False)
+```
+
+Table comments appear in database introspection tools and migration files, making your schema self-documenting.
+
+### Type Processors
+
+Type processors enable automatic value transformation when reading from and writing to the database, similar to SQLAlchemy's `TypeDecorator`. This is useful for encryption, serialization, and custom data transformations.
+
+```python
+from tsql import TypeProcessor
+from tsql.query_builder import Table, SAColumn
+from sqlalchemy import Integer, String, MetaData
+import json
+
+metadata = MetaData()
+
+# Define custom type processors
+class EncryptedString(TypeProcessor):
+    def __init__(self, key):
+        self.key = key
+
+    def process_bind_param(self, value):
+        """Transform Python value -> DB value (encrypt on write)"""
+        if value is None:
+            return None
+        return encrypt(value, self.key)
+
+    def process_result_value(self, value):
+        """Transform DB value -> Python value (decrypt on read)"""
+        if value is None:
+            return None
+        return decrypt(value, self.key)
+
+class JSONType(TypeProcessor):
+    def process_bind_param(self, value):
+        """Serialize Python dict/list -> JSON string"""
+        return json.dumps(value) if value is not None else None
+
+    def process_result_value(self, value):
+        """Deserialize JSON string -> Python dict/list"""
+        return json.loads(value) if value is not None else None
+
+# Use type processors in table definition
+class User(Table, metadata=metadata):
+    id = SAColumn(Integer, primary_key=True)
+    ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret"))
+    metadata_ = SAColumn(String, type_processor=JSONType())
+    email = SAColumn(String(255))  # No processor = no transformation
+
+# Write - automatic encryption/serialization
+User.insert(ssn="123-45-6789", metadata_={"role": "admin"})
+# SQL: INSERT INTO user (ssn, metadata_) VALUES (?, ?)
+# Params: [encrypt("123-45-6789", "secret"), '{"role": "admin"}']
+
+User.update(ssn="new-ssn").where(User.id == 1)
+# SQL: UPDATE user SET ssn = ? WHERE user.id = ?
+# Params: [encrypt("new-ssn", "secret"), 1]
+
+# Where clauses - automatic transformation
+User.select().where(User.ssn == "123-45-6789")
+# SQL: SELECT * FROM user WHERE user.ssn = ?
+# Params: [encrypt("123-45-6789", "secret")]
+
+# Read - manual decryption/deserialization with map_results()
+query = User.select().where(User.id == 1)
+sql, params = query.render()
+rows = await connection.fetch(sql, *params)  # Returns encrypted/serialized data
+transformed_rows = query.map_results(rows)   # Applies type processors
+# transformed_rows = [{"id": 1, "ssn": "123-45-6789", "metadata_": {"role": "admin"}, ...}]
+```
+
+**Key features:**
+- **Write-side**: Automatically applied in `INSERT`, `UPDATE`, and `WHERE` clauses
+- **Read-side**: Manual via `query.map_results(rows)` - you control when transformation happens
+- **NULL handling**: NULL values are passed through to processors (they decide how to handle)
+- **Column comparisons**: Type processors are NOT applied when comparing columns to other columns
+
+**Why manual read-side transformation?**
+The query builder stays database-agnostic and doesn't execute queries directly. You control when to apply transformations after fetching results from your specific database driver.
 
 ## Schema Support
 

{t_sql-4.2.1 → t_sql-4.4.0}/README.md

@@ -516,6 +516,124 @@ query = Users.select().where(Users.age > 18)
 
 The `SAColumn` wrapper tells type checkers it returns a tsql `Column`, while at runtime it creates a SQLAlchemy `Column`. This gives you proper IDE completions for methods like `.is_null()`, `.like()`, etc.
 
+### Table Constraints
+
+For Alembic migrations, you can define table-level constraints using the `constraints` attribute:
+
+```python
+from sqlalchemy import MetaData, String, UniqueConstraint, CheckConstraint, Index
+from tsql.query_builder import Table, SAColumn
+
+metadata = MetaData()
+
+class Clients(Table, table_name='clients', metadata=metadata):
+    id = SAColumn(String, primary_key=True)
+    tenant_id = SAColumn(String)
+    email = SAColumn(String, nullable=False)
+
+    # Define table-level constraints
+    constraints = [
+        UniqueConstraint('tenant_id', 'email', name='uq_clients_tenant_email'),
+        CheckConstraint('length(email) > 0', name='ck_clients_email_not_empty'),
+        Index('ix_clients_tenant', 'tenant_id')
+    ]
+```
+
+The `constraints` attribute accepts both lists and tuples, and supports all SQLAlchemy constraint types:
+- `UniqueConstraint` - Multi-column unique constraints
+- `CheckConstraint` - Table-level check constraints
+- `Index` - Multi-column indexes
+- `ForeignKeyConstraint` - Table-level foreign keys
+
+**Note:** Single-column constraints like unique indexes and foreign keys can still be defined directly on `SAColumn` (e.g., `SAColumn(String, unique=True, index=True)`).
+
+### Table Comments
+
+Add database-level documentation with the `comment` parameter:
+
+```python
+class Users(Table, metadata=metadata, comment='Application user accounts'):
+    id = SAColumn(Integer, primary_key=True)
+    email = SAColumn(String(255), nullable=False)
+```
+
+Table comments appear in database introspection tools and migration files, making your schema self-documenting.
+
+### Type Processors
+
+Type processors enable automatic value transformation when reading from and writing to the database, similar to SQLAlchemy's `TypeDecorator`. This is useful for encryption, serialization, and custom data transformations.
+
+```python
+from tsql import TypeProcessor
+from tsql.query_builder import Table, SAColumn
+from sqlalchemy import Integer, String, MetaData
+import json
+
+metadata = MetaData()
+
+# Define custom type processors
+class EncryptedString(TypeProcessor):
+    def __init__(self, key):
+        self.key = key
+
+    def process_bind_param(self, value):
+        """Transform Python value -> DB value (encrypt on write)"""
+        if value is None:
+            return None
+        return encrypt(value, self.key)
+
+    def process_result_value(self, value):
+        """Transform DB value -> Python value (decrypt on read)"""
+        if value is None:
+            return None
+        return decrypt(value, self.key)
+
+class JSONType(TypeProcessor):
+    def process_bind_param(self, value):
+        """Serialize Python dict/list -> JSON string"""
+        return json.dumps(value) if value is not None else None
+
+    def process_result_value(self, value):
+        """Deserialize JSON string -> Python dict/list"""
+        return json.loads(value) if value is not None else None
+
+# Use type processors in table definition
+class User(Table, metadata=metadata):
+    id = SAColumn(Integer, primary_key=True)
+    ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret"))
+    metadata_ = SAColumn(String, type_processor=JSONType())
+    email = SAColumn(String(255))  # No processor = no transformation
+
+# Write - automatic encryption/serialization
+User.insert(ssn="123-45-6789", metadata_={"role": "admin"})
+# SQL: INSERT INTO user (ssn, metadata_) VALUES (?, ?)
+# Params: [encrypt("123-45-6789", "secret"), '{"role": "admin"}']
+
+User.update(ssn="new-ssn").where(User.id == 1)
+# SQL: UPDATE user SET ssn = ? WHERE user.id = ?
+# Params: [encrypt("new-ssn", "secret"), 1]
+
+# Where clauses - automatic transformation
+User.select().where(User.ssn == "123-45-6789")
+# SQL: SELECT * FROM user WHERE user.ssn = ?
+# Params: [encrypt("123-45-6789", "secret")]
+
+# Read - manual decryption/deserialization with map_results()
+query = User.select().where(User.id == 1)
+sql, params = query.render()
+rows = await connection.fetch(sql, *params)  # Returns encrypted/serialized data
+transformed_rows = query.map_results(rows)   # Applies type processors
+# transformed_rows = [{"id": 1, "ssn": "123-45-6789", "metadata_": {"role": "admin"}, ...}]
+```
+
+**Key features:**
+- **Write-side**: Automatically applied in `INSERT`, `UPDATE`, and `WHERE` clauses
+- **Read-side**: Manual via `query.map_results(rows)` - you control when transformation happens
+- **NULL handling**: NULL values are passed through to processors (they decide how to handle)
+- **Column comparisons**: Type processors are NOT applied when comparing columns to other columns
+
+**Why manual read-side transformation?**
+The query builder stays database-agnostic and doesn't execute queries directly. You control when to apply transformations after fetching results from your specific database driver.
 
 ## Schema Support
 

{t_sql-4.2.1 → t_sql-4.4.0}/pyproject.toml

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

{t_sql-4.2.1 → t_sql-4.4.0}/tests/test_alembic_integration.py

@@ -360,4 +360,109 @@ def test_alembic_with_schema_parameter(temp_alembic_env):
     assert table.schema == 'public'
 
 
-from sqlalchemy import text as sa_text
+from sqlalchemy import text as sa_text
+
+
+def test_alembic_detects_unique_constraint(temp_alembic_env):
+    """Test that Alembic autogenerate detects UniqueConstraint"""
+    from sqlalchemy import UniqueConstraint
+
+    temp_dir, alembic_ini = temp_alembic_env
+    metadata = MetaData()
+    engine = create_engine("sqlite:///:memory:")
+
+    class Clients(Table, table_name='clients', metadata=metadata):
+        id = Column(String, primary_key=True)
+        tenant_id = Column(String)
+        email = Column(String, nullable=False)
+
+        constraints = [
+            UniqueConstraint('tenant_id', 'email', name='uq_clients_tenant_email')
+        ]
+
+    cfg = Config(str(alembic_ini))
+    cfg.attributes['target_metadata'] = metadata
+    cfg.attributes['connection'] = engine
+
+    with engine.begin() as connection:
+        mc = MigrationContext.configure(connection)
+        diff = compare_metadata(mc, metadata)
+
+    # Should detect the new table
+    add_table_ops = [op for op in diff if op[0] == 'add_table']
+    assert len(add_table_ops) == 1
+
+    table = add_table_ops[0][1]
+    assert table.name == 'clients'
+
+    # Verify the UniqueConstraint is in the table definition
+    unique_constraints = [c for c in table.constraints if isinstance(c, UniqueConstraint)]
+    assert len(unique_constraints) == 1
+
+    uc = unique_constraints[0]
+    assert uc.name == 'uq_clients_tenant_email'
+    assert set(c.name for c in uc.columns) == {'tenant_id', 'email'}
+
+
+def test_alembic_detects_check_constraint(temp_alembic_env):
+    """Test that Alembic autogenerate detects CheckConstraint"""
+    from sqlalchemy import CheckConstraint
+
+    temp_dir, alembic_ini = temp_alembic_env
+    metadata = MetaData()
+    engine = create_engine("sqlite:///:memory:")
+
+    class Products(Table, table_name='products', metadata=metadata):
+        id = Column(Integer, primary_key=True)
+        name = Column(String, nullable=False)
+        price = Column(Integer)
+
+        constraints = [
+            CheckConstraint('price > 0', name='ck_products_positive_price')
+        ]
+
+    cfg = Config(str(alembic_ini))
+    cfg.attributes['target_metadata'] = metadata
+    cfg.attributes['connection'] = engine
+
+    with engine.begin() as connection:
+        mc = MigrationContext.configure(connection)
+        diff = compare_metadata(mc, metadata)
+
+    add_table_ops = [op for op in diff if op[0] == 'add_table']
+    assert len(add_table_ops) == 1
+
+    table = add_table_ops[0][1]
+
+    # Verify the CheckConstraint is in the table definition
+    check_constraints = [c for c in table.constraints if isinstance(c, CheckConstraint)]
+    assert len(check_constraints) == 1
+
+    cc = check_constraints[0]
+    assert cc.name == 'ck_products_positive_price'
+
+
+def test_alembic_detects_table_comment(temp_alembic_env):
+    """Test that Alembic autogenerate preserves table comments"""
+    temp_dir, alembic_ini = temp_alembic_env
+    metadata = MetaData()
+    engine = create_engine("sqlite:///:memory:")
+
+    class Settings(Table, table_name='settings', metadata=metadata, comment='Application configuration'):
+        id = Column(Integer, primary_key=True)
+        key = Column(String, nullable=False)
+        value = Column(String)
+
+    cfg = Config(str(alembic_ini))
+    cfg.attributes['target_metadata'] = metadata
+    cfg.attributes['connection'] = engine
+
+    with engine.begin() as connection:
+        mc = MigrationContext.configure(connection)
+        diff = compare_metadata(mc, metadata)
+
+    add_table_ops = [op for op in diff if op[0] == 'add_table']
+    assert len(add_table_ops) == 1
+
+    table = add_table_ops[0][1]
+    assert table.comment == 'Application configuration'

{t_sql-4.2.1 → t_sql-4.4.0}/tests/test_sqlalchemy_integration.py

@@ -264,3 +264,159 @@ def test_sa_column_annotations_are_correct_type():
 def gen_id(prefix):
     """Dummy function for test"""
     return f"{prefix}_123"
+
+
+def test_table_with_unique_constraint():
+    """Test that UniqueConstraint is properly added to SA table"""
+    from sqlalchemy import UniqueConstraint
+
+    metadata = MetaData()
+
+    class Clients(Table, table_name='clients', metadata=metadata):
+        id = Column(String, primary_key=True)
+        tenant_id = Column(String, ForeignKey('tenants.id'))
+        email = Column(String, nullable=False)
+
+        constraints = [
+            UniqueConstraint('tenant_id', 'email', name='uq_clients_tenant_email')
+        ]
+
+    assert 'clients' in metadata.tables
+    sa_table = metadata.tables['clients']
+
+    # Find the unique constraint
+    unique_constraints = [c for c in sa_table.constraints if isinstance(c, UniqueConstraint)]
+    assert len(unique_constraints) == 1
+
+    uc = unique_constraints[0]
+    assert uc.name == 'uq_clients_tenant_email'
+    assert set(c.name for c in uc.columns) == {'tenant_id', 'email'}
+
+    # Query builder still works
+    query = Clients.select(Clients.id, Clients.email)
+    sql, params = query.render()
+    assert 'SELECT clients.id, clients.email FROM clients' in sql
+
+
+def test_table_with_check_constraint():
+    """Test that CheckConstraint is properly added to SA table"""
+    from sqlalchemy import CheckConstraint
+
+    metadata = MetaData()
+
+    class Products(Table, table_name='products', metadata=metadata):
+        id = Column(Integer, primary_key=True)
+        name = Column(String, nullable=False)
+        price = Column(Integer)
+
+        constraints = [
+            CheckConstraint('price > 0', name='ck_products_positive_price')
+        ]
+
+    sa_table = metadata.tables['products']
+
+    # Find the check constraint
+    check_constraints = [c for c in sa_table.constraints if isinstance(c, CheckConstraint)]
+    assert len(check_constraints) == 1
+
+    cc = check_constraints[0]
+    assert cc.name == 'ck_products_positive_price'
+
+
+def test_table_with_multiple_constraints():
+    """Test that multiple constraints can be added together"""
+    from sqlalchemy import UniqueConstraint, CheckConstraint, Index
+
+    metadata = MetaData()
+
+    class Orders(Table, table_name='orders', metadata=metadata):
+        id = Column(String, primary_key=True)
+        user_id = Column(String, nullable=False)
+        order_number = Column(String, nullable=False)
+        amount = Column(Integer)
+        status = Column(String)
+
+        constraints = [
+            UniqueConstraint('order_number', name='uq_orders_order_number'),
+            CheckConstraint('amount >= 0', name='ck_orders_non_negative_amount'),
+            Index('ix_orders_user_status', 'user_id', 'status')
+        ]
+
+    sa_table = metadata.tables['orders']
+
+    # Verify all constraints are present
+    unique_constraints = [c for c in sa_table.constraints if isinstance(c, UniqueConstraint)]
+    check_constraints = [c for c in sa_table.constraints if isinstance(c, CheckConstraint)]
+
+    assert len(unique_constraints) == 1
+    assert len(check_constraints) == 1
+
+    # Verify index
+    assert len(sa_table.indexes) == 1
+    idx = list(sa_table.indexes)[0]
+    assert idx.name == 'ix_orders_user_status'
+
+
+def test_table_with_constraints_as_tuple():
+    """Test that constraints attribute works with tuple format"""
+    from sqlalchemy import UniqueConstraint
+
+    metadata = MetaData()
+
+    class Items(Table, table_name='items', metadata=metadata):
+        id = Column(Integer, primary_key=True)
+        category = Column(String)
+        code = Column(String)
+
+        constraints = (
+            UniqueConstraint('category', 'code', name='uq_items_category_code'),
+        )
+
+    sa_table = metadata.tables['items']
+
+    unique_constraints = [c for c in sa_table.constraints if isinstance(c, UniqueConstraint)]
+    assert len(unique_constraints) == 1
+    assert unique_constraints[0].name == 'uq_items_category_code'
+
+
+def test_table_with_comment():
+    """Test that comment parameter is passed to SQLAlchemy table"""
+    metadata = MetaData()
+
+    class Settings(Table, table_name='settings', metadata=metadata, comment='Application settings and configuration'):
+        id = Column(Integer, primary_key=True)
+        key = Column(String, nullable=False)
+        value = Column(String)
+
+    sa_table = metadata.tables['settings']
+    assert sa_table.comment == 'Application settings and configuration'
+
+
+def test_table_with_constraints_and_comment():
+    """Test that both constraints and comment work together"""
+    from sqlalchemy import UniqueConstraint
+
+    metadata = MetaData()
+
+    class ApiKeys(Table, table_name='api_keys', metadata=metadata, comment='API authentication keys'):
+        id = Column(String, primary_key=True)
+        user_id = Column(String, nullable=False)
+        key_hash = Column(String, nullable=False)
+
+        constraints = [
+            UniqueConstraint('key_hash', name='uq_api_keys_key_hash')
+        ]
+
+    sa_table = metadata.tables['api_keys']
+
+    assert sa_table.comment == 'API authentication keys'
+
+    unique_constraints = [c for c in sa_table.constraints if isinstance(c, UniqueConstraint)]
+    assert len(unique_constraints) == 1
+    assert unique_constraints[0].name == 'uq_api_keys_key_hash'
+
+    # Query builder still works
+    query = ApiKeys.select().where(ApiKeys.user_id == 'user123')
+    sql, params = query.render()
+    assert 'WHERE api_keys.user_id = ?' in sql
+    assert params == ['user123']