loom-kernel 1.3.0__tar.gz → 1.4.0__tar.gz

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/CHANGELOG.md

@@ -1,3 +1,56 @@
+# 🚀 Release 1.4.0 ([#129](https://github.com/the-reacher-data/loom-py/pull/129)) ([`71520ce`](https://github.com/the-reacher-data/loom-py/commit/71520ce4840f8a3b9b914081704520f90d46b31e))
+
+
+## ✨ Features
+### streaming
+- **streaming:** structured compiler error codes and public compiler exports<br>
+  > Replace the compiler's bare list[str] failures with structured issues so a
+  > guided platform can map compilation errors to form fields, mirroring
+  > loom.etl's ETLErrorCode:
+  > New loom.streaming.compiler._errors with StreamingErrorCode (StrEnum
+  > covering the binding, validation, and plan-building phases, plus codes
+  > reserved for the delivery-semantics phase) and CompilationIssue
+  > (LoomFrozenStruct with code, message, component, field). All message
+  > formatting lives in per-code factory functions; validator call-sites stay
+  > intention-revealing.
+  > CompilationError now aggregates issues (.issues) while keeping the legacy
+  > .errors accessor and the exact aggregated message format. The constructor
+  > still accepts bare strings, normalized to code UNSPECIFIED.
+  > Branch validation scopes nested issues via CompilationIssue.prefixed(),
+  > preserving the historical "fork/router/broadcast branch X: ..." messages.
+  > Two previously uncoded build-phase failures now raise CompilationError
+  > with codes: STORAGE_SINK_UNSUPPORTED (was a bare ValueError) and
+  > PAYLOAD_TYPE_INVALID (was an unguarded AttributeError).
+  > validate.py no longer constructs UnsupportedNodeError/MissingSinkError just
+  > to str() them; the exception classes remain runtime errors of the adapter.
+  > Export symmetry: loom.streaming now exports CompilationError, CompiledPlan,
+  > CompilationIssue, and StreamingErrorCode; loom.streaming.compiler adds
+  > CompiledMongoCDCSource. Tests migrated from private to public import paths.
+
+
+
+## 🐛 Fixes
+### docs
+- **docs:** keep compilation types canonical in loom.streaming.compiler<br>
+  > The strict docs build (warnings-as-errors) rejected re-exporting
+  > CompilationError/CompilationIssue/CompiledPlan/StreamingErrorCode at the
+  > loom.streaming package level: both the package and loom.streaming.compiler
+  > pages are in the autosummary, so each symbol was documented twice and
+  > cross-references became ambiguous.
+  > Follow the real loom.etl convention instead: compilation types have a single
+  > canonical import path (loom.streaming.compiler) and the package front-page
+  > docstring points there, exactly like loom.etl does with ETLCompilationError.
+  > compile_flow stays exported at the package level as before.
+  > --------
+
+
+
+
+
+
+
+
+
 # 🚀 Release 1.3.0 ([#127](https://github.com/the-reacher-data/loom-py/pull/127)) ([`1fcaa1c`](https://github.com/the-reacher-data/loom-py/commit/1fcaa1ca1520db435d1ba4974284a96a35d2734f))
 
 

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 1.3.0
+Version: 1.4.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/pyproject.toml

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

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/src/loom/streaming/__init__.py

@@ -14,6 +14,17 @@ Use :mod:`loom.streaming` for user-facing flow declarations::
         StreamShape,
     )
 
