loom-kernel 2.15.1__tar.gz → 2.16.0__tar.gz

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/CHANGELOG.md

@@ -225,6 +225,11 @@
   downstream run inherits the placeholder text and resolves it against its own
   creation time. Without `trigger` the deployment is registered exactly as
   before.
+- **prefect:** `FlowTrigger`, the decoded `trigger` block, is exported from
+  `loom.prefect` and `loom.prefect.flow`, and `check_inherited_params(trigger,
+  params_type, *, name)` from `loom.prefect.flow`, so CI can check that every
+  inherited parameter is a field declared `str`, `date` or `datetime` without
+  building the flow.
 
 ### etl
 
@@ -278,6 +283,36 @@
   `MISSING_CONFIG_PARAMS`, `CONFIG_ALIAS_CONFLICT` and
   `UNSUPPORTED_CONFIG_VALUE`. `ETLRunner`, `ETLRunner.from_config`,
   `ETLCompiler` and `ETLExecutor` take `agents=`. Polars only.
+- **etl:** `loom.etl.compiler.filter_plan(plan, include)` returns the plan
+  `ETLRunner.run(..., include=...)` executes: a process name keeps the whole
+  process, a step name keeps that step, and a name that is neither raises
+  `InvalidStageError`, listing the unknown names sorted, so a deployment's
+  selection can be checked without running it. A bare string as `include`
+  raises `TypeError`. The runner now filters through it. `InvalidStageError`
+  is exported from `loom.etl.compiler` as well; it is the same class as
+  `loom.etl.runner.InvalidStageError` and `loom.etl.InvalidStageError`.
+- **etl:** `iter_processes`, `iter_steps_in_process` and `iter_all_steps` are
+  exported from `loom.etl.compiler`. They flatten a compiled plan in
+  execution order, parallel groups in declaration order, so code that walks
+  a plan no longer reimplements them over the private `_plan` module.
+- **etl:** `loom.etl.backends.polars.decode_json_columns(frame, json_columns)`
+  decodes JSON text columns exactly as the Polars reader does for a source
+  declared with `parse_json`, normalising fields whose JSON type changes
+  between rows, and returns a frame of the same kind, eager or lazy. The
+  reader decodes through it. `FromTable.json_columns` and
+  `FromFile.json_columns` expose the declarations it takes, so a test can
+  decode a seed as the step would receive it. Spark keeps its `from_json`
+  decoding, which has no normalisation to share.
+- **etl:** `IntoTable(...).replace(allow_empty=False)` refuses to wipe a table
+  with an empty frame: the writer raises `EmptyReplaceError` (a `ValueError`,
+  exported from `loom.etl`, carrying `table_ref`) before it creates or writes
+  anything, so a dimension rebuilt from a read that came back empty keeps its
+  rows and the step fails. Polars checks the row count of the frame the
+  replace already collects, at no extra cost; Spark runs `isEmpty()`, one
+  job that stops at the first row, before the write recomputes the frame. On
+  Polars a `Null`-typed column still fails first, with `SchemaError`.
+  The default, `allow_empty=True`, keeps today's behaviour, and `ReplaceSpec`
+  gains the `allow_empty` field.
 
 ## ⚠ Behaviour changes
 
@@ -368,6 +403,14 @@
   which is harmless. The update is one attempt with a 10-second timeout; if
   it fails, the flow logs it at `ERROR` in the run's logs and goes on.
 
+### etl
+
+- **etl:** the names of `loom.etl.runner.filtering` (`_filter_plan`,
+  `_filter_process`, `_collect_all_names`, `_map_pipeline_nodes`,
+  `_map_process_nodes`) are deprecated and removed in loom 3.0; each emits a
+  `DeprecationWarning` naming its replacement, `loom.etl.compiler.filter_plan`
+  or, for `_collect_all_names`, `iter_processes` and `iter_all_steps`.
+
 ## 🐛 Fixes
 
 ### core

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.15.1
+Version: 2.16.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/__init__.py

@@ -55,6 +55,7 @@ from loom.etl.declarative import (
     CsvReadOptions,
     CsvWriteOptions,
     DeletePolicy,
+    EmptyReplaceError,
     ExcelReadOptions,
     Format,
     FromConfig,
@@ -203,6 +204,7 @@ __all__ = [
     "HistorifyKeyConflictError",
     "HistorifyDateCollisionError",
     "HistorifyTemporalConflictError",
+    "EmptyReplaceError",
     # intermediates
     "CheckpointCleaner",
     "CheckpointScope",

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/backends/_write_policy.py

@@ -15,6 +15,7 @@ from loom.core.logger import get_logger
 from loom.etl.declarative.target import (
     AppendSpec,
     ClientSpec,
+    EmptyReplaceError,
     FileSpec,
     ReplacePartitionsSpec,
     ReplaceSpec,
@@ -188,6 +189,7 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
         streaming: bool,
         create_partition_cols: tuple[str, ...] = (),
         require_physical_partitions: tuple[str, ...] | None = None,
+        allow_empty: bool = True,
     ) -> _PreparedWrite[WriteFrameT, PhysicalSchemaT] | None:
         """Run the shared policy up to the point where the write mode differs.
 
@@ -207,6 +209,10 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             require_physical_partitions: Partition columns the existing table
                                          must physically carry, or ``None`` to
                                          skip that check.
+            allow_empty:                 When ``False``, raise
+                                         :class:`EmptyReplaceError` for a
+                                         frame with no rows, before the table
+                                         is created or written.
 
         Returns:
             The prepared write when the table already exists and the caller
@@ -220,7 +226,9 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
                 schema_mode=schema_mode,
                 missing_table_policy=self._missing_table_policy,
             )
-            materialized = self._materialize_checked(frame, target, streaming)
+            materialized = self._materialize_checked(
+                frame, target, streaming, allow_empty=allow_empty
+            )
             self._create(
                 materialized,
                 target,
@@ -232,7 +240,7 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             self._require_physical_partitions(target, require_physical_partitions)
         aligned = self._align(frame, existing, schema_mode)
         return _PreparedWrite(
-            frame=self._materialize_checked(aligned, target, streaming),
+            frame=self._materialize_checked(aligned, target, streaming, allow_empty=allow_empty),
             existing_schema=existing,
         )
 
@@ -260,7 +268,11 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
     ) -> None:
         """Replace policy: check exists → create OR align → write."""
         prepared = self._prepare_write(
-            frame, target, schema_mode=spec.schema_mode, streaming=streaming
+            frame,
+            target,
+            schema_mode=spec.schema_mode,
+            streaming=streaming,
+            allow_empty=spec.allow_empty,
         )
         if prepared is None:
             return
@@ -507,15 +519,29 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
         _ = frame
         return None
 
+    @abstractmethod
+    def _is_empty(self, frame: WriteFrameT) -> bool:
+        """Whether the materialised *frame* has no rows."""
+
     def _materialize_checked(
         self,
         frame: InputFrameT,
         target: ResolvedTarget,
         streaming: bool,
+        *,
+        allow_empty: bool = True,
     ) -> WriteFrameT:
-        """Materialise *frame*, warning when the write carries no rows."""
+        """Materialise *frame*, warning when the write carries no rows.
+
+        Raises:
+            EmptyReplaceError: When *allow_empty* is ``False`` and the
+                materialised frame has no rows.
+        """
         materialized = self._materialize_for_write(frame, streaming)
-        if self._row_count_if_cheap(materialized) == 0:
+        if not allow_empty:
+            if self._is_empty(materialized):
+                raise EmptyReplaceError(target.logical_ref.ref)
+        elif self._row_count_if_cheap(materialized) == 0:
             _log.warning("write_produced_no_rows", target=target.logical_ref.ref)
         return materialized
 

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/backends/polars/__init__.py

@@ -1,7 +1,7 @@
 """Polars backend for the Loom ETL framework."""
 
 from loom.etl.backends.polars._file_writer import PolarsFileWriter
-from loom.etl.backends.polars._reader import PolarsSourceReader
+from loom.etl.backends.polars._reader import PolarsSourceReader, decode_json_columns
 from loom.etl.backends.polars._schema import PolarsPhysicalSchema, read_delta_physical_schema
 from loom.etl.backends.polars._writer import PolarsTargetWriter
 
@@ -10,5 +10,6 @@ __all__ = [
     "PolarsPhysicalSchema",
     "PolarsSourceReader",
     "PolarsTargetWriter",
+    "decode_json_columns",
     "read_delta_physical_schema",
 ]

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/backends/polars/_reader.py

@@ -5,8 +5,8 @@ from __future__ import annotations
 import functools
 import json
 import logging
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Any, TypeVar
 
 if TYPE_CHECKING:
     from loom.etl.io.sources._clickhouse import ClickHouseSourceReader
@@ -23,6 +23,7 @@ from loom.etl.declarative.source import FileSourceSpec, SourceSpec, TableSourceS
 from loom.etl.declarative.source._specs import (
     ClickHouseSourceSpec,
     DynamoDbSourceSpec,
+    JsonColumnSpec,
     MongoSourceSpec,
 )
 from loom.etl.runtime.contracts import SourceReader
@@ -43,6 +44,8 @@ from ._predicate import predicate_to_polars
 
 _log = logging.getLogger(__name__)
 
+_FrameT = TypeVar("_FrameT", pl.DataFrame, pl.LazyFrame)
+
 
 # ---------------------------------------------------------------------------
 # Polymorphic JSON normalization
@@ -124,6 +127,49 @@ def _normalize_json_string(json_str: str | None, *, loom_type: LoomType) -> str
     return json.dumps(result, ensure_ascii=False)
 
 
+def decode_json_columns(frame: _FrameT, json_columns: Iterable[JsonColumnSpec]) -> _FrameT:
+    """Decode JSON string columns the way :class:`PolarsSourceReader` does at read time.
+
+    Each column named in *json_columns* holds JSON text and is replaced by the
+    value decoded into its declared :class:`~loom.etl.schema.LoomType`. Rows
+    are first normalised to that type, so a field that is a string in some rows
+    and an object in others decodes instead of raising
+    :exc:`polars.exceptions.ComputeError`. A null or unparseable value decodes
+    to null. Other columns pass through unchanged.
+
+    Use it to reproduce in a test what a step receives from a source declared
+    with ``parse_json``.
+
+    Args:
+        frame: Eager or lazy frame holding the JSON text columns.
+        json_columns: Column declarations, e.g. ``FromTable(...).json_columns``
+            or ``FromFile(...).json_columns``.
+
+    Returns:
+        A frame of the same kind as *frame*, or *frame* itself when
+        *json_columns* is empty.
+
+    Example::
+
+        from loom.etl.backends.polars import decode_json_columns
+
+        events = FromTable("raw.events").parse_json("payload", Payload)
+        decoded = decode_json_columns(raw_frame, events.json_columns)
+    """
+    exprs = [
+        pl.col(jc.column)
+        .map_elements(
+            functools.partial(_normalize_json_string, loom_type=jc.loom_type),
+            return_dtype=pl.String,
+        )
+        .str.json_decode(loom_type_to_polars(jc.loom_type))
+        for jc in json_columns
+    ]
+    if not exprs:
+        return frame
+    return frame.with_columns(exprs)
+
+
 class PolarsSourceReader(SourceReader):
     """Read table, file, and MongoDB sources using Polars."""
 
@@ -351,21 +397,10 @@ class PolarsSourceReader(SourceReader):
         Applies a per-row normalization pass before ``json_decode`` so that
         polymorphic fields (e.g. ``String`` in some rows, ``Object`` in others)
         are coerced to the declared :class:`~loom.etl.schema.LoomType` without
-        raising :exc:`polars.exceptions.ComputeError`.
+        raising :exc:`polars.exceptions.ComputeError`. See
+        :func:`decode_json_columns`.
         """
-        if not json_columns:
-            return frame
-
-        exprs = [
-            pl.col(jc.column)
-            .map_elements(
-                functools.partial(_normalize_json_string, loom_type=jc.loom_type),
-                return_dtype=pl.String,
-            )
-            .str.json_decode(loom_type_to_polars(jc.loom_type))
-            for jc in json_columns
-        ]
-        return frame.with_columns(exprs)
+        return decode_json_columns(frame, json_columns)
 
 
 def _apply_source_schema(frame: pl.LazyFrame, schema: tuple[ColumnSchema, ...]) -> pl.LazyFrame:
@@ -374,8 +409,8 @@ def _apply_source_schema(frame: pl.LazyFrame, schema: tuple[ColumnSchema, ...])
 
 
 def _apply_json_decode(frame: pl.LazyFrame, json_columns: tuple[Any, ...]) -> pl.LazyFrame:
-    """Compatibility helper used by tests."""
-    return PolarsSourceReader._apply_json_decode(frame, json_columns)
+    """Compatibility alias of :func:`decode_json_columns`."""
+    return decode_json_columns(frame, json_columns)
 
 
 def execute_sql(frames: dict[str, pl.LazyFrame], query: str) -> pl.LazyFrame:
@@ -386,4 +421,10 @@ def execute_sql(frames: dict[str, pl.LazyFrame], query: str) -> pl.LazyFrame:
     return ctx.execute(query, eager=False)
 
 
-__all__ = ["PolarsSourceReader", "execute_sql", "_apply_source_schema", "_apply_json_decode"]
+__all__ = [
+    "PolarsSourceReader",
+    "decode_json_columns",
+    "execute_sql",
+    "_apply_source_schema",
+    "_apply_json_decode",
+]

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/backends/polars/_writer.py

@@ -217,6 +217,10 @@ class PolarsTargetWriter(_WritePolicy[pl.LazyFrame, pl.DataFrame, PolarsPhysical
         """Rows in the collected frame."""
         return frame.height
 
+    def _is_empty(self, frame: pl.DataFrame) -> bool:
+        """Whether the collected frame has no rows."""
+        return frame.is_empty()
+
     def _materialize_for_write(self, frame: pl.LazyFrame, streaming: bool) -> pl.DataFrame:
         """Collect lazy frame to DataFrame before Delta write."""
         df = frame.collect(engine="streaming" if streaming else "auto")

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/backends/spark/_writer.py

@@ -143,6 +143,10 @@ class SparkTargetWriter(_WritePolicy[DataFrame, DataFrame, SparkPhysicalSchema])
         _ = streaming
         return frame
 
+    def _is_empty(self, frame: DataFrame) -> bool:
+        """Whether *frame* has no rows; runs one Spark job that stops at the first row."""
+        return frame.isEmpty()
+
     def _predicate_to_sql(self, predicate: Any, params: Any) -> str:
         """Convert predicate to SQL."""
         return predicate_to_sql(predicate, params)

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/compiler/__init__.py

@@ -2,6 +2,7 @@
 
 from loom.etl.compiler._compiler import ETLCompiler
 from loom.etl.compiler._errors import ETLCompilationError, ETLErrorCode
+from loom.etl.compiler._filter import InvalidStageError, filter_plan
 from loom.etl.compiler._plan import (
     AgentBinding,
     ConfigValueBinding,
@@ -13,6 +14,9 @@ from loom.etl.compiler._plan import (
     StepPlan,
     TargetBinding,
     flatten_step_names,
+    iter_all_steps,
+    iter_processes,
+    iter_steps_in_process,
 )
 from loom.etl.compiler._validators import (
     StepCompilationContext,
@@ -31,6 +35,7 @@ __all__ = [
     "ETLCompiler",
     "ETLCompilationError",
     "ETLErrorCode",
+    "InvalidStageError",
     "StepPlan",
     "ProcessPlan",
     "PipelinePlan",
@@ -41,7 +46,11 @@ __all__ = [
     "ParallelStepGroup",
     "ParallelProcessGroup",
     "StepCompilationContext",
+    "filter_plan",
     "flatten_step_names",
+    "iter_all_steps",
+    "iter_processes",
+    "iter_steps_in_process",
     "validate_execute_signature",
     "validate_param_exprs",
     "validate_params_compat",

loom_kernel-2.15.1/src/loom/etl/runner/filtering.py → loom_kernel-2.16.0/src/loom/etl/compiler/_filter.py

@@ -1,8 +1,12 @@
-"""Plan filtering helpers used by ETLRunner.run(include=...)."""
+"""Plan filtering: keep the steps and processes a run selects by name.
+
+Internal module — import :func:`filter_plan` and :class:`InvalidStageError`
+from :mod:`loom.etl.compiler`.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 
 from loom.etl.compiler._plan import (
     ParallelProcessGroup,
@@ -15,26 +19,62 @@ from loom.etl.compiler._plan import (
     iter_all_steps,
     iter_processes,
 )
-from loom.etl.runner.errors import InvalidStageError
 
 
-def _filter_plan(plan: PipelinePlan, include: frozenset[str]) -> PipelinePlan:
-    """Return a new :class:`PipelinePlan` keeping only nodes matched by *include*.
+class InvalidStageError(ValueError):
+    """Raised when *include* names a step or process absent from the compiled plan.
+
+    Args:
+        include: The names that match no step or process.
+    """
+
+    def __init__(self, include: frozenset[str]) -> None:
+        super().__init__(
+            f"No steps or processes match include={sorted(include)!r}. "
+            "Check that the names match the class names of your ETLStep or ETLProcess subclasses."
+        )
+
+
+def filter_plan(plan: PipelinePlan, include: Iterable[str]) -> PipelinePlan:
+    """Return a new plan keeping only the steps and processes named in *include*.
+
+    This is the selection :meth:`~loom.etl.runner.ETLRunner.run` applies for
+    ``include=``. A process name keeps the whole process; a step name keeps
+    that step inside its process. A process left with no step is dropped, and
+    a parallel group left with one member becomes that member. Execution
+    order and the remaining parallel groups are preserved.
 
     Args:
-        plan: Fully compiled pipeline plan.
-        include: Set of step or process class names to keep.
+        plan: Compiled pipeline plan, as returned by
+            :meth:`~loom.etl.compiler.ETLCompiler.compile`.
+        include: Class names of steps or processes to keep. A bare string is
+            refused rather than read as its characters.
 
     Returns:
-        Filtered :class:`PipelinePlan`.
+        A new :class:`PipelinePlan`; *plan* is not modified.
 
     Raises:
-        InvalidStageError: When any name in *include* does not exist in the plan.
+        TypeError: When *include* is a ``str``.
+        InvalidStageError: When a name in *include* is neither a step nor a
+            process of *plan*.
+
+    Example::
+
+        >>> from loom.etl.compiler import ETLCompiler, filter_plan, iter_all_steps
+        >>> plan = filter_plan(ETLCompiler().compile(MyPipeline), {"LoadStep"})
+        >>> [step.step_type.__name__ for step in iter_all_steps(plan)]
+        ['LoadStep']
     """
-    unknown = include - _collect_all_names(plan)
+    if isinstance(include, str):
+        raise TypeError(
+            f"filter_plan() takes an iterable of names, not the string {include!r}; "
+            f"wrap it, e.g. include={{{include!r}}}."
+        )
+    names = frozenset(include)
+    unknown = names - _collect_all_names(plan)
     if unknown:
-        raise InvalidStageError(frozenset(unknown))
-    nodes = _map_pipeline_nodes(plan.nodes, lambda proc: _filter_process(proc, include))
+        raise InvalidStageError(unknown)
+    nodes = _map_pipeline_nodes(plan.nodes, lambda proc: _filter_process(proc, names))
     return PipelinePlan(
         pipeline_type=plan.pipeline_type,
         params_type=plan.params_type,
@@ -105,3 +145,6 @@ def _map_process_nodes(
                 elif kept:
                     result.append(ParallelStepGroup(plans=kept))
     return tuple(result)
+
+
+__all__ = ["InvalidStageError", "filter_plan"]

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/compiler/_plan.py

@@ -163,6 +163,12 @@ def iter_processes(plan: PipelinePlan) -> Iterator[ProcessPlan]:
 
     Flattens top-level :class:`ParallelProcessGroup` nodes while preserving
     the declared order within each group.
+
+    Args:
+        plan: Compiled pipeline plan.
+
+    Yields:
+        Each :class:`ProcessPlan` of *plan*, once.
     """
     for node in plan.nodes:
         match node:
@@ -177,6 +183,12 @@ def iter_steps_in_process(plan: ProcessPlan) -> Iterator[StepPlan]:
 
     Flattens :class:`ParallelStepGroup` nodes while preserving the declared
     order within each group.
+
+    Args:
+        plan: Compiled process plan, e.g. one yielded by :func:`iter_processes`.
+
+    Yields:
+        Each :class:`StepPlan` of *plan*, once.
     """
     for node in plan.nodes:
         match node:
@@ -187,7 +199,18 @@ def iter_steps_in_process(plan: ProcessPlan) -> Iterator[StepPlan]:
 
 
 def iter_all_steps(plan: PipelinePlan) -> Iterator[StepPlan]:
-    """Yield every concrete step plan in a pipeline."""
+    """Yield every concrete step plan in a pipeline, in execution order.
+
+    Equivalent to :func:`iter_steps_in_process` over each process yielded by
+    :func:`iter_processes`.
+
+    Args:
+        plan: Compiled pipeline plan.
+
+    Yields:
+        Each :class:`StepPlan` of *plan*; a step class listed by two
+        processes is yielded once per process.
+    """
     for proc in iter_processes(plan):
         yield from iter_steps_in_process(proc)
 

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/declarative/__init__.py

@@ -32,6 +32,7 @@ from .source import (
 )
 from .target import (
     DeletePolicy,
+    EmptyReplaceError,
     HistorifyDateCollisionError,
     HistorifyInputMode,
     HistorifyKeyConflictError,
@@ -91,4 +92,6 @@ __all__ = [
     "HistorifyKeyConflictError",
     "HistorifyDateCollisionError",
     "HistorifyTemporalConflictError",
+    # write errors
+    "EmptyReplaceError",
 ]

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/declarative/source/_from.py

@@ -99,6 +99,11 @@ class FromTable:
         """Declared filter predicates."""
         return self._predicates
 
+    @property
+    def json_columns(self) -> tuple[JsonColumnSpec, ...]:
+        """JSON columns declared with :meth:`parse_json`, in declaration order."""
+        return self._json_columns
+
     def with_schema(self, schema: SchemaContract) -> FromTable:
         """Return a new ``FromTable`` with a user-declared source schema.
 
@@ -298,6 +303,11 @@ class FromFile:
         """File path template."""
         return self._path
 
+    @property
+    def json_columns(self) -> tuple[JsonColumnSpec, ...]:
+        """JSON columns declared with :meth:`parse_json`, in declaration order."""
+        return self._json_columns
+
     @property
     def format(self) -> Format:
         """I/O format."""

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/declarative/target/__init__.py

@@ -35,9 +35,14 @@ SCD2 support types:
 * :class:`HistorifyKeyConflictError`   — duplicate entity state vectors
 * :class:`HistorifyDateCollisionError` — same-date LOG mode collisions
 * :class:`HistorifyTemporalConflictError` — future-open records without re-weave
+
+Write errors:
+
+* :class:`EmptyReplaceError` — ``replace(allow_empty=False)`` received no rows
 """
 
 from loom.etl.declarative.target._client import ClientSpec, IntoClient
+from loom.etl.declarative.target._errors import EmptyReplaceError
 from loom.etl.declarative.target._file import FileSpec
 from loom.etl.declarative.target._history import (
     DeletePolicy,
@@ -127,4 +132,6 @@ __all__ = [
     "HistorifyKeyConflictError",
     "HistorifyDateCollisionError",
     "HistorifyTemporalConflictError",
+    # write errors
+    "EmptyReplaceError",
 ]

loom_kernel-2.16.0/src/loom/etl/declarative/target/_errors.py

@@ -0,0 +1,30 @@
+"""Errors raised by backend writers for table targets.
+
+Internal module — import from :mod:`loom.etl.declarative.target` or :mod:`loom.etl`.
+"""
+
+from __future__ import annotations
+
+
+class EmptyReplaceError(ValueError):
+    """Raised when a ``replace(allow_empty=False)`` target receives no rows.
+
+    The table is left as it was: the check runs after the frame is
+    materialised and before anything is written or created.
+
+    Args:
+        table_ref: Logical reference of the target table.
+
+    Attributes:
+        table_ref: Logical reference of the target table.
+    """
+
+    def __init__(self, table_ref: str) -> None:
+        self.table_ref = table_ref
+        super().__init__(
+            f"Refusing to replace {table_ref!r} with an empty frame: the target declares "
+            "replace(allow_empty=False). The table was not modified."
+        )
+
+
+__all__ = ["EmptyReplaceError"]

{loom_kernel-2.15.1 → loom_kernel-2.16.0}/src/loom/etl/declarative/target/_into.py

@@ -108,6 +108,7 @@ class IntoTable:
         *,
         schema: SchemaMode = SchemaMode.STRICT,
         streaming: bool = False,
+        allow_empty: bool = True,
     ) -> IntoTable:
         """Write mode: full replace of the target table.
 
@@ -115,16 +116,33 @@ class IntoTable:
         partition-scoped overwrite or :meth:`replace_where` for predicate-scoped.
 
         Args:
-            schema:    Schema evolution strategy.  Use
-                       :attr:`~SchemaMode.OVERWRITE` to replace the table schema
-                       entirely alongside the data.
-            streaming: When ``True`` the Polars backend writes via an Arrow
-                       ``RecordBatchReader`` instead of materialising.
+            schema:      Schema evolution strategy.  Use
+                         :attr:`~SchemaMode.OVERWRITE` to replace the table
+                         schema entirely alongside the data.
+            streaming:   When ``True`` the Polars backend writes via an Arrow
+                         ``RecordBatchReader`` instead of materialising.
+            allow_empty: When ``False``, a frame with no rows raises
+                         :class:`~loom.etl.EmptyReplaceError` and the table
+                         is neither replaced nor created.  Use it for a
+                         table, such as a dimension, that an empty read must
+                         never wipe.  Defaults to ``True``: an empty frame
+                         replaces the table with an empty one.
 
         Returns:
             New ``IntoTable`` with REPLACE mode.
+
+        Example::
+
+            target = IntoTable("silver.dim_dealer").replace(allow_empty=False)
         """
-        return self._with(ReplaceSpec(table_ref=self._ref, schema_mode=schema, streaming=streaming))
+        return self._with(
+            ReplaceSpec(
+                table_ref=self._ref,
+                schema_mode=schema,
+                streaming=streaming,
+                allow_empty=allow_empty,
+            )
+        )
 
     def replace_partitions(
         self,