loom-kernel 0.12.0__tar.gz → 0.12.2__tar.gz

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/CHANGELOG.md

@@ -1,3 +1,37 @@
+# 🚀 Release 0.12.2 ([#68](https://github.com/the-reacher-data/loom-py/pull/68)) ([`4f067d0`](https://github.com/the-reacher-data/loom-py/commit/4f067d060347334128455503d6a4975c1bcc6285))
+
+
+
+## 🐛 Fixes
+### prefect
+- **prefect:** observe maintenance logs in flow runs
+
+
+
+
+
+
+
+
+
+
+# 🚀 Release 0.12.1 ([#66](https://github.com/the-reacher-data/loom-py/pull/66)) ([`f3c045e`](https://github.com/the-reacher-data/loom-py/commit/f3c045ec6b9e915e5d2c9f55d7134a7be37c1475))
+
+
+
+## 🐛 Fixes
+### runner
+- **runner:** wire ClickHouseClientExecutor in from_config for ClientStep
+
+
+
+
+
+
+
+
+
+
 # 🚀 Release 0.12.0 ([#64](https://github.com/the-reacher-data/loom-py/pull/64)) ([`a471a17`](https://github.com/the-reacher-data/loom-py/commit/a471a17337d2d63b66fad0f74c81b199b943e588))
 
 

loom_kernel-0.12.2/CHANGELOG_RELEASE.md

@@ -0,0 +1,15 @@
+# 🚀 Release 0.12.2 ([#68](https://github.com/the-reacher-data/loom-py/pull/68)) ([`4f067d0`](https://github.com/the-reacher-data/loom-py/commit/4f067d060347334128455503d6a4975c1bcc6285))
+
+
+
+## 🐛 Fixes
+### prefect
+- **prefect:** observe maintenance logs in flow runs
+
+
+
+
+
+
+
+

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loom-kernel
-Version: 0.12.0
+Version: 0.12.2
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "0.12.0"
+version = "0.12.2"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -268,7 +268,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.12.0"
+version = "0.12.2"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/etl/backends/polars/provider.py

@@ -11,11 +11,11 @@ from loom.etl.backends.polars._writer import PolarsTargetWriter
 from loom.etl.io._registry import ReaderRegistry, WriterRegistry
 from loom.etl.io.sources._clickhouse import ClickHouseSourceReader
 from loom.etl.io.sources._mongo import MongoSourceReader
-from loom.etl.io.targets._clickhouse import ClickHouseTargetWriter
+from loom.etl.io.targets._clickhouse import ClickHouseClientExecutor, ClickHouseTargetWriter
 from loom.etl.lineage._config import LineageConfig
 from loom.etl.lineage.sinks import RecordFrameTargetWriter, TargetLineageWriter
 from loom.etl.runner._providers import BackendProvider
-from loom.etl.runtime.contracts import SourceReader, TargetWriter
+from loom.etl.runtime.contracts import ClientCommandExecutor, SourceReader, TargetWriter
 from loom.etl.storage._config import CatalogConnection, StorageConfig
 from loom.etl.storage._locator import MappingLocator, PrefixLocator, TableLocation, TableLocator
 
@@ -87,6 +87,16 @@ class PolarsProvider(BackendProvider):
         )
         return TargetLineageWriter(cast(RecordFrameTargetWriter, target_writer))
 
+    def create_client_executor(
+        self,
+        config: StorageConfig,
+        spark: Any = None,
+    ) -> ClientCommandExecutor | None:
+        _ = spark
+        if config.clickhouse.url:
+            return ClickHouseClientExecutor(url=config.clickhouse.url)
+        return None
+
 
 def _build_polars_locator(config: StorageConfig) -> TableLocator:
     mapping: dict[str, TableLocation] = {}

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/etl/backends/spark/provider.py

@@ -9,7 +9,7 @@ from loom.etl.backends.spark._writer import SparkTargetWriter
 from loom.etl.lineage._config import LineageConfig
 from loom.etl.lineage.sinks import RecordFrameTargetWriter, TargetLineageWriter
 from loom.etl.runner._providers import BackendProvider
-from loom.etl.runtime.contracts import SourceReader, TargetWriter
+from loom.etl.runtime.contracts import ClientCommandExecutor, SourceReader, TargetWriter
 from loom.etl.storage._config import StorageConfig
 from loom.etl.storage._locator import PrefixLocator
 from loom.etl.storage.routing import build_table_resolver