+Compilation types (plan, structured errors) live under
+:mod:`loom.streaming.compiler`::
+
+    from loom.streaming.compiler import (
+        CompilationError,
+        CompilationIssue,
+        CompiledPlan,
+        StreamingErrorCode,
+        compile_flow,
+    )
+
 Kafka-specific codecs, clients, and transport settings live under
 :mod:`loom.streaming.kafka`.
 """

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/src/loom/streaming/compiler/__init__.py

@@ -1,8 +1,10 @@
 """Streaming compiler: validates StreamFlow and produces CompiledPlan."""
 
 from loom.streaming.compiler._compiler import compile_flow
+from loom.streaming.compiler._errors import CompilationIssue, StreamingErrorCode
 from loom.streaming.compiler._plan import (
     CompilationError,
+    CompiledMongoCDCSource,
     CompiledMultiSource,
     CompiledNode,
     CompiledPlan,
@@ -15,6 +17,8 @@ from loom.streaming.compiler._plan import (
 __all__ = [
     "compile_flow",
     "CompilationError",
+    "CompilationIssue",
+    "CompiledMongoCDCSource",
     "CompiledMultiSource",
     "CompiledNode",
     "CompiledPlan",
@@ -22,4 +26,5 @@ __all__ = [
     "CompiledSink",
     "CompiledSource",
     "CompiledStorageSink",
+    "StreamingErrorCode",
 ]

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/src/loom/streaming/compiler/_bindings.py

@@ -6,6 +6,13 @@ from collections.abc import Mapping
 from typing import Any, TypeGuard
 
 from loom.core.config import ConfigBinding, ConfigContext, ConfigError
+from loom.streaming.compiler._errors import (
+    CompilationIssue,
+    binding_not_process_node,
+    binding_resolution_failed,
+    fork_selector_missing,
+    step_instantiation_failed,
+)
 from loom.streaming.graph._flow import Process, ProcessNode, StreamFlow
 from loom.streaming.nodes._boundary import IntoTopic
 from loom.streaming.nodes._broadcast import Broadcast, BroadcastRoute
@@ -20,7 +27,7 @@ from loom.streaming.nodes._with import With, WithAsync
 def resolve_flow_bindings(
     flow: StreamFlow[Any, Any],
     ctx: ConfigContext,
-) -> tuple[StreamFlow[Any, Any], list[str]]:
+) -> tuple[StreamFlow[Any, Any], list[CompilationIssue]]:
     """Resolve every config binding reachable from a streaming flow.
 
     The flow declaration remains declarative in user code. This helper
