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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: t-sql
-Version: 4.3.0
+Version: 4.4.1
 Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
 Project-URL: Homepage, https://github.com/nhumrich/t-sql
 License-File: LICENSE
@@ -569,6 +569,82 @@ class Users(Table, metadata=metadata, comment='Application user accounts'):
 
 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
 
 ```python

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

@@ -559,6 +559,82 @@ class Users(Table, metadata=metadata, comment='Application user accounts'):
 
 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
 
 ```python

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

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

t_sql-4.4.1/tests/test_type_processor.py

@@ -0,0 +1,260 @@
+import json
+import pytest
+from tsql import TypeProcessor
+from tsql.query_builder import Table, SAColumn
+
+try:
+    from sqlalchemy import Integer, String, MetaData
+    HAS_SQLALCHEMY = True
+except ImportError:
+    HAS_SQLALCHEMY = False
+
+
+class EncryptedString(TypeProcessor):
+    """Simple encryption simulator for testing"""
+
+    def __init__(self, key: str):
+        self.key = key
+
+    def process_bind_param(self, value):
+        if value is None:
+            return None
+        return f"encrypted_{value}_{self.key}"
+
+    def process_result_value(self, value):
+        if value is None:
+            return None
+        if value.startswith(f"encrypted_") and value.endswith(f"_{self.key}"):
+            return value[len(f"encrypted_"):-len(f"_{self.key}")]
+        return value
+
+
+class JSONType(TypeProcessor):
+    """JSON serialization for testing"""
+
+    def process_bind_param(self, value):
+        if value is None:
+            return None
+        return json.dumps(value)
+
+    def process_result_value(self, value):
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return json.loads(value)
+        return value
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_insert_with_type_processor():
+    """Test that type processors are applied during INSERT"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+        metadata_ = SAColumn(String, type_processor=JSONType())
+
+    # Build insert query
+    query = User.insert(id=1, ssn="123-45-6789", metadata_={"foo": "bar"})
+    sql, params = query.render()
+
+    # Check that values were transformed
+    assert params[1] == "encrypted_123-45-6789_secret123"
+    assert params[2] == '{"foo": "bar"}'
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_update_with_type_processor():
+    """Test that type processors are applied during UPDATE"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+
+    # Build update query
+    query = User.update(ssn="new-ssn").where(User.id == 1)
+    sql, params = query.render()
+
+    # Check that value was transformed
+    assert "encrypted_new-ssn_secret123" in params
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_where_clause_with_type_processor():
+    """Test that type processors are applied in WHERE clauses"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+
+    # Build select query with WHERE
+    query = User.select().where(User.ssn == "123-45-6789")
+    sql, params = query.render()
+
+    # Check that value was transformed
+    assert params[0] == "encrypted_123-45-6789_secret123"
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_in_clause_with_type_processor():
+    """Test that type processors are applied to IN clause values"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+
+    # Build select query with IN
+    query = User.select().where(User.ssn.in_(["123-45-6789", "987-65-4321"]))
+    sql, params = query.render()
+
+    # Check that values were transformed
+    assert params[0] == "encrypted_123-45-6789_secret123"
+    assert params[1] == "encrypted_987-65-4321_secret123"
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_between_with_type_processor():
+    """Test that type processors are applied to BETWEEN values"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        score = SAColumn(Integer, type_processor=EncryptedString(key="secret123"))
+
+    # Build select query with BETWEEN
+    query = User.select().where(User.score.between(10, 20))
+    sql, params = query.render()
+
+    # Check that values were transformed
+    assert params[0] == "encrypted_10_secret123"
+    assert params[1] == "encrypted_20_secret123"
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_map_results():
+    """Test that map_results applies type processors to query results"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+        metadata_ = SAColumn(String, type_processor=JSONType())
+
+    # Simulate database results
+    rows = [
+        {"id": 1, "ssn": "encrypted_123-45-6789_secret123", "metadata_": '{"foo": "bar"}'},
+        {"id": 2, "ssn": "encrypted_987-65-4321_secret123", "metadata_": '{"baz": "qux"}'},
+    ]
+
+    # Build query and map results
+    query = User.select()
+    transformed_rows = query.map_results(rows)
+
+    # Check that values were decrypted/deserialized
+    assert transformed_rows[0]["ssn"] == "123-45-6789"
+    assert transformed_rows[0]["metadata_"] == {"foo": "bar"}
+    assert transformed_rows[1]["ssn"] == "987-65-4321"
+    assert transformed_rows[1]["metadata_"] == {"baz": "qux"}
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_null_handling():
+    """Test that NULL values are passed through to processors"""
+    metadata = MetaData()
+
+    class NullAwareProcessor(TypeProcessor):
+        def process_bind_param(self, value):
+            if value is None:
+                return "NULL_MARKER"
+            return value
+
+        def process_result_value(self, value):
+            if value == "NULL_MARKER":
+                return None
+            return value
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        optional_field = SAColumn(String, type_processor=NullAwareProcessor())
+
+    # Test insert with None
+    query = User.insert(id=1, optional_field=None)
+    sql, params = query.render()
+    assert params[1] == "NULL_MARKER"
+
+    # Test map_results with marker
+    rows = [{"id": 1, "optional_field": "NULL_MARKER"}]
+    query = User.select()
+    transformed_rows = query.map_results(rows)
+    assert transformed_rows[0]["optional_field"] is None
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_on_conflict_with_type_processor():
+    """Test that type processors are applied in ON CONFLICT UPDATE"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+
+    # Build insert with on_conflict_update
+    query = User.insert(id=1, ssn="123-45-6789").on_conflict_update(
+        conflict_on="id",
+        update={"ssn": "new-ssn"}
+    )
+    sql, params = query.render()
+
+    # Check that both insert and update values were transformed
+    assert "encrypted_123-45-6789_secret123" in params
+    assert "encrypted_new-ssn_secret123" in params
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_comparison_operators_with_type_processor():
+    """Test that all comparison operators apply type processors"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        score = SAColumn(Integer, type_processor=EncryptedString(key="secret123"))
+
+    # Test various operators
+    ops = [
+        (User.score == 100, "encrypted_100_secret123"),
+        (User.score != 100, "encrypted_100_secret123"),
+        (User.score < 100, "encrypted_100_secret123"),
+        (User.score <= 100, "encrypted_100_secret123"),
+        (User.score > 100, "encrypted_100_secret123"),
+        (User.score >= 100, "encrypted_100_secret123"),
+        (User.score.like("10%"), "encrypted_10%_secret123"),
+        (User.score.not_like("10%"), "encrypted_10%_secret123"),
+    ]
+
+    for condition, expected_value in ops:
+        query = User.select().where(condition)
+        sql, params = query.render()
+        assert expected_value in params, f"Failed for condition: {condition}"
+
+
+@pytest.mark.skipif(not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_type_processor_not_applied_to_column_comparisons():
+    """Test that type processors are NOT applied when comparing columns to columns"""
+    metadata = MetaData()
+
+    class User(Table, metadata=metadata):
+        id = SAColumn(Integer, primary_key=True)
+        ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+        backup_ssn = SAColumn(String(255), type_processor=EncryptedString(key="secret123"))
+
+    # Build query comparing two columns
+    query = User.select().where(User.ssn == User.backup_ssn)
+    sql, params = query.render()
+
+    # No parameters should be generated (column-to-column comparison)
+    assert len(params) == 0
+    assert "user.ssn = user.backup_ssn" in sql

{t_sql-4.3.0 → t_sql-4.4.1}/tsql/__init__.py

@@ -361,6 +361,7 @@ def delete(table: str, id: str | int) -> TSQL:
 
 
 from tsql.query_builder import UnsafeQueryError
+from tsql.type_processor import TypeProcessor
 
 __all__ = [
     'TSQL',
@@ -373,5 +374,6 @@ __all__ = [
     'delete',
     'set_style',
     'UnsafeQueryError',
+    'TypeProcessor',
 ]
 

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

@@ -38,11 +38,12 @@ class OrderByClause:
 class Column:
     """Represents a bound column (table + column name) for building queries"""
 
-    def __init__(self, table_name: str | None = None, column_name: str | None = None, alias: str | None = None, schema: str | None = None):
+    def __init__(self, table_name: str | None = None, column_name: str | None = None, alias: str | None = None, schema: str | None = None, type_processor: Any | None = None):
         self.table_name = table_name
         self.column_name = column_name
         self.alias = alias
         self.schema = schema
+        self.type_processor = type_processor
 
     def __str__(self) -> str:
         if self.schema:
@@ -70,29 +71,48 @@ class Column:
         Example:
             users.select(users.first_name.as_('first'), users.last_name.as_('last'))
         """
-        return Column(self.table_name, self.column_name, alias, self.schema)
+        return Column(self.table_name, self.column_name, alias, self.schema, self.type_processor)
+
+    def _process_value(self, value: Any) -> Any:
+        """Apply type processor to a comparison value if one is configured.
+
+        Args:
+            value: The value to process
+
+        Returns:
+            The processed value (or unchanged if no processor or value is special type)
+        """
+        # Don't process special types
+        if value is None or isinstance(value, (Column, Template)) or hasattr(value, 'to_tsql'):
+            return value
+
+        # Apply processor if present
+        if self.type_processor is not None:
+            return self.type_processor.process_bind_param(value)
+
+        return value
 
     def __eq__(self, other) -> 'Condition':
         if other is None:
             return Condition(self, 'IS', None)
-        return Condition(self, '=', other)
+        return Condition(self, '=', self._process_value(other))
 
     def __ne__(self, other) -> 'Condition':
         if other is None:
             return Condition(self, 'IS NOT', None)
-        return Condition(self, '!=', other)
+        return Condition(self, '!=', self._process_value(other))
 
     def __lt__(self, other) -> 'Condition':
-        return Condition(self, '<', other)
+        return Condition(self, '<', self._process_value(other))
 
     def __le__(self, other) -> 'Condition':
-        return Condition(self, '<=', other)
+        return Condition(self, '<=', self._process_value(other))
 
     def __gt__(self, other) -> 'Condition':
-        return Condition(self, '>', other)
+        return Condition(self, '>', self._process_value(other))
 
     def __ge__(self, other) -> 'Condition':
-        return Condition(self, '>=', other)
+        return Condition(self, '>=', self._process_value(other))
 
     def in_(self, values: Union[list, tuple, 'Column', Template, 'SelectQueryBuilder']) -> 'Condition':
         """Create an IN condition
@@ -101,7 +121,9 @@ class Column:
             values: List/tuple of values, a Column, a Template (t-string), or a SelectQueryBuilder for subqueries
         """
         if isinstance(values, (list, tuple)):
-            return Condition(self, 'IN', tuple(values))
+            # Process each value in the tuple/list
+            processed_values = tuple(self._process_value(v) for v in values)
+            return Condition(self, 'IN', processed_values)
         return Condition(self, 'IN', values)
 
     def not_in(self, values: Union[list, tuple, 'Column', Template, 'SelectQueryBuilder']) -> 'Condition':
@@ -111,24 +133,26 @@ class Column:
             values: List/tuple of values, a Column, a Template (t-string), or a SelectQueryBuilder for subqueries
         """
         if isinstance(values, (list, tuple)):
-            return Condition(self, 'NOT IN', tuple(values))
+            # Process each value in the tuple/list
+            processed_values = tuple(self._process_value(v) for v in values)
+            return Condition(self, 'NOT IN', processed_values)
         return Condition(self, 'NOT IN', values)
 
     def like(self, pattern: str) -> 'Condition':
         """Create a LIKE condition"""
-        return Condition(self, 'LIKE', pattern)
+        return Condition(self, 'LIKE', self._process_value(pattern))
 
     def not_like(self, pattern: str) -> 'Condition':
         """Create a NOT LIKE condition"""
-        return Condition(self, 'NOT LIKE', pattern)
+        return Condition(self, 'NOT LIKE', self._process_value(pattern))
 
     def ilike(self, pattern: str) -> 'Condition':
         """Create an ILIKE condition (case-insensitive, PostgreSQL/SQLite only)"""
-        return Condition(self, 'ILIKE', pattern)
+        return Condition(self, 'ILIKE', self._process_value(pattern))
 
     def not_ilike(self, pattern: str) -> 'Condition':
         """Create a NOT ILIKE condition (case-insensitive, PostgreSQL/SQLite only)"""
-        return Condition(self, 'NOT ILIKE', pattern)
+        return Condition(self, 'NOT ILIKE', self._process_value(pattern))
 
     def between(self, start: Any, end: Any) -> 'Condition':
         """Create a BETWEEN condition
@@ -137,7 +161,7 @@ class Column:
             start: Lower bound value
             end: Upper bound value
         """
-        return Condition(self, 'BETWEEN', (start, end))
+        return Condition(self, 'BETWEEN', (self._process_value(start), self._process_value(end)))
 
     def not_between(self, start: Any, end: Any) -> 'Condition':
         """Create a NOT BETWEEN condition
@@ -146,7 +170,7 @@ class Column:
             start: Lower bound value
             end: Upper bound value
         """
-        return Condition(self, 'NOT BETWEEN', (start, end))
+        return Condition(self, 'NOT BETWEEN', (self._process_value(start), self._process_value(end)))
 
     def is_null(self) -> 'Condition':
         """Create an IS NULL condition"""
@@ -242,6 +266,7 @@ class Table:
 
         annotations = getattr(cls, '__annotations__', {})
         sa_columns = []
+        cls._type_processors = {}
 
         # Collect all potential column fields
         all_fields = {}
@@ -295,12 +320,19 @@ class Table:
                     sa_col.name = field_name
                     sa_columns.append(sa_col)
 
+                # Extract type processor if present
+                type_processor = getattr(field_value, '_tsql_type_processor', None)
+
                 # Create query builder Column directly
-                setattr(cls, field_name, Column(cls.table_name, field_name, schema=schema))
+                setattr(cls, field_name, Column(cls.table_name, field_name, schema=schema, type_processor=type_processor))
                 # Update annotation to reflect the Column type
                 if not hasattr(cls, '__annotations__'):
                     cls.__annotations__ = {}
                 cls.__annotations__[field_name] = Column
+
+                # Store type processor in mapping if present
+                if type_processor is not None:
+                    cls._type_processors[field_name] = type_processor
                 continue
 
             # Check if it's a Column instance (for column_name remapping)
@@ -311,13 +343,20 @@ class Table:
                     # No column_name specified, use field_name
                     db_column_name = field_name
 
+                # Extract type processor if present
+                type_processor = field_value.type_processor
+
                 # Create query builder Column directly with the DB column name
-                setattr(cls, field_name, Column(cls.table_name, db_column_name, schema=schema))
+                setattr(cls, field_name, Column(cls.table_name, db_column_name, schema=schema, type_processor=type_processor))
                 # Update annotation to reflect the Column type
                 if not hasattr(cls, '__annotations__'):
                     cls.__annotations__ = {}
                 cls.__annotations__[field_name] = Column
 
+                # Store type processor in mapping if present
+                if type_processor is not None:
+                    cls._type_processors[field_name] = type_processor
+
                 # Create SQLAlchemy column if metadata provided
                 if metadata is not None and HAS_SQLALCHEMY:
                     sa_type = PYTHON_TO_SA.get(field_type, String)()
@@ -520,6 +559,45 @@ class QueryBuilder(ABC):
         """
         return self.to_tsql().render(style)
 
+    def map_results(self, rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Transform database rows with type processors applied.
+
+        This method applies process_result_value from type processors to convert
+        database values back to Python values (e.g., decrypt encrypted fields,
+        deserialize JSON, etc.).
+
+        Preserves the original row object type when possible by updating values
+        in place rather than creating new dictionaries.
+
+        Args:
+            rows: List of dictionaries from database query results
+
+        Returns:
+            List of dictionaries with transformed values
+
+        Example:
+            query = User.select().where(User.id == 1)
+            rows = await conn.fetch(*query.render())
+            transformed_rows = query.map_results(rows)  # ssn decrypted, metadata deserialized
+        """
+        if not hasattr(self, 'base_table'):
+            raise AttributeError("map_results requires a base_table attribute")
+
+        results = []
+        for row in rows:
+            # Convert row to dict if it's not already (some drivers return Record objects)
+            row_dict = dict(row) if not isinstance(row, dict) else row
+
+            # Apply type processors in place
+            for col_name in list(row_dict.keys()):
+                if col_name in self.base_table._type_processors:
+                    processor = self.base_table._type_processors[col_name]
+                    row_dict[col_name] = processor.process_result_value(row_dict[col_name])
+
+            results.append(row_dict)
+
+        return results
+
 
 class InsertBuilder(QueryBuilder):
     """Fluent interface for building INSERT queries"""
@@ -619,7 +697,15 @@ class InsertBuilder(QueryBuilder):
             table_name = f"{self.base_table.schema}.{self.base_table.table_name}"
         else:
             table_name = self.base_table.table_name
-        values_dict = self.values
+
+        # Apply type processors to values
+        values_dict = {}
+        for col_name, value in self.values.items():
+            if col_name in self.base_table._type_processors:
+                processor = self.base_table._type_processors[col_name]
+                values_dict[col_name] = processor.process_bind_param(value)
+            else:
+                values_dict[col_name] = value
 
         # MySQL INSERT IGNORE
         if self._ignore:
@@ -651,8 +737,14 @@ class InsertBuilder(QueryBuilder):
 
             # Build UPDATE SET clause
             if self._update_cols:
-                # User specified which columns to update
-                update_dict = self._update_cols
+                # User specified which columns to update - apply type processors
+                update_dict = {}
+                for col_name, value in self._update_cols.items():
+                    if col_name in self.base_table._type_processors:
+                        processor = self.base_table._type_processors[col_name]
+                        update_dict[col_name] = processor.process_bind_param(value)
+                    else:
+                        update_dict[col_name] = value
                 parts.append(t'ON CONFLICT ({conflict_cols_str:unsafe}) DO UPDATE SET {update_dict:as_set}')
             else:
                 # Default: update all non-conflict columns with EXCLUDED.*
@@ -673,7 +765,14 @@ class InsertBuilder(QueryBuilder):
         # MySQL ON DUPLICATE KEY UPDATE
         elif self._on_conflict_action == 'duplicate_key':
             if self._update_cols:
-                update_dict = self._update_cols
+                # Apply type processors
+                update_dict = {}
+                for col_name, value in self._update_cols.items():
+                    if col_name in self.base_table._type_processors:
+                        processor = self.base_table._type_processors[col_name]
+                        update_dict[col_name] = processor.process_bind_param(value)
+                    else:
+                        update_dict[col_name] = value
                 parts.append(t'ON DUPLICATE KEY UPDATE {update_dict:as_set}')
             else:
                 # Default: update all columns with alias.column (new MySQL syntax)
@@ -792,7 +891,16 @@ class UpdateBuilder(QueryBuilder):
             table_name = f"{self.base_table.schema}.{self.base_table.table_name}"
         else:
             table_name = self.base_table.table_name
-        values_dict = self.values
+
+        # Apply type processors to values
+        values_dict = {}
+        for col_name, value in self.values.items():
+            if col_name in self.base_table._type_processors:
+                processor = self.base_table._type_processors[col_name]
+                values_dict[col_name] = processor.process_bind_param(value)
+            else:
+                values_dict[col_name] = value
+
         parts.append(t'UPDATE {table_name:literal} SET {values_dict:as_set}')
 
         if self._conditions:
@@ -1128,7 +1236,7 @@ if HAS_SQLALCHEMY:
 
 
 # Helper function for type checker compatibility with SQLAlchemy columns
-def SAColumn(*args: Any, **kwargs: Any) -> Column:  # noqa: N802
+def SAColumn(*args: Any, type_processor: Any = None, **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
@@ -1143,6 +1251,12 @@ def SAColumn(*args: Any, **kwargs: Any) -> Column:  # noqa: N802
             id = SAColumn(Integer, primary_key=True)  # Type checker sees: tsql Column
             name = SAColumn(String(100))
 
+        # With type processor:
+        from tsql.type_processor import TypeProcessor
+
+        class Users(Table):
+            ssn = SAColumn(String(255), type_processor=EncryptedString(key=MY_KEY))
+
     Note: This shadows the SQLAlchemy Column import. Import SA Column explicitly if needed:
         from sqlalchemy import Column as SA_Column
 
@@ -1153,4 +1267,7 @@ def SAColumn(*args: Any, **kwargs: Any) -> Column:  # noqa: N802
     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]
+    sa_col = SA_Column(*args, **kwargs)
+    if type_processor is not None:
+        sa_col._tsql_type_processor = type_processor  # type: ignore[attr-defined]
+    return sa_col  # type: ignore[return-value]

t_sql-4.4.1/tsql/type_processor.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class TypeProcessor(ABC):
+    """Base class for custom column type transformations.
+
+    Type processors enable automatic value transformation when reading from
+    and writing to the database, similar to SQLAlchemy's TypeDecorator.
+
+    Processors can be stateful and accept configuration in __init__:
+
+        class EncryptedString(TypeProcessor):
+            def __init__(self, key):
+                self.key = key
+
+            def process_bind_param(self, value):
+                return encrypt(value, self.key) if value is not None else None
+
+            def process_result_value(self, value):
+                return decrypt(value, self.key) if value is not None else None
+
+    Example usage with Table:
+
+        class User(Table, metadata=metadata):
+            id = SAColumn(Integer, primary_key=True)
+            ssn = SAColumn(String(255), type_processor=EncryptedString(key=MY_KEY))
+
+        # Automatic encryption on insert
+        User.insert(ssn="123-45-6789")
+
+        # Manual decryption on select
+        query = User.select().where(User.id == 1)
+        rows = await conn.fetch(*query.render())
+        users = query.map_results(rows)  # ssn automatically decrypted
+    """
+
+    @abstractmethod
+    def process_bind_param(self, value: Any) -> Any:
+        """Transform Python value to database value.
+
+        Called when inserting, updating, or comparing values in WHERE clauses.
+        NULL values (None) are passed through - the processor decides how to handle them.
+
+        Args:
+            value: The Python value to transform
+
+        Returns:
+            The transformed value to send to the database
+        """
+        pass
+
+    @abstractmethod
+    def process_result_value(self, value: Any) -> Any:
+        """Transform database value to Python value.
+
+        Called when reading values from query results via map_results().
+        NULL values (None) are passed through - the processor decides how to handle them.
+
+        Args:
+            value: The database value to transform
+
+        Returns:
+            The transformed Python value
+        """
+        pass
+
+
+__all__ = ['TypeProcessor']