@@ -75,5 +75,14 @@ class SparkProvider(BackendProvider):
         )
         return TargetLineageWriter(cast(RecordFrameTargetWriter, target_writer))
 
+    def create_client_executor(
+        self,
+        config: StorageConfig,
+        spark: Any = None,
+    ) -> ClientCommandExecutor | None:
+        """Return ``None``: ClickHouse client steps do not apply to Spark yet."""
+        _ = (config, spark)
+        return None
+
 
 __all__ = ["SparkProvider"]

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/etl/runner/_providers.py

@@ -7,7 +7,7 @@ from typing import Any, Protocol, cast, runtime_checkable
 
 from loom.etl.lineage._config import LineageConfig
 from loom.etl.lineage.sinks import LineageWriter
-from loom.etl.runtime.contracts import SourceReader, TargetWriter
+from loom.etl.runtime.contracts import ClientCommandExecutor, SourceReader, TargetWriter
 from loom.etl.storage._config import StorageConfig
 
 _BACKEND_EP_GROUP = "loom.etl.backends"
@@ -34,6 +34,23 @@ class BackendProvider(Protocol):
         """Create lineage writer for ETL lineage persistence."""
         ...
 
+    def create_client_executor(
+        self,
+        config: StorageConfig,
+        spark: Any = None,
+    ) -> ClientCommandExecutor | None:
+        """Create a client command executor for ``ClientStep`` execution.
+
+        Args:
+            config: Resolved storage config.
+            spark: Active SparkSession, when the engine is Spark.
+
+        Returns:
+            An executor when the engine and config support client steps,
+            or ``None`` when no client backend is configured.
+        """
+        ...
+
 
 def load_backend_provider(engine: str) -> BackendProvider:
     """Load backend provider implementation from package entry points."""

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/etl/runner/_wiring.py

@@ -14,7 +14,7 @@ from loom.etl.checkpoint._cleaners import _is_cloud_path
 from loom.etl.lineage._config import LineageConfig
 from loom.etl.lineage.sinks import LineageStore, LineageWriter, TableLineageStore
 from loom.etl.runner._providers import load_backend_provider
-from loom.etl.runtime.contracts import SourceReader, TargetWriter
+from loom.etl.runtime.contracts import ClientCommandExecutor, SourceReader, TargetWriter
 from loom.etl.storage._config import StorageConfig
 
 