@@ -31,9 +38,9 @@ def resolve_flow_bindings(
         ctx: Runtime config context used for binding resolution.
 
     Returns:
-        A resolved flow plus a list of binding-resolution errors.
+        A resolved flow plus a list of binding-resolution issues.
     """
-    errors: list[str] = []
+    errors: list[CompilationIssue] = []
     resolved_process = _resolve_process(flow.process, ctx, errors)
     resolved_flow = StreamFlow(
         name=flow.name,
@@ -48,7 +55,7 @@ def resolve_flow_bindings(
 def _resolve_process(
     process: Process[Any, Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> Process[Any, Any]:
     nodes = tuple(_resolve_process_node(node, ctx, errors) for node in process.nodes)
     return Process(*nodes)
@@ -57,20 +64,20 @@ def _resolve_process(
 def _resolve_process_node(
     node: ProcessNode,
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> ProcessNode:
     if _is_step_class(node):
         try:
             return node()
         except TypeError as exc:
-            errors.append(f"step {node.__qualname__}: {exc}")
+            errors.append(step_instantiation_failed(node, exc))
             return node
     if isinstance(node, ConfigBinding):
         resolved = _resolve_binding(node, ctx, errors)
         if _is_process_node(resolved):
             return resolved
         binding_name = node.config_path or node.target.__name__
-        errors.append(f"binding {binding_name}: resolved object is not a process node")
+        errors.append(binding_not_process_node(binding_name))
         return node
     if isinstance(node, With):
         return _resolve_with(node, ctx, errors)
@@ -90,19 +97,20 @@ def _resolve_process_node(
 def _resolve_binding(
     binding: ConfigBinding,
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> object:
     try:
         return ctx.resolve(binding)
     except (ConfigError, TypeError, ValueError) as exc:
-        errors.append(f"binding {binding.config_path or binding.target.__name__}: {exc}")
+        binding_name = binding.config_path or binding.target.__name__
+        errors.append(binding_resolution_failed(binding_name, exc))
         return binding
 
 
 def _resolve_with(
     node: With[Any, Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> With[Any, Any]:
     resolved_process = _resolve_process(node.process, ctx, errors)
     resolved_deps = _resolve_dependencies(node.sync_contexts, ctx, errors)
@@ -114,7 +122,7 @@ def _resolve_with(
 def _resolve_with_async(
     node: WithAsync[Any, Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> WithAsync[Any, Any]:
     resolved_process = _resolve_process(node.process, ctx, errors)
     resolved_deps = _resolve_dependencies(node.async_contexts, ctx, errors)
@@ -132,7 +140,7 @@ def _resolve_with_async(
 def _resolve_router(
     node: Router[Any, Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> Router[Any, Any]:
     default = _resolve_process(node.default, ctx, errors) if node.default else None
     routes = {key: _resolve_process(process, ctx, errors) for key, process in node.routes.items()}
@@ -151,13 +159,13 @@ def _resolve_router(
 def _resolve_fork(
     node: Fork[Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> Fork[Any]:
     default = _resolve_process(node.default, ctx, errors) if node.default else None
     if node.kind is ForkKind.KEYED:
         selector = node.selector
         if selector is None:
-            errors.append("fork selector missing for keyed fork")
+            errors.append(fork_selector_missing())
             return node
         routes = {
             key: _resolve_process(process, ctx, errors) for key, process in node.routes.items()
@@ -176,7 +184,7 @@ def _resolve_fork(
 def _resolve_broadcast(
     node: Broadcast[Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> Broadcast[Any]:
     routes = tuple(
         BroadcastRoute(
@@ -191,7 +199,7 @@ def _resolve_broadcast(
 def _resolve_expand_routes(
     node: ExpandRoutes[Any],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> ExpandRoutes[Any]:
     routes = {
         output_type: _resolve_process(process, ctx, errors)
@@ -204,12 +212,16 @@ def _resolve_expand_routes(
 def _resolve_dependencies(
     dependencies: Mapping[str, object],
     ctx: ConfigContext,
-    errors: list[str],
+    errors: list[CompilationIssue],
 ) -> dict[str, object]:
     return {name: _resolve_dependency(value, ctx, errors) for name, value in dependencies.items()}
 
 
-def _resolve_dependency(value: object, ctx: ConfigContext, errors: list[str]) -> object:
+def _resolve_dependency(
+    value: object,
+    ctx: ConfigContext,
+    errors: list[CompilationIssue],
+) -> object:
     if isinstance(value, ConfigBinding):
         return _resolve_binding(value, ctx, errors)
     return value

{loom_kernel-1.3.0 → loom_kernel-1.4.0}/src/loom/streaming/compiler/_compiler.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from loom.core.config import ConfigContext
 from loom.streaming.compiler._bindings import resolve_flow_bindings
+from loom.streaming.compiler._errors import CompilationIssue
 from loom.streaming.compiler._plan import CompilationError, CompiledPlan
 from loom.streaming.compiler.phases.build_plan import build_plan
 from loom.streaming.compiler.phases.validate import (
@@ -44,12 +45,14 @@ def compile_flow(
 class _Compiler:
     """Validates a StreamFlow and produces a CompiledPlan.
 
-    Each validator is a pure function that returns a list of error strings.
+    Each validator is a pure function that returns a list of
+    :class:`CompilationIssue` values; the compiler accumulates them and raises
+    a single :class:`CompilationError` per phase gate.
     """
 
     def compile(self, flow: StreamFlow[Any, Any], ctx: ConfigContext) -> CompiledPlan:
         """Run all validation phases then build the compiled plan."""
-        errors: list[str] = []
+        errors: list[CompilationIssue] = []
 
         resolved_flow, binding_errors = resolve_flow_bindings(flow, ctx)
         errors.extend(binding_errors)