t-sql 4.0.0__tar.gz → 4.2.0__tar.gz

{t_sql-4.0.0 → t_sql-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 4.0.0
+Version: 4.2.0
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE
@@ -495,7 +495,7 @@ uv add t-sql --optional sqlalchemy
 **1. Simple Column annotations** (for query builder only):
 
 ```python
-from tsql import Table, Column
+from tsql.query_builder import Table, Column
 
 class Users(Table):
     id: Column
@@ -503,38 +503,29 @@ class Users(Table):
     age: Column
 ```
 
-**2. SQLAlchemy Column objects** (for alembic integration):
+**2. SQLAlchemy with SAColumn wrapper** (recommended for type checkers):
 
 ```python
-from sqlalchemy import MetaData, Column, String, Integer, ForeignKey
-from tsql.query_builder import Table
+from sqlalchemy import MetaData, Integer, String
+from tsql.query_builder import Table, SAColumn
 
 metadata = MetaData()
 
 class Users(Table, metadata=metadata):
-    id = Column(String, primary_key=True)
-    email = Column(String(255), unique=True, nullable=False)
-    name = Column(String(100))
-    age = Column(Integer)
+    id = SAColumn(Integer, primary_key=True)
+    email = SAColumn(String(255), unique=True, nullable=False)
+    name = SAColumn(String(100))
+    age = SAColumn(Integer)
 
 # Use for alembic
 target_metadata = metadata
 
-# Use for queries (works identically!)
+# Use for queries
 query = Users.select().where(Users.age > 18)
 ```
 
-You can mix both approaches:
-
-```python
-from sqlalchemy import Column, String, DateTime
-from sqlalchemy.sql.functions import now
+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.
 
-class Events(Table, metadata=metadata):
-    id = Column(String, primary_key=True)
-    topic: Column  # Simple annotation - becomes nullable String column
-    created_at = Column(DateTime, server_default=now())
-```
 
 ## Schema Support
 

{t_sql-4.0.0 → t_sql-4.2.0}/README.md

@@ -485,7 +485,7 @@ uv add t-sql --optional sqlalchemy
 **1. Simple Column annotations** (for query builder only):
 
 ```python
-from tsql import Table, Column
+from tsql.query_builder import Table, Column
 
 class Users(Table):
     id: Column
@@ -493,38 +493,29 @@ class Users(Table):
     age: Column
 ```
 
-**2. SQLAlchemy Column objects** (for alembic integration):
+**2. SQLAlchemy with SAColumn wrapper** (recommended for type checkers):
 
 ```python
-from sqlalchemy import MetaData, Column, String, Integer, ForeignKey
-from tsql.query_builder import Table
+from sqlalchemy import MetaData, Integer, String
+from tsql.query_builder import Table, SAColumn
 
 metadata = MetaData()
 
 class Users(Table, metadata=metadata):
-    id = Column(String, primary_key=True)
-    email = Column(String(255), unique=True, nullable=False)
-    name = Column(String(100))
-    age = Column(Integer)
+    id = SAColumn(Integer, primary_key=True)
+    email = SAColumn(String(255), unique=True, nullable=False)
+    name = SAColumn(String(100))
+    age = SAColumn(Integer)
 
 # Use for alembic
 target_metadata = metadata
 
-# Use for queries (works identically!)
+# Use for queries
 query = Users.select().where(Users.age > 18)
 ```
 
-You can mix both approaches:
-
-```python
-from sqlalchemy import Column, String, DateTime
-from sqlalchemy.sql.functions import now
+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.
 
-class Events(Table, metadata=metadata):
-    id = Column(String, primary_key=True)
-    topic: Column  # Simple annotation - becomes nullable String column
-    created_at = Column(DateTime, server_default=now())
-```
 
 ## Schema Support
 

{t_sql-4.0.0 → t_sql-4.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "t-sql"
-version = "4.0.0"
+version = "4.2.0"
 description = "Safe SQL. SQL queries for python t-strings (PEP 750)"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -23,9 +23,12 @@ dev = [
     "anyio>=4.9.0",
     "asyncpg>=0.30.0",
     "cryptography>=46.0.2",
+    "mypy>=1.18.2",
+    "pyright>=1.1.406",
     "pytest>=8.3.5",
     "pytest-asyncio>=0.24.0",
     "sqlalchemy>=2.0.0",
+    "ty>=0.0.1a23",
 ]
 
 [tool.hatch.build.targets.wheel]

{t_sql-4.0.0 → t_sql-4.2.0}/tsql/query_builder.py

@@ -38,7 +38,7 @@ class OrderByClause:
 class Column:
     """Represents a bound column (table + column name) for building queries"""
 
-    def __init__(self, table_name: str = None, column_name: str = None, alias: str = None, schema: str = None):
+    def __init__(self, table_name: str | None = None, column_name: str | None = None, alias: str | None = None, schema: str | None = None):
         self.table_name = table_name
         self.column_name = column_name
         self.alias = alias
@@ -194,13 +194,22 @@ class Table:
         class Users(Table, table_name='user_accounts'):
             id: Column
 
-    For SQLAlchemy integration, use SQLAlchemy Column objects:
+    For SQLAlchemy integration, use the SAColumn wrapper for type checker compatibility:
 
-        from sqlalchemy import Column, Integer, String
+        from sqlalchemy import Integer, String
+        from tsql.query_builder import Table, SAColumn
 
         class Users(Table, metadata=metadata, schema='public'):
-            id = Column(Integer, primary_key=True)
-            name = Column(String(100))
+            id = SAColumn(Integer, primary_key=True)
+            name = SAColumn(String(100))
+
+    Alternative: Use explicit type annotations with SQLAlchemy Column:
+
+        from sqlalchemy import Column as SACol
+
+        class Users(Table, metadata=metadata):
+            id: Column = SACol(Integer, primary_key=True)
+            name: Column = SACol(String(100))
     """
     table_name: ClassVar[str]
     schema: ClassVar[Optional[str]] = None
@@ -231,7 +240,7 @@ class Table:
                 continue
             field_value = getattr(cls, field_name, None)
 
-            # Check for Ellipsis syntax: id = ...
+            # Check for Ellipsis syntax: id = ...~
             if field_value is ...:
                 if field_name not in all_fields:
                     all_fields[field_name] = {
@@ -267,9 +276,9 @@ class Table:
                     sa_col.name = field_name
                     sa_columns.append(sa_col)
 
-                # Create query builder ColumnDescriptor
-                setattr(cls, field_name, ColumnDescriptor(field_name))
-                # Update annotation to reflect the descriptor's return type
+                # Create query builder Column directly
+                setattr(cls, field_name, Column(cls.table_name, field_name, schema=schema))
+                # Update annotation to reflect the Column type
                 if not hasattr(cls, '__annotations__'):
                     cls.__annotations__ = {}
                 cls.__annotations__[field_name] = Column
@@ -283,9 +292,9 @@ class Table:
                     # No column_name specified, use field_name
                     db_column_name = field_name
 
-                # Create query builder ColumnDescriptor with the DB column name
-                setattr(cls, field_name, ColumnDescriptor(db_column_name))
-                # Update annotation to reflect the descriptor's return type
+                # Create query builder Column directly with the DB column name
+                setattr(cls, field_name, Column(cls.table_name, db_column_name, schema=schema))
+                # Update annotation to reflect the Column type
                 if not hasattr(cls, '__annotations__'):
                     cls.__annotations__ = {}
                 cls.__annotations__[field_name] = Column
@@ -298,9 +307,9 @@ class Table:
 
             # Check if it's an Ellipsis (...) declaration
             if field_value is ...:
-                # Create query builder ColumnDescriptor
-                setattr(cls, field_name, ColumnDescriptor(field_name))
-                # Update annotation to reflect the descriptor's return type
+                # Create query builder Column directly
+                setattr(cls, field_name, Column(cls.table_name, field_name, schema=schema))
+                # Update annotation to reflect the Column type
                 if not hasattr(cls, '__annotations__'):
                     cls.__annotations__ = {}
                 cls.__annotations__[field_name] = Column
@@ -311,9 +320,9 @@ class Table:
                 # No type annotation, Ellipsis, or SA Column - skip
                 continue
 
-            # Create query builder ColumnDescriptor for type-annotated fields
-            setattr(cls, field_name, ColumnDescriptor(field_name))
-            # Update annotation to reflect the descriptor's return type
+            # Create query builder Column directly for type-annotated fields
+            setattr(cls, field_name, Column(cls.table_name, field_name, schema=schema))
+            # Update annotation to reflect the Column type
             if not hasattr(cls, '__annotations__'):
                 cls.__annotations__ = {}
             cls.__annotations__[field_name] = Column
@@ -327,8 +336,8 @@ class Table:
         if metadata is not None and HAS_SQLALCHEMY:
             cls._sa_table = SATable(cls.table_name, metadata, *sa_columns, schema=schema)
 
-        # Add the ALL descriptor for wildcard column selection
-        cls.ALL = AllColumnsDescriptor()
+        # Add the ALL column for wildcard column selection
+        cls.ALL = Column(cls.table_name, '*', schema=schema)
 
     @classmethod
     def select(cls, *columns: Union['Column', Template]) -> 'SelectQueryBuilder':
@@ -380,32 +389,6 @@ class Table:
         return DeleteBuilder(cls)
 
 
-class ColumnDescriptor:
-    """Descriptor that creates Column objects when accessed on Table classes or instances"""
-
-    def __init__(self, column_name: str):
-        self.column_name = column_name
-
-    def __set_name__(self, owner, name):
-        self.column_name = name
-
-    def __get__(self, obj, objtype=None) -> Column:
-        if objtype is None:
-            objtype = type(obj)
-        schema = getattr(objtype, 'schema', None)
-        return Column(objtype.table_name, self.column_name, schema=schema)
-
-
-class AllColumnsDescriptor:
-    """Descriptor that creates a Column with wildcard (*) for selecting all columns from a table"""
-
-    def __get__(self, obj, objtype=None) -> Column:
-        if objtype is None:
-            objtype = type(obj)
-        schema = getattr(objtype, 'schema', None)
-        return Column(objtype.table_name, '*', schema=schema)
-
-
 class Condition:
     """Represents a WHERE clause condition"""
 
@@ -469,7 +452,7 @@ class Condition:
 class Join:
     """Represents a JOIN clause"""
 
-    def __init__(self, table: 'Table', condition: Condition, join_type: str = 'INNER'):
+    def __init__(self, table: type['Table'], condition: Condition, join_type: str = 'INNER'):
         self.table = table
         self.condition = condition
         self.join_type = join_type
@@ -512,7 +495,7 @@ class QueryBuilder(ABC):
 class InsertBuilder(QueryBuilder):
     """Fluent interface for building INSERT queries"""
 
-    def __init__(self, base_table: 'Table', values: dict[str, Any]):
+    def __init__(self, base_table: type['Table'], values: dict[str, Any]):
         self.base_table = base_table
 
         # Apply defaults from SQLAlchemy columns if available
@@ -580,13 +563,23 @@ class InsertBuilder(QueryBuilder):
         self._update_cols = update
         return self
 
-    def returning(self, *columns: str) -> 'InsertBuilder':
+    def returning(self, *columns: Union[str, Column]) -> 'InsertBuilder':
         """Add RETURNING clause (Postgres/SQLite only)
 
         Args:
-            columns: Column names to return, or none for RETURNING *
+            columns: Column names (strings) or Column objects to return, or none for RETURNING *
         """
-        self._returning_cols = list(columns) if columns else ['*']
+        if columns:
+            # Convert Column objects to their column names
+            col_names = []
+            for col in columns:
+                if isinstance(col, Column):
+                    col_names.append(col.column_name)
+                else:
+                    col_names.append(col)
+            self._returning_cols = col_names
+        else:
+            self._returning_cols = ['*']
         return self
 
     def to_tsql(self) -> TSQL:
@@ -694,7 +687,7 @@ class InsertBuilder(QueryBuilder):
 class UpdateBuilder(QueryBuilder):
     """Fluent interface for building UPDATE queries"""
 
-    def __init__(self, base_table: 'Table', values: dict[str, Any]):
+    def __init__(self, base_table: type['Table'], values: dict[str, Any]):
         self.base_table = base_table
 
         # Apply onupdate defaults from SQLAlchemy columns if available
@@ -743,13 +736,23 @@ class UpdateBuilder(QueryBuilder):
         self._requires_where = False
         return self
 
-    def returning(self, *columns: str) -> 'UpdateBuilder':
+    def returning(self, *columns: Union[str, Column]) -> 'UpdateBuilder':
         """Add RETURNING clause (Postgres/SQLite only)
 
         Args:
-            columns: Column names to return, or none for RETURNING *
+            columns: Column names (strings) or Column objects to return, or none for RETURNING *
         """
-        self._returning_cols = list(columns) if columns else ['*']
+        if columns:
+            # Convert Column objects to their column names
+            col_names = []
+            for col in columns:
+                if isinstance(col, Column):
+                    col_names.append(col.column_name)
+                else:
+                    col_names.append(col)
+            self._returning_cols = col_names
+        else:
+            self._returning_cols = ['*']
         return self
 
     def to_tsql(self) -> TSQL:
@@ -807,7 +810,7 @@ class UpdateBuilder(QueryBuilder):
 class DeleteBuilder(QueryBuilder):
     """Fluent interface for building DELETE queries"""
 
-    def __init__(self, base_table: 'Table'):
+    def __init__(self, base_table: type['Table']):
         self.base_table = base_table
         self._conditions: List[Union[Condition, Template]] = []
         self._returning_cols: Optional[List[str]] = None
@@ -834,13 +837,23 @@ class DeleteBuilder(QueryBuilder):
         self._requires_where = False
         return self
 
-    def returning(self, *columns: str) -> 'DeleteBuilder':
+    def returning(self, *columns: Union[str, Column]) -> 'DeleteBuilder':
         """Add RETURNING clause (Postgres/SQLite only)
 
         Args:
-            columns: Column names to return, or none for RETURNING *
+            columns: Column names (strings) or Column objects to return, or none for RETURNING *
         """
-        self._returning_cols = list(columns) if columns else ['*']
+        if columns:
+            # Convert Column objects to their column names
+            col_names = []
+            for col in columns:
+                if isinstance(col, Column):
+                    col_names.append(col.column_name)
+                else:
+                    col_names.append(col)
+            self._returning_cols = col_names
+        else:
+            self._returning_cols = ['*']
         return self
 
     def to_tsql(self) -> TSQL:
@@ -897,7 +910,7 @@ class DeleteBuilder(QueryBuilder):
 class SelectQueryBuilder(QueryBuilder):
     """Fluent interface for building SQL SELECT queries"""
 
-    def __init__(self, base_table: 'Table'):
+    def __init__(self, base_table: type['Table']):
         self.base_table = base_table
         self._columns: Optional[List[Column]] = None
         self._conditions: List[Condition] = []
@@ -935,16 +948,16 @@ class SelectQueryBuilder(QueryBuilder):
         self._conditions.append(condition)
         return self
 
-    def join(self, table: 'Table', on: Condition, join_type: str = 'INNER') -> 'SelectQueryBuilder':
+    def join(self, table: type['Table'], on: Condition, join_type: str = 'INNER') -> 'SelectQueryBuilder':
         """Add a JOIN clause"""
         self._joins.append(Join(table, on, join_type))
         return self
 
-    def left_join(self, table: 'Table', on: Condition) -> 'SelectQueryBuilder':
+    def left_join(self, table: type['Table'], on: Condition) -> 'SelectQueryBuilder':
         """Add a LEFT JOIN clause"""
         return self.join(table, on, 'LEFT')
 
-    def right_join(self, table: 'Table', on: Condition) -> 'SelectQueryBuilder':
+    def right_join(self, table: type['Table'], on: Condition) -> 'SelectQueryBuilder':
         """Add a RIGHT JOIN clause"""
         return self.join(table, on, 'RIGHT')
 
@@ -1083,3 +1096,32 @@ if HAS_SQLALCHEMY:
         datetime: DateTime,
         float: Float,
     }
+
+
+# Helper function for type checker compatibility with SQLAlchemy columns
+def SAColumn(*args: Any, **kwargs: Any) -> Column:  # noqa: N802
+    """Wrapper for SQLAlchemy Column that satisfies type checkers.
+
+    This function returns a SQLAlchemy Column at runtime but tells type checkers
+    it returns a tsql Column. This allows you to use SQLAlchemy columns without
+    explicit type annotations while still getting proper IDE completions.
+
+    Usage:
+        from tsql.query_builder import Table, SAColumn
+        from sqlalchemy import Integer, String
+
+        class Users(Table):
+            id = SAColumn(Integer, primary_key=True)  # Type checker sees: tsql Column
+            name = SAColumn(String(100))
+
+    Note: This shadows the SQLAlchemy Column import. Import SA Column explicitly if needed:
+        from sqlalchemy import Column as SA_Column
+
+    Alternative: Use explicit type annotations:
+        from sqlalchemy import Column as SACol
+        id: Column = SACol(Integer, primary_key=True)
+    """
+    if not HAS_SQLALCHEMY:
+        raise ImportError("SQLAlchemy is not installed. Cannot use SAColumn() helper.")
+    from sqlalchemy import Column as SA_Column
+    return SA_Column(*args, **kwargs)  # type: ignore[return-value]