@@ -113,6 +113,25 @@ def make_lineage_store(
     return TableLineageStore(writer, database="")
 
 
+def make_client_executor(
+    config: StorageConfig,
+    spark: Any = None,
+) -> ClientCommandExecutor | None:
+    """Build a client command executor from config or return ``None``.
+
+    Args:
+        config: Resolved storage config.
+        spark: Active SparkSession. Required for the Spark engine.
+
+    Returns:
+        An executor when the engine and config support client steps,
+        or ``None`` when no client backend is configured.
+    """
+    engine = _resolve_engine(config, spark)
+    provider = load_backend_provider(engine)
+    return provider.create_client_executor(config, spark)
+
+
 def _make_checkpoint_backend(spark: Any, storage_options: dict[str, str]) -> Any:
     if spark is not None:
         return _SparkCheckpointBackend(spark)
@@ -128,6 +147,7 @@ def _resolve_engine(config: StorageConfig, spark: Any) -> str:
 __all__ = [
     "make_backends",
     "make_checkpoint_store",
+    "make_client_executor",
     "make_lineage_writer",
     "make_lineage_store",
 ]

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/etl/runner/core.py

@@ -25,6 +25,7 @@ from loom.etl.pipeline._pipeline import ETLPipeline
 from loom.etl.runner._wiring import (
     make_backends,
     make_checkpoint_store,
+    make_client_executor,
     make_lineage_store,
 )
 from loom.etl.runner.config_loader import _load_yaml
@@ -97,7 +98,8 @@ class ETLRunner:
         if extra_observers:
             observability = ObservabilityRuntime([*observability.observers, *extra_observers])
         checkpoint_store = make_checkpoint_store(config, spark, cleaner)
-        return cls(reader, writer, observability, dispatcher, checkpoint_store)
+        client_executor = make_client_executor(config, spark)
+        return cls(reader, writer, observability, dispatcher, checkpoint_store, client_executor)
 
     @classmethod
     def from_yaml(

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/prefect/flow/_body.py

@@ -16,6 +16,7 @@ from loom.etl.runner import ETLRunner
 from loom.prefect._ctx import FlowCtx
 from loom.prefect._placeholders import resolve_placeholder
 from loom.prefect._summary import set_run_summary
+from loom.prefect.flow._common import prefect_flow_run_id
 from loom.prefect.flow._run_name import compute_correlation_id
 from loom.prefect.flow._signature import normalize_datetime_fields
 from loom.prefect.manifest import (
@@ -89,7 +90,7 @@ def build_flow_body(
             _maybe_delete_manifest(manifest_store, ctx.correlation_id)
             return
 
-        flow_run_id = _current_flow_run_id()
+        flow_run_id = prefect_flow_run_id()
         install_log_bridge(flow_run_id)
         try:
             observers = _build_observers(flow_run_id, manifest_store, manifest)
@@ -158,15 +159,6 @@ def _maybe_build_prometheus_adapter() -> Any:
     return PrometheusLifecycleAdapter(pushgateway_url=pushgateway)
 
 
-def _current_flow_run_id() -> Any:
-    try:
-        from prefect.runtime import flow_run as _fr  # noqa: PLC0415
-
-        return _fr.id
-    except (ImportError, AttributeError):
-        return None
-
-
 def _invoke_runner(
     config_path: str,
     pipeline: type[ETLPipeline[Any]],

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/prefect/flow/_common.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Any
+import uuid
+from typing import Any, cast
 
 
 def coerce_tags(raw: Any) -> tuple[str, ...]:
@@ -17,4 +18,18 @@ def coerce_tags(raw: Any) -> tuple[str, ...]:
     return tuple(raw)
 
 
-__all__ = ["coerce_tags"]
+def prefect_flow_run_id() -> uuid.UUID | None:
+    """Return the current Prefect flow run identifier.
+
+    Returns:
+        The active flow run UUID, or ``None`` outside a Prefect flow run.
+    """
+    try:
+        from prefect.runtime import flow_run  # noqa: PLC0415
+
+        return cast(uuid.UUID | None, flow_run.id)
+    except (ImportError, AttributeError):
+        return None
+
+
+__all__ = ["coerce_tags", "prefect_flow_run_id"]

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/src/loom/prefect/flow/_maintenance.py

@@ -19,10 +19,12 @@ from loom.prefect._summary import set_run_summary
 from loom.prefect.deploy._schedule import extract_pool_config
 from loom.prefect.deploy._yaml import read_yaml
 from loom.prefect.flow._common import coerce_tags as _coerce_tags
+from loom.prefect.flow._common import prefect_flow_run_id
 from loom.prefect.flow._hooks import make_notification_hooks, pause_schedule_on_failure
 from loom.prefect.flow._run_name import make_run_name_callback
 from loom.prefect.flow._signature import normalize_datetime_fields, signature_from_params_type
 from loom.prefect.notify import build_notifiers
+from loom.prefect.observer._logging_bridge import install_log_bridge, uninstall_log_bridge
 
 
 def maintenance_flow(
@@ -76,8 +78,13 @@ def maintenance_flow(
         resolved = normalize_datetime_fields(resolved, params_type)
         params = msgspec.convert(resolved, type=params_type)
         actual_path = os.environ.get("LOOM_STORAGE_CONFIG_PATH") or storage_config_path
-        storage_config, _ = _load_yaml(actual_path)
-        report = MaintenanceRunner.from_config(storage_config).run(step, params=params)
+        # Bridge loom logs into the Prefect run (mirrors etl_flow).
+        install_log_bridge(prefect_flow_run_id())
+        try:
+            storage_config, _ = _load_yaml(actual_path)
+            report = MaintenanceRunner.from_config(storage_config).run(step, params=params)
+        finally:
+            uninstall_log_bridge()
         set_run_summary(_maintenance_summary(report, resolved))
         report.raise_if_errors()
 

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/tests/unit/etl/client_step/test_client_step.py

@@ -239,6 +239,35 @@ class TestClientStepExecution:
         with pytest.raises(TypeError, match="ClientCommandExecutor"):
             executor.run_step(plan, SimpleParams(value=1))
 
+    def test_from_config_runner_runs_client_step_without_missing_executor_error(
+        self, tmp_path: Any, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A runner built via from_config with a clickhouse url executes a
+        ClientStep without raising the missing-executor TypeError (offline).
+        """
+        from loom.etl.runner import ETLRunner
+        from loom.etl.storage._config import (
+            ClickHouseConfig,
+            StorageConfig,
+            StorageDefaults,
+            TablePathConfig,
+        )
+
+        fake_client = MagicMock()
+        fake_module = MagicMock()
+        fake_module.get_client.return_value = fake_client
+        monkeypatch.setattr("loom.etl.io.targets._clickhouse._clickhouse_connect", fake_module)
+
+        config = StorageConfig(
+            defaults=StorageDefaults(table_path=TablePathConfig(uri=str(tmp_path))),
+            clickhouse=ClickHouseConfig(url="clickhouse://user:pass@host:8123/db"),
+        )
+        runner = ETLRunner.from_config(config)
+
+        runner.run(_PipelineWithClientStep, SimpleParams(value=99))
+
+        fake_client.command.assert_called_once_with("SELECT 99")
+
 
 # ---------------------------------------------------------------------------
 # ClickHouseClientExecutor

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/tests/unit/etl/storage/test_backend_factory.py

@@ -17,11 +17,13 @@ from loom.etl.runner._providers import load_backend_provider
 from loom.etl.runner._wiring import (
     make_backends,
     make_checkpoint_store,
+    make_client_executor,
     make_lineage_store,
     make_lineage_writer,
 )
 from loom.etl.storage._config import (
     CatalogConnection,
+    ClickHouseConfig,
     MissingTablePolicy,
     StorageConfig,
     StorageDefaults,
@@ -320,6 +322,39 @@ def test_make_lineage_store_returns_table_store_when_enabled() -> None:
     assert isinstance(store, TableLineageStore)
 
 
+# ---------------------------------------------------------------------------
+# make_client_executor
+# ---------------------------------------------------------------------------
+
+
+def test_make_client_executor_polars_with_clickhouse_url_returns_executor() -> None:
+    from loom.etl.io.targets._clickhouse import ClickHouseClientExecutor
+
+    config = StorageConfig(
+        engine="polars",
+        clickhouse=ClickHouseConfig(url="clickhouse://user:pass@host:8123/db"),
+    )
+    executor = make_client_executor(config)
+
+    assert isinstance(executor, ClickHouseClientExecutor)
+
+
+def test_make_client_executor_polars_without_clickhouse_url_returns_none() -> None:
+    config = StorageConfig(engine="polars")
+    assert make_client_executor(config) is None
+
+
+def test_make_client_executor_spark_returns_none() -> None:
+    from unittest.mock import MagicMock
+
+    spark = MagicMock()
+    config = StorageConfig(
+        engine="spark",
+        clickhouse=ClickHouseConfig(url="clickhouse://user:pass@host:8123/db"),
+    )
+    assert make_client_executor(config, spark=spark) is None
+
+
 # ---------------------------------------------------------------------------
 # make_checkpoint_store
 # ---------------------------------------------------------------------------

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/tests/unit/etl/test_runner.py

@@ -321,6 +321,34 @@ class TestRunnerFromConfig:
         assert isinstance(runner._executor._writer, PolarsTargetWriter)
         assert (runner._checkpoint_store is not None) is has_checkpoint_store
 
+    def test_from_config_with_clickhouse_url_wires_client_executor(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from unittest.mock import MagicMock
+
+        from loom.etl.io.targets._clickhouse import ClickHouseClientExecutor
+        from loom.etl.storage._config import ClickHouseConfig
+
+        monkeypatch.setattr("loom.etl.io.targets._clickhouse._clickhouse_connect", MagicMock())
+
+        config = StorageConfig(
+            defaults=StorageDefaults(table_path=TablePathConfig(uri=str(tmp_path))),
+            clickhouse=ClickHouseConfig(url="clickhouse://user:pass@host:8123/db"),
+        )
+        runner = ETLRunner.from_config(config)
+
+        assert isinstance(runner._executor._client_executor, ClickHouseClientExecutor)
+
+    def test_from_config_without_clickhouse_url_leaves_client_executor_none(
+        self, tmp_path: Path
+    ) -> None:
+        config = StorageConfig(
+            defaults=StorageDefaults(table_path=TablePathConfig(uri=str(tmp_path))),
+        )
+        runner = ETLRunner.from_config(config)
+
+        assert runner._executor._client_executor is None
+
 
 class TestRunnerFromDict:
     def test_from_dict_polars_path_builds_polars_backends(self, tmp_path: Path) -> None:

loom_kernel-0.12.2/tests/unit/prefect/test_maintenance_flow.py

@@ -0,0 +1,84 @@
+"""Tests for Prefect maintenance-flow observability."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import msgspec
+import pytest
+
+from loom.etl.maintenance._runner import MaintenanceReport
+from loom.etl.maintenance._step import MaintenanceStep
+from loom.prefect.flow import _maintenance
+
+
+class _MaintenanceParams(msgspec.Struct, frozen=True):
+    dry_run: bool = False
+
+
+class _MaintenanceStep(MaintenanceStep[_MaintenanceParams]):
+    operations = []
+
+
+def _write_config(tmp_path: Path) -> Path:
+    config_path = tmp_path / "maintenance.yaml"
+    config_path.write_text("params: {}\n", encoding="utf-8")
+    return config_path
+
+
+def _build_flow(tmp_path: Path) -> object:
+    return _maintenance.maintenance_flow(
+        name="maintenance",
+        step=_MaintenanceStep,
+        params_type=_MaintenanceParams,
+        config_path=str(_write_config(tmp_path)),
+        source_file=__file__,
+    )
+
+
+def test_maintenance_flow_bridges_logs_to_current_flow_run(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    flow_run_id = uuid.uuid4()
+    runner = MagicMock()
+    runner.run.return_value = MaintenanceReport()
+    install = MagicMock()
+    uninstall = MagicMock()
+
+    monkeypatch.setattr(_maintenance, "prefect_flow_run_id", lambda: flow_run_id)
+    monkeypatch.setattr(_maintenance, "install_log_bridge", install)
+    monkeypatch.setattr(_maintenance, "uninstall_log_bridge", uninstall)
+    monkeypatch.setattr(_maintenance, "_load_yaml", lambda path: (MagicMock(), path))
+    monkeypatch.setattr(_maintenance.MaintenanceRunner, "from_config", lambda config: runner)
+
+    flow = _build_flow(tmp_path)
+    flow.fn(dry_run=True)  # type: ignore[attr-defined]
+
+    install.assert_called_once_with(flow_run_id)
+    uninstall.assert_called_once_with()
+    runner.run.assert_called_once()
+
+
+def test_maintenance_flow_uninstalls_log_bridge_after_failure(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    uninstall = MagicMock()
+
+    monkeypatch.setattr(_maintenance, "prefect_flow_run_id", uuid.uuid4)
+    monkeypatch.setattr(_maintenance, "install_log_bridge", MagicMock())
+    monkeypatch.setattr(_maintenance, "uninstall_log_bridge", uninstall)
+    monkeypatch.setattr(
+        _maintenance,
+        "_load_yaml",
+        MagicMock(side_effect=RuntimeError("storage config failed")),
+    )
+
+    flow = _build_flow(tmp_path)
+    with pytest.raises(RuntimeError, match="storage config failed"):
+        flow.fn(dry_run=False)  # type: ignore[attr-defined]
+
+    uninstall.assert_called_once_with()

{loom_kernel-0.12.0 → loom_kernel-0.12.2}/uv.lock

@@ -1583,7 +1583,7 @@ wheels = [
 
 [[package]]
 name = "loom-kernel"
-version = "0.12.0"
+version = "0.12.2"
 source = { editable = "." }
 dependencies = [
     { name = "aiocache" },
@@ -2315,8 +2315,8 @@ name = "pendulum"
 version = "3.2.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "python-dateutil", marker = "python_full_version < '3.13'" },
-    { name = "tzdata", marker = "python_full_version < '3.13'" },
+    { name = "python-dateutil" },
+    { name = "tzdata" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/cb/72/9a51afa0a822b09e286c4cb827ed7b00bc818dac7bd11a5f161e493a217d/pendulum-3.2.0.tar.gz", hash = "sha256:e80feda2d10fa3ff8b1526715f7d33dcb7e08494b3088f2c8a3ac92d4a4331ce", size = 86912, upload-time = "2026-01-30T11:22:24.093Z" }
 wheels = [
@@ -3951,8 +3951,8 @@ name = "whenever"
 version = "0.10.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "tzdata", marker = "python_full_version >= '3.13' and sys_platform == 'win32'" },
-    { name = "tzlocal", marker = "python_full_version >= '3.13' and sys_platform != 'darwin' and sys_platform != 'linux'" },
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+    { name = "tzlocal", marker = "sys_platform != 'darwin' and sys_platform != 'linux'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/fd/13/281bc0bc19f0e2e9559a22137607271d6e684b0f9bcbaf0a95b95a5e9258/whenever-0.10.0.tar.gz", hash = "sha256:a5ef2b5493531de95294080495d4d9bce9691b4b3d681c6952c7a8b3d52d7a04", size = 429588, upload-time = "2026-04-05T18:43:50.199Z" }
 wheels = [

loom_kernel-0.12.0/CHANGELOG_RELEASE.md

@@ -1,80 +0,0 @@
-# 🚀 Release 0.12.0 ([#64](https://github.com/the-reacher-data/loom-py/pull/64)) ([`a471a17`](https://github.com/the-reacher-data/loom-py/commit/a471a17337d2d63b66fad0f74c81b199b943e588))
-
-
-## ✨ Features
-### etl
-- **etl:** add ClientStep for side-effect engine commands<br>
-  > Introduces a new step type for executing ClickHouse DDL, OPTIMIZE,
-  > ALTER TABLE DROP PARTITION, and similar commands that need the native
-  > engine client but produce no DataFrame output.
-  > New public API:
-  > `ClientStep[ParamsT]` — base class; implement `execute(params, *, client)`
-  > `IntoClient` / `ClientSpec` — target sentinel that bypasses read-write path
-  > `ClientCommandExecutor` protocol — injected capability; method is `command(fn)`
-  > `ClickHouseClientExecutor` — standalone executor with lazy thread-safe client
-  > `ETLRunner(client_executor=...)` / `ETLExecutor(client_executor=...)` params
-  > Architecture decisions:
-  > `ETLExecutor.run_step` short-circuits to `client_executor.command(fn)` before
-  > any source reads when `target_binding.spec` is `ClientSpec`
-  > Compiler skips execute-signature validation for `ClientStep` subclasses
-  > `_write_policy` and `ClickHouseTargetWriter.write()` raise on `ClientSpec`
-  > as a defence-in-depth guard
-  > `ETLStep._log` class variable set by `__init_subclass__` gives every step
-  > a structured logger named after the concrete step class
-  > Module-level `try/except` imports replace lazy function-level imports;
-  > `threading.Lock` guards lazy client init under parallel step execution
-  > Also fixes a pre-existing return type annotation in `_historify.py`:
-  > `pl.Datetime("us", "UTC")` is an instance, not `type[pl.Datetime]`.
-  > Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
-
-- **etl:** ClickHouseSourceReader implements ClientCommandExecutor<br>
-  > Allows passing the existing ClickHouseSourceReader as client_executor
-  > to ETLRunner / ETLExecutor, reusing the same connection for both
-  > DataFrame reads and ClientStep side-effect commands — no second
-  > ClickHouse connection opened.
-  > Changes:
-  > `ClickHouseSourceReader` now inherits `ClientCommandExecutor` and
-  > exposes `command(fn)` which lazily resolves the client via the same
-  > `_get_client()` path used by `read()` and `read_streaming()`
-  > `threading.Lock` and double-check pattern protect the shared lazy
-  > client init against concurrent access under `ParallelStepGroup`
-  > Module-level `try/except` imports for `clickhouse_connect` and
-  > `pyarrow` replace lazy function-level imports
-  > Usage:
-  > ch_reader = ClickHouseSourceReader(url="clickhouse://...")
-  > runner = ETLRunner(
-  > reader=ch_reader,
-  > writer=ch_writer,
-  > client_executor=ch_reader,  # reuses the same connection
-  > )
-  > Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
-
-
-### prefect
-- **prefect:** wrap ETLProcess instances as Prefect subflows<br>
-  > Each ETLProcess now runs inside a nested @prefect.flow, giving the Prefect
-  > UI a process-level hierarchy instead of a flat list of 300 tasks.
-  > PrefectTaskRunObserver resolves the active flow_run_id at task-creation
-  > time via prefect.runtime, so task runs attach to the correct subflow
-  > automatically. Fallback to the stored flow_run_id keeps unit tests intact.
-  > Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
-
-
-
-## 🐛 Fixes
-### tests
-- **tests:** resolve Sonar collection-access issues in test_client_step<br>
-  > Replace [0] index access with tuple unpacking to eliminate potential
-  > IndexError; replace == [] comparisons with `not collection` idiom.
-  > Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
-  > --------
-  > Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
-
-
-
-
-
-
-
-
-