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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 4.2.1
+Version: 4.3.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,48 @@ 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.
 
 ## Schema Support
 

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

@@ -516,6 +516,48 @@ 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.
 
 ## Schema Support
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "t-sql"
-version = "4.2.1"
+version = "4.3.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.3.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.3.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']

{t_sql-4.2.1 → t_sql-4.3.0}/tsql/query_builder.py

@@ -210,11 +210,30 @@ class Table:
         class Users(Table, metadata=metadata):
             id: Column = SACol(Integer, primary_key=True)
             name: Column = SACol(String(100))
+
+    Table-level constraints (for SQLAlchemy/Alembic migrations):
+
+        from sqlalchemy import UniqueConstraint, CheckConstraint
+
+        class Users(Table, metadata=metadata):
+            id = SAColumn(String, primary_key=True)
+            tenant_id = SAColumn(String)
+            email = SAColumn(String)
+
+            constraints = [
+                UniqueConstraint('tenant_id', 'email', name='uq_users_tenant_email'),
+                CheckConstraint('length(email) > 0', name='ck_users_email_not_empty')
+            ]
+
+    Table comment (for database documentation in migrations):
+
+        class Users(Table, metadata=metadata, comment='Application user accounts'):
+            id = SAColumn(Integer, primary_key=True)
     """
     table_name: ClassVar[str]
     schema: ClassVar[Optional[str]] = None
 
-    def __init_subclass__(cls, table_name: Optional[str] = None, metadata: Optional[Any] = None, schema: Optional[str] = None, **kwargs):
+    def __init_subclass__(cls, table_name: Optional[str] = None, metadata: Optional[Any] = None, schema: Optional[str] = None, comment: Optional[str] = None, **kwargs):
         super().__init_subclass__(**kwargs)
 
         # Set table_name: use provided name, or default to lowercase class name
@@ -334,7 +353,17 @@ class Table:
 
         # Create SQLAlchemy Table if metadata provided
         if metadata is not None and HAS_SQLALCHEMY:
-            cls._sa_table = SATable(cls.table_name, metadata, *sa_columns, schema=schema)
+            # Extract constraints from class attribute (supports both tuple and list)
+            table_constraints = getattr(cls, 'constraints', [])
+            if isinstance(table_constraints, tuple):
+                table_constraints = list(table_constraints)
+
+            # Build keyword args for SATable
+            table_kwargs = {'schema': schema}
+            if comment is not None:
+                table_kwargs['comment'] = comment
+
+            cls._sa_table = SATable(cls.table_name, metadata, *sa_columns, *table_constraints, **table_kwargs)
 
         # Add the ALL column for wildcard column selection
         cls.ALL = Column(cls.table_name, '*', schema=schema)