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

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

@@ -225,6 +225,24 @@
   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.
+- **prefect:** `deploy_flow(flow, *, env, work_pool=None)`, exported from
+  `loom.prefect` and `loom.prefect.deploy`, registers the deployment of one
+  flow built by `etl_flow`, `backfill_flow` or `maintenance_flow`, with the
+  same name, tags, parameters, schedule, trigger and work-pool settings
+  `discover_and_deploy_etls(flows_package=...)` gives it, and returns its id.
+  Flows built on demand, such as by a module `__getattr__`, or a single ETL
+  deployed by name no longer need the private `_deploy_single` and metadata
+  attribute. `env` is required; `work_pool` is used when the YAML names no
+  pool for `env`, and with neither it raises `ValueError`. Before registering
+  it checks that the flow's `source_file` exposes the flow under its
+  attribute name (the flow name with `-` replaced by `_`), as the worker
+  imports it, and raises `ValueError` otherwise; a module not yet imported is
+  imported from that file. Any other object raises `TypeError`.
 
 ### etl
 
@@ -278,6 +296,52 @@
   `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`. On
+  Spark a streaming DataFrame, whose rows cannot be counted before the
+  write, raises `ValueError` and the table is left as it was.
+  The default, `allow_empty=True`, keeps today's behaviour, and `ReplaceSpec`
+  gains the `allow_empty` field.
+- **etl:** `MaintenanceSpec`, `VacuumSpec`, `CompactSpec` and `ZOrderSpec` are
+  exported from `loom.etl.maintenance`, next to `OpSpec` and
+  `OperationDeclaration`, so a custom maintenance op (an `OpSpec` appended to
+  each `MaintenanceSpec` by a wrapping `OperationDeclaration`) and a custom
+  `DeltaTableMaintainer` are written without the private `_ops` module. The
+  ETL guide and the package docstring show how to write one.
+- **etl:** `loom.etl.schema.annotation_to_loom_type(ann)` converts one Python
+  type annotation to the `LoomType` it declares, as `resolve_schema` does for
+  each field of a contract (`X | None` maps as `X`; an unsupported annotation
+  raises `TypeError`), and `loom.etl.backends.polars` exports
+  `loom_type_to_polars` and `polars_to_loom_type`, so the Polars dtype of a
+  contract field is `loom_type_to_polars(annotation_to_loom_type(ann))`. The
+  private names `loom.etl.schema._contract._annotation_to_loom_type` and
+  `loom.etl.backends.polars._dtype.*` keep working.
 
 ## ⚠ Behaviour changes
 
@@ -367,6 +431,24 @@
   placeholders it started with and repeats the call with the same values,
   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.
+- **prefect:** the private `_deploy_single(flow, meta, work_pool, env)` of
+  `loom.prefect.deploy._discovery` now takes `(flow, meta, plan)`; callers
+  migrate to the public `deploy_flow(flow, env=..., work_pool=...)`.
+
+### 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`.
+- **etl:** `InvalidStageError` names what it reports: its message reads
+  `Unknown step or process names: [...]` instead of `No steps or processes
+  match include=[...]`, the constructor's parameter is `unknown`, and the
+  names are kept on the new `unknown` attribute. Positional construction is
+  unchanged; `InvalidStageError(include=...)` still works, emits a
+  `DeprecationWarning` and is removed in loom 3.0. The error survives pickle
+  with its `unknown` names, so it crosses process boundaries intact.
 
 ## 🐛 Fixes
 

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

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

{loom_kernel-2.15.1 → loom_kernel-2.17.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.17.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,36 @@ 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.
+
+        Raises:
+            ValueError: When the backend cannot count the rows of *frame*
+                before the write, such as a Spark streaming DataFrame.
+        """
+
     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.
+            ValueError: When *allow_empty* is ``False`` and the backend
+                cannot count the rows of the materialised frame.
+        """
         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.17.0}/src/loom/etl/backends/polars/__init__.py

@@ -1,7 +1,8 @@
 """Polars backend for the Loom ETL framework."""
 
+from loom.etl.backends.polars._dtype import loom_type_to_polars, polars_to_loom_type
 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 +11,8 @@ __all__ = [
     "PolarsPhysicalSchema",
     "PolarsSourceReader",
     "PolarsTargetWriter",
+    "decode_json_columns",
+    "loom_type_to_polars",
+    "polars_to_loom_type",
     "read_delta_physical_schema",
 ]

{loom_kernel-2.15.1 → loom_kernel-2.17.0}/src/loom/etl/backends/polars/_dtype.py

