deev 2.0.0__tar.gz → 2.0.2__tar.gz

{deev-2.0.0/src/deev.egg-info → deev-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deev
-Version: 2.0.0
+Version: 2.0.2
 Summary: ..an entity framework for Python.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT

{deev-2.0.0 → deev-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deev"
-version = "2.0.0"
+version = "2.0.2"
 description = "..an entity framework for Python."
 keywords = ["DB", "database", "entity framework", "mapper", "sqlite", "mysql", "mongodb", "clickhouse"]
 authors = [

{deev-2.0.0 → deev-2.0.2}/src/deev/SKILL.md

@@ -389,7 +389,7 @@ def undo(tx: ClickHouseTransactionContext) -> None:
 
 | Name | Purpose |
 |------|---------|
-| `splat` | Extract entity field values from object (params: `attrs`, `to_sql`, `to_bson`) |
+| `splat` | Extract entity field values from object (parameters: `attrs`, `to_sql`, `to_bson`) |
 | `hydrate` | Create entity instances from dicts |
 | `configure_serialization` | Customize JSON serialization |
 | `DeevJsonEncoder` | Custom JSON encoder for deev types |
@@ -403,7 +403,7 @@ def undo(tx: ClickHouseTransactionContext) -> None:
 
 | Name | Purpose |
 |------|---------|
-| `validate` | Validate entity instance (params: `attrs`) |
+| `validate` | Validate entity instance (parameters: `attrs`) |
 | `ValidationError` | Exception raised on validation failure |
 
 ### From `deev.utils`

{deev-2.0.0 → deev-2.0.2}/src/deev/__init__.py

@@ -21,8 +21,8 @@ from .translation import hydrate, splat
 from .utils import connect
 
 
-__version__ = '2.0.0'
-__commit__ = '2f75316'
+__version__ = '2.0.2'
+__commit__ = 'a337fba'
 __all__ = [
     '__version__',
     '__commit__',

{deev-2.0.0 → deev-2.0.2}/src/deev/clickhouse/async_clickhouse_table_adapter.py

@@ -45,7 +45,6 @@ class AsyncClickHouseTableAdapter(AsyncDbTableAdapter[TEntity]):
     __logger: logging.Logger
     __dbtype_mapper: DbTypeMapper
     __table_name: str | None
-    __transaction_state: int
 
     def __init__(
         self,
@@ -59,7 +58,6 @@ class AsyncClickHouseTableAdapter(AsyncDbTableAdapter[TEntity]):
         self.__create_table = create_table is True
         self.__initialized = False
         self.__table_name = table_name
-        self.__transaction_state = 0
         self.__is_sync_replicas_enabled = sync_replicas is True and getattr(self.__context, 'is_replicated', False) is True
         self.__logger = hanaro.get_logger()
 

deev-2.0.2/src/deev/clickhouse/async_clickhouse_transaction_context.py

@@ -0,0 +1,272 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import asyncio
+from contextvars import ContextVar
+import logging
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Literal, Self, cast
+from uuid import UUID, uuid4
+
+import hanaro
+
+from ..common.async_db_connection import AsyncDbConnection
+from ..common.db_context import AsyncDbContext
+from ..common.async_db_cursor import AsyncDbCursor
+from ..common.async_db_transaction_context import AsyncDbTransactionContext
+from ..common.db_error import DbError
+from ..common.db_parameters import DbParameters
+from ..common.tlc_parser import extract_begin_name, extract_rollback_name, extract_savepoint_name
+from .async_clickhouse_proxy_connection import AsyncClickHouseProxyConnection
+
+
+class AsyncClickHouseTransactionContext(AsyncDbTransactionContext):
+    """
+    Async transaction context for ClickHouse.
+
+    ClickHouse does not support traditional ACID transactions. All transaction methods are
+    no-ops. This context enables using ClickHouse connections with code that expects
+    transactional semantics. For example, when swapping providers.
+    """
+
+    __ambient_transaction_id: ContextVar[str | None] = ContextVar[str | None]('ambient_transaction_id', default=None)
+    __context: AsyncDbContext | None
+    __cursor: Any | None
+    __logger: logging.Logger
+    __savepoints: list[str]
+    __transaction_depth: int
+    __transaction_id: str
+    __transaction_name: str | None
+
+    def __init__(self, context: AsyncDbContext, *, owns_context: bool | None = None) -> None:
+        self.__owns_context = owns_context is True
+        self.__is_deev_context = isinstance(context, (AsyncClickHouseProxyConnection, AsyncClickHouseTransactionContext))
+        self.__context = context if self.__is_deev_context else AsyncClickHouseProxyConnection(context)  # type: ignore[arg-type]
+        self.__logger = hanaro.get_logger()
+        self.__transaction_id = uuid4().hex
+        self.__transaction_depth = 0
+        self.__savepoints: list[str] = []
+        self.__transaction_name: str | None = None
+        self.__cursor = None
+
+    def __del__(self) -> None:
+        try:
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = None
+            if loop and loop.is_running():
+                loop.create_task(self.close())
+            else:
+                asyncio.run(self.close())
+        except Exception:
+            pass
+
+    async def __aenter__(self) -> Self:
+        await self.begin_transaction()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None
+    ) -> Literal[False]:
+        try:
+            if self.__transaction_depth > 0:
+                if exc_type is not None:
+                    await self.rollback()
+                else:
+                    await self.rollback()
+                    raise DbError('Detected uncommitted transaction, rolling back. You must explicitly call commit or rollback.')
+        finally:
+            await self.close()
+            self.__transaction_depth = -1
+        return False
+
+    def __preprocess_sql(self, sql: str) -> str | None:
+        """
+        Parse SQL to determine whether it is a transaction-control (TLC) keyword
+        or a regular SQL statement.
+
+        For ClickHouse: all TLC keywords return None (scrubbed) since ClickHouse
+        has no transaction support. Depth tracking is for diagnostics/consistency.
+        """
+        if self.__transaction_depth == -1:
+            raise DbError('Cannot use a transaction context that has exited.')
+        elif self.__transaction_depth == -2:
+            raise DbError('Cannot use a transaction context that has been committed.')
+        elif self.__transaction_depth == -3:
+            raise DbError('Cannot use a transaction context that has been rolled back.')
+
+        sql_upper = sql.lstrip().upper()
+        prefix = sql_upper[:4]
+
+        if prefix == 'BEGI':
+            self.__transaction_depth += 1
+            self.__transaction_name = extract_begin_name(sql)
+            return None
+
+        elif prefix == 'SAVE' or sql_upper.startswith('SAVEPOINT '):
+            name_token = extract_savepoint_name(sql)
+            if name_token:
+                self.__savepoints.append(name_token)
+            return None
+
+        elif prefix == 'COMM':
+            if self.__transaction_depth == 0:
+                raise DbError('No active transaction to commit.')
+            self.__transaction_depth -= 1
+            if self.__transaction_depth == 0:
+                self.__savepoints.clear()
+                self.__transaction_name = None
+                self.__ambient_transaction_id.set(None)
+                self.__transaction_depth = -2
+            return None
+
+        elif prefix == 'ROLL':
+            if self.__transaction_depth == 0:
+                raise DbError('Cannot rollback, no transaction.')
+            name = extract_rollback_name(sql)
+
+            if name:
+                if name in self.__savepoints:
+                    while self.__savepoints:
+                        sp = self.__savepoints.pop()
+                        if sp == name:
+                            break
+                    return None
+                elif name == self.__transaction_name:
+                    pass  # full rollback, depth reset below
+                else:
+                    raise DbError('Invalid Transaction Name')
+            else:
+                pass  # full rollback, depth reset below
+
+            self.__transaction_depth = -3
+            self.__savepoints.clear()
+            self.__transaction_name = None
+            self.__ambient_transaction_id.set(None)
+            return None
+
+        return sql
+
+    @property
+    def connection(self) -> AsyncDbConnection:
+        if isinstance(self.__context, AsyncDbTransactionContext):
+            return cast(AsyncDbTransactionContext, self.__context).connection
+        else:
+            return cast(AsyncDbConnection, self.__context)
+
+    @property
+    def clickhouse_client(self) -> Any:
+        assert self.__context is not None, 'no context'
+        if hasattr(self.__context, 'clickhouse_client'):
+            return self.__context.clickhouse_client  # type: ignore[return-value]
+        return None
+
+    @property
+    def transaction_name(self) -> str | None:
+        return self.__transaction_name
+
+    @property
+    def savepoints(self) -> tuple[str, ...]:
+        return tuple(self.__savepoints)
+
+    async def begin_transaction(self, name: str | None = None) -> Self:
+        assert self.__context is not None, 'no context'
+        self.__cursor = await self.__context.cursor()
+        if AsyncClickHouseTransactionContext.__ambient_transaction_id.get(None) is None:
+            AsyncClickHouseTransactionContext.__ambient_transaction_id.set(name or self.__transaction_id)
+        sql = 'BEGIN TRANSACTION'
+        if name:
+            sql += f' {name}'
+        await self.execute(sql)
+        return self
+
+    async def create_savepoint(self, name: str | None = None) -> Self:
+        if name is None:
+            name = f'TID_{uuid4().hex[:24]}'
+        sql = f'SAVE TRANSACTION {name}'
+        await self.execute(sql)
+        return self
+
+    async def rollback_savepoint(self, name: str | None = None) -> None:
+        if name is None:
+            if not self.__savepoints:
+                return
+            name = self.__savepoints[-1]
+        sql = f'ROLLBACK TRANSACTION {name}'
+        await self.execute(sql)
+
+    async def close(self) -> None:
+        try:
+            if self.__cursor is not None:
+                await self.__cursor.close()
+        except Exception:
+            pass
+        self.__cursor = None
+        try:
+            if self.__context is not None and self.__owns_context and hasattr(self.__context, 'close'):
+                await self.__context.close()
+        except Exception:
+            pass
+        self.__context = None
+
+    async def commit(self) -> None:
+        await self.execute('COMMIT')
+
+    async def cursor(self) -> AsyncDbCursor:
+        assert self.__context is not None, 'no context'
+        return await self.__context.cursor()
+
+    async def execute(self, sql: str, parameters: DbParameters | None = None, raw: bool = False) -> AsyncDbCursor:
+        if not raw:
+            modified = self.__preprocess_sql(sql)
+            if modified is None:
+                from ..common.noop_cursor import NoopCursor
+                return cast(AsyncDbCursor, NoopCursor())  # type: ignore[return-value]
+            sql = modified
+        assert self.__context is not None, 'no context'
+        if self.__cursor is None:
+            self.__cursor = await self.__context.cursor()
+        assert self.__cursor is not None
+        await self.__cursor.execute(sql, parameters)
+        return cast(AsyncDbCursor, self.__cursor)
+
+    async def execute_nonquery(self, sql: str, parameters: DbParameters | None = None) -> None:
+        await self.execute(sql, parameters)
+
+    async def execute_reader(self, sql: str, parameters: DbParameters | None = None) -> AsyncGenerator[tuple[Any, ...], None]:  # type: ignore[override]
+        cursor = await self.execute(sql, parameters)
+        row = await cursor.fetchone()
+        while row is not None:
+            yield row
+            row = await cursor.fetchone()
+
+    async def execute_scalar(self, sql: str, parameters: DbParameters | None = None) -> Any:
+        cursor = await self.execute(sql, parameters)
+        try:
+            row = await cursor.fetchone()
+            return None if row is None else row[0]
+        except Exception:
+            return cursor.rowcount
+
+    async def execute_script(self, sql: str, raw: bool = False) -> None:
+        if raw is True:
+            await self.execute(sql, raw=True)
+            return
+        lines = sql.split('\n')
+        scrubbed = [line for line in lines if self.__preprocess_sql(line) is not None]
+        joined = '\n'.join(scrubbed)
+        if joined:
+            await self.execute(joined, raw=True)
+
+    async def rollback(self, name: str | None = None) -> None:
+        sql = 'ROLLBACK' if name is None else f'ROLLBACK TRANSACTION {name}'
+        await self.execute(sql)
+
+
+__all__ = ['AsyncClickHouseTransactionContext']

{deev-2.0.0 → deev-2.0.2}/src/deev/clickhouse/clickhouse_table_adapter.py

@@ -41,7 +41,6 @@ class ClickHouseTableAdapter(Generic[TEntity]):
     __initialized: bool
     __logger: logging.Logger
     __table_name: str | None
-    __transaction_state: int
 
     def __init__(
         self,
@@ -55,7 +54,6 @@ class ClickHouseTableAdapter(Generic[TEntity]):
         self.__create_table = create_table is True
         self.__initialized = False
         self.__table_name = table_name
-        self.__transaction_state = 0
         self.__is_sync_replicas_enabled = sync_replicas is True and getattr(self.__context, 'is_replicated', False) is True
         self.__logger = hanaro.get_logger()
 

deev-2.0.2/src/deev/clickhouse/clickhouse_transaction_context.py

@@ -0,0 +1,264 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+import logging
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Generator, Literal, Self, cast
+
+import hanaro
+from uuid import uuid4
+
+from ..common.db_connection import DbConnection
+from ..common.db_cursor import DbCursor
+from ..common.db_error import DbError
+from ..common.db_parameters import DbParameters
+from ..common.db_transaction_context import DbTransactionContext
+from ..common.tlc_parser import extract_begin_name, extract_rollback_name, extract_savepoint_name
+from .clickhouse_proxy_connection import ClickHouseProxyConnection
+
+if TYPE_CHECKING:
+    from ..common.db_context import DbContext
+
+
+class ClickHouseTransactionContext(DbTransactionContext):
+    """
+    Transaction context for ClickHouse.
+
+    ClickHouse does not support traditional ACID transactions. All transaction methods are
+    no-ops. This context enables using ClickHouse connections with code that expects
+    transactional semantics.  For example, when swapping providers.
+    """
+
+    __ambient_transaction_id: ContextVar[str | None] = ContextVar[str | None]('ambient_transaction_id', default=None)
+    __context: DbContext | None
+    __cursor: DbCursor | None
+    __logger: logging.Logger
+    __savepoints: list[str]
+    __transaction_depth: int
+    __transaction_id: str
+    __transaction_name: str | None
+
+    def __init__(self, context: DbContext, *, owns_context: bool | None = None) -> None:
+        """
+        Initialize the ClickHouse transaction context.
+
+        ClickHouse does not support traditional ACID transactions; all transaction methods
+        are no-ops. This context enables using ClickHouse with code that expects
+        transactional semantics.
+
+        :param context: A :class:`ClickHouseProxyConnection` or related context.
+        :param owns_context: Whether this transaction context owns *context* and should close it.
+        """
+        self.__owns_context = owns_context is True
+        self.__is_deev_context = isinstance(context, (ClickHouseProxyConnection, ClickHouseTransactionContext))
+        self.__context = context if self.__is_deev_context else ClickHouseProxyConnection(context)  # type: ignore[arg-type]
+        self.__logger = hanaro.get_logger()
+        self.__transaction_id = uuid4().hex
+        self.__transaction_depth = 0
+        self.__savepoints: list[str] = []
+        self.__transaction_name: str | None = None
+        self.__cursor = None
+
+    def __del__(self) -> None:
+        self.close()
+
+    def __enter__(self) -> Self:
+        self.begin_transaction()
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None = None, exc_value: BaseException | None = None, traceback: TracebackType | None = None) -> Literal[False]:
+        try:
+            if self.__transaction_depth > 0:
+                if exc_type is not None:
+                    self.rollback()
+                else:
+                    self.rollback()
+                    raise DbError('Detected uncommitted transaction, rolling back. You must explicitly call commit or rollback.')
+        finally:
+            self.close()
+            self.__transaction_depth = -1
+            self.__ambient_transaction_id.set(None)
+        return False
+
+    def __preprocess_sql(self, sql: str) -> str | None:
+        """
+        Parse SQL to determine whether it is a transaction-control (TLC) keyword
+        or a regular SQL statement.
+
+        For ClickHouse: all TLC keywords return None (scrubbed) since ClickHouse
+        has no transaction support. Depth tracking is for diagnostics/consistency.
+        """
+        if self.__transaction_depth == -1:
+            raise DbError('Cannot use a transaction context that has exited.')
+        elif self.__transaction_depth == -2:
+            raise DbError('Cannot use a transaction context that has been committed.')
+        elif self.__transaction_depth == -3:
+            raise DbError('Cannot use a transaction context that has been rolled back.')
+
+        sql_upper = sql.lstrip().upper()
+        prefix = sql_upper[:4]
+
+        if prefix == 'BEGI':
+            self.__transaction_depth += 1
+            self.__transaction_name = extract_begin_name(sql)
+            return None
+
+        elif prefix == 'SAVE' or sql_upper.startswith('SAVEPOINT '):
+            name_token = extract_savepoint_name(sql)
+            if name_token:
+                self.__savepoints.append(name_token)
+            return None
+
+        elif prefix == 'COMM':
+            if self.__transaction_depth == 0:
+                raise DbError('No active transaction to commit.')
+            self.__transaction_depth -= 1
+            if self.__transaction_depth == 0:
+                self.__savepoints.clear()
+                self.__transaction_name = None
+                self.__ambient_transaction_id.set(None)
+                self.__transaction_depth = -2
+            return None
+
+        elif prefix == 'ROLL':
+            if self.__transaction_depth == 0:
+                raise DbError('Cannot rollback, no transaction.')
+            name = extract_rollback_name(sql)
+
+            if name:
+                if name in self.__savepoints:
+                    while self.__savepoints:
+                        sp = self.__savepoints.pop()
+                        if sp == name:
+                            break
+                    return None
+                elif name == self.__transaction_name:
+                    pass  # full rollback, depth reset below
+                else:
+                    raise DbError('Invalid Transaction Name')
+            else:
+                pass  # full rollback, depth reset below
+
+            self.__transaction_depth = -3
+            self.__savepoints.clear()
+            self.__transaction_name = None
+            self.__ambient_transaction_id.set(None)
+            return None
+
+        return sql
+
+    @property
+    def connection(self) -> DbConnection:
+        if isinstance(self.__context, DbTransactionContext):
+            return cast(DbTransactionContext, self.__context).connection
+        else:
+            return cast(DbConnection, self.__context)
+
+    @property
+    def clickhouse_client(self) -> Any:
+        return cast(ClickHouseProxyConnection, self.__context).clickhouse_client
+
+    @property
+    def transaction_name(self) -> str | None:
+        return self.__transaction_name
+
+    @property
+    def savepoints(self) -> tuple[str, ...]:
+        return tuple(self.__savepoints)
+
+    def begin_transaction(self, name: str | None = None) -> Self:
+        if self.__cursor is None:
+            assert self.__context is not None, 'no context'
+            self.__cursor = self.__context.cursor()
+        sql = 'BEGIN TRANSACTION'
+        if name:
+            sql += f' {name}'
+        self.execute(sql)
+        return self
+
+    def create_savepoint(self, name: str | None = None) -> Self:
+        if name is None:
+            name = f'TID_{uuid4().hex[:24]}'
+        sql = f'SAVE TRANSACTION {name}'
+        self.execute(sql)
+        return self
+
+    def rollback_savepoint(self, name: str | None = None) -> None:
+        if name is None:
+            if not self.__savepoints:
+                return
+            name = self.__savepoints[-1]
+        sql = f'ROLLBACK TRANSACTION {name}'
+        self.execute(sql)
+
+    def close(self) -> None:
+        try:
+            if self.__cursor is not None:
+                self.__cursor.close()
+        except Exception:
+            pass
+        self.__cursor = None
+        try:
+            if self.__context is not None and self.__owns_context and hasattr(self.__context, 'close'):
+                self.__context.close()
+        except Exception:
+            pass
+        self.__context = None
+
+    def commit(self) -> None:
+        self.execute('COMMIT')
+
+    def cursor(self) -> DbCursor:
+        assert self.__context is not None, 'no context'
+        return self.__context.cursor()
+
+    def execute(self, sql: str, parameters: DbParameters | None = None, raw: bool = False) -> DbCursor:
+        if not raw:
+            modified = self.__preprocess_sql(sql)
+            if modified is None:
+                from ..common.noop_cursor import NoopCursor
+                return NoopCursor()
+            sql = modified
+        if self.__cursor is None:
+            assert self.__context is not None, 'no context'
+            self.__cursor = self.__context.cursor()
+        self.__cursor.execute(sql, parameters)
+        return cast(DbCursor, self.__cursor)
+
+    def execute_nonquery(self, sql: str, parameters: DbParameters | None = None) -> None:
+        self.execute(sql, parameters)
+
+    def execute_reader(self, sql: str, parameters: DbParameters | None = None) -> Generator[Any, None, None]:
+        cursor = self.execute(sql, parameters)
+        row = cursor.fetchone()
+        while row is not None:
+            yield row
+            row = cursor.fetchone()
+
+    def execute_scalar(self, sql: str, parameters: DbParameters | None = None) -> Any:
+        cursor = self.execute(sql, parameters)
+        try:
+            row = cursor.fetchone()
+            return None if row is None else row[0]
+        except Exception:
+            return cursor.rowcount
+
+    def execute_script(self, sql: str, raw: bool = False) -> None:
+        if raw is True:
+            self.execute(sql, raw=True)
+            return
+        lines = sql.split('\n')
+        scrubbed = [line for line in lines if self.__preprocess_sql(line) is not None]
+        joined = '\n'.join(scrubbed)
+        if joined:
+            self.execute(joined, raw=True)
+
+    def rollback(self, name: str | None = None) -> None:
+        sql = 'ROLLBACK' if name is None else f'ROLLBACK TRANSACTION {name}'
+        self.execute(sql)
+
+
+__all__ = ['ClickHouseTransactionContext']

{deev-2.0.0 → deev-2.0.2}/src/deev/common/async_db_transaction_context.py

@@ -41,16 +41,30 @@ class AsyncDbTransactionContext(Protocol):
     def connection(self) -> AsyncDbConnection:
         ...
 
+    @property
+    def transaction_name(self) -> str | None:
+        ...
+
+    @property
+    def savepoints(self) -> tuple[str, ...]:
+        ...
+
     async def cursor(self) -> AsyncDbCursor:
         ...
 
+    async def begin_transaction(self, name: str | None = None) -> Self:
+        ...
+
     async def commit(self) -> None:
         ...
 
-    async def execute(self, sql: str, parameters: DbParameters | None = ...) -> AsyncDbCursor:
+    async def create_savepoint(self, name: str | None = None) -> Self:
+        ...
+
+    async def execute(self, sql: str, parameters: DbParameters | None = ..., raw: bool = ...) -> AsyncDbCursor:
         ...
 
-    async def execute_script(self, sql: str) -> None:
+    async def execute_script(self, sql: str, raw: bool = ...) -> None:
         ...
 
     async def execute_nonquery(self, sql: str, parameters: DbParameters | None = ...) -> None:
@@ -62,7 +76,13 @@ class AsyncDbTransactionContext(Protocol):
     async def execute_scalar(self, sql: str, parameters: DbParameters | None = ...) -> Any:
         ...
 
-    async def rollback(self) -> None:
+    async def rollback(self, name: str | None = None) -> None:
+        ...
+
+    async def rollback_savepoint(self, name: str | None = None) -> None:
+        ...
+
+    async def close(self) -> None:
         ...
 
     @classmethod

{deev-2.0.0 → deev-2.0.2}/src/deev/common/db_migrator.py

@@ -161,7 +161,6 @@ class DbMigrator:
                 if migration_func is not None:
                     with begin_transaction(self.__connectionstring) as db_transaction:
                         migration_func(db_transaction)
-                        db_transaction.commit()
                         # NOTE: callee (migration_func) is responsible for calling commit (or rollback)
                     migrations_table.delete(id=applied_migrations.get(migration_name, 0))
                     migrations_table.commit()