@@ -1,6 +1,7 @@
 """LoomType ↔ Polars DataType conversion utilities.
 
-Internal module — not part of the public API.
+Internal module — import ``loom_type_to_polars`` and ``polars_to_loom_type``
+from :mod:`loom.etl.backends.polars`.
 
 Two conversion layers
 ---------------------

{loom_kernel-2.15.1 → loom_kernel-2.17.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.17.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.17.0}/src/loom/etl/backends/spark/_writer.py

@@ -143,6 +143,21 @@ 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.
+
+        Raises:
+            ValueError: When *frame* is a streaming DataFrame, whose rows
+                cannot be counted before the write.
+        """
+        if frame.isStreaming:
+            raise ValueError(
+                "replace(allow_empty=False) needs a batch DataFrame to check for rows, "
+                "but the frame to write is a streaming DataFrame. Read the source as a "
+                "batch DataFrame or declare replace() without allow_empty=False."
+            )
+        return bool(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.17.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.17.0/src/loom/etl/compiler/_filter.py

@@ -0,0 +1,186 @@
+"""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
+
+import warnings
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from loom.etl.compiler._plan import (
+    ParallelProcessGroup,
+    ParallelStepGroup,
+    PipelinePlan,
+    PipelineProcessNode,
+    ProcessPlan,
+    ProcessStepNode,
+    StepPlan,
+    iter_all_steps,
+    iter_processes,
+)
+
+
+class InvalidStageError(ValueError):
+    """Raised when a selection names a step or process absent from the compiled plan.
+
+    Args:
+        unknown: The selected names that match no step or process.
+        include: Deprecated keyword spelling of *unknown*, removed in loom 3.0.
+
+    Attributes:
+        unknown: The selected names that match no step or process.
+
+    Raises:
+        TypeError: When both or neither of *unknown* and *include* are given.
+    """
+
+    def __init__(
+        self,
+        unknown: frozenset[str] | None = None,
+        *,
+        include: frozenset[str] | None = None,
+    ) -> None:
+        self.unknown = _unknown_names(unknown, include)
+        super().__init__(
+            f"Unknown step or process names: {sorted(self.unknown)!r}. "
+            "Check that the names match the class names of your ETLStep or ETLProcess subclasses."
+        )
+
+    def __reduce__(self) -> tuple[type[InvalidStageError], tuple[frozenset[str]], dict[str, Any]]:
+        return type(self), (self.unknown,), self.__dict__
+
+
+def _unknown_names(
+    unknown: frozenset[str] | None, include: frozenset[str] | None
+) -> frozenset[str]:
+    if include is None:
+        if unknown is None:
+            raise TypeError("InvalidStageError() requires the unknown names.")
+        return frozenset(unknown)
+    if unknown is not None:
+        raise TypeError("InvalidStageError() takes unknown= or the deprecated include=, not both.")
+    warnings.warn(
+        "InvalidStageError(include=...) is deprecated and will be removed in loom 3.0; "
+        "use InvalidStageError(unknown=...) instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+    return frozenset(include)
+
+
+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: 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:
+        A new :class:`PipelinePlan`; *plan* is not modified.
+
+    Raises:
+        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']
+    """
+    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(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,
+        nodes=nodes,
+    )
+
+
+def _filter_process(plan: ProcessPlan, include: frozenset[str]) -> ProcessPlan | None:
+    if plan.process_type.__name__ in include:
+        return plan
+    nodes = _map_process_nodes(
+        plan.nodes,
+        lambda step: step if step.step_type.__name__ in include else None,
+    )
+    if not nodes:
+        return None
+    return ProcessPlan(
+        process_type=plan.process_type,
+        params_type=plan.params_type,
+        nodes=nodes,
+    )
+
+
+def _collect_all_names(plan: PipelinePlan) -> frozenset[str]:
+    """Collect every step and process class name reachable from *plan*."""
+    names = {proc.process_type.__name__ for proc in iter_processes(plan)}
+    names.update(step.step_type.__name__ for step in iter_all_steps(plan))
+    return frozenset(names)
+
+
+def _map_pipeline_nodes(
+    nodes: tuple[PipelineProcessNode, ...],
+    fn: Callable[[ProcessPlan], ProcessPlan | None],
+) -> tuple[PipelineProcessNode, ...]:
+    """Map/filter process nodes while preserving parallel-group shape."""
+    result: list[PipelineProcessNode] = []
+    for node in nodes:
+        match node:
+            case ProcessPlan():
+                mapped = fn(node)
+                if mapped is not None:
+                    result.append(mapped)
+            case ParallelProcessGroup(plans=plans):
+                kept = tuple(proc for proc in (fn(proc) for proc in plans) if proc is not None)
+                if len(kept) == 1:
+                    result.append(kept[0])
+                elif kept:
+                    result.append(ParallelProcessGroup(plans=kept))
+    return tuple(result)
+
+
+def _map_process_nodes(
+    nodes: tuple[ProcessStepNode, ...],
+    fn: Callable[[StepPlan], StepPlan | None],
+) -> tuple[ProcessStepNode, ...]:
+    """Map/filter step nodes while preserving parallel-group shape."""
+    result: list[ProcessStepNode] = []
+    for node in nodes:
+        match node:
+            case StepPlan():
+                mapped = fn(node)
+                if mapped is not None:
+                    result.append(mapped)
+            case ParallelStepGroup(plans=plans):
+                kept = tuple(step for step in (fn(step) for step in plans) if step is not None)
+                if len(kept) == 1:
+                    result.append(kept[0])
+                elif kept:
+                    result.append(ParallelStepGroup(plans=kept))
+    return tuple(result)
+
+
+__all__ = ["InvalidStageError", "filter_plan"]