dirigent-testing 0.17.2__tar.gz → 0.18.0__tar.gz

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: dirigent-testing
-Version: 0.17.2
+Version: 0.18.0
 Summary: Test doubles and pytest fixtures for writing and testing dirigent blocks.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-common==0.17.2
-Requires-Dist: dirigent-plugin==0.17.2
+Requires-Dist: dirigent-common==0.18.0
+Requires-Dist: dirigent-plugin==0.18.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: pytest>=9.1.1
@@ -24,6 +24,7 @@ Installing it registers the fixtures by entry point, so a block author writes no
 `call_block` validates a config the way the engine does before making the block's first call.
 
 `check_pack_examples` checks a pack's own example documents against its own `Contribution`
--- format, code, blocks, config schemas, and carried connections -- without importing
+-- format, code, blocks, config schemas, and the connections a step names, which the
+document may either carry or list under `requires.connections` -- without importing
 dirigent-core, and `assert_contribution_conforms` checks the blocks a contribution provides
 are well-formed. Both return a list of human-readable issues; an empty list means it passed.

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/README.md

@@ -7,6 +7,7 @@ Installing it registers the fixtures by entry point, so a block author writes no
 `call_block` validates a config the way the engine does before making the block's first call.
 
 `check_pack_examples` checks a pack's own example documents against its own `Contribution`
--- format, code, blocks, config schemas, and carried connections -- without importing
+-- format, code, blocks, config schemas, and the connections a step names, which the
+document may either carry or list under `requires.connections` -- without importing
 dirigent-core, and `assert_contribution_conforms` checks the blocks a contribution provides
 are well-formed. Both return a list of human-readable issues; an empty list means it passed.

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-testing"
-version = "0.17.2"
+version = "0.18.0"
 description = "Test doubles and pytest fixtures for writing and testing dirigent blocks."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,8 +11,8 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.17.2",
-    "dirigent-plugin==0.17.2",
+    "dirigent-common==0.18.0",
+    "dirigent-plugin==0.18.0",
     "httpx2>=2.12.0",
     "pydantic>=2.13.5",
     "pytest>=9.1.1",

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-testing"
-version = "0.17.2"
+version = "0.18.0"
 description = "Test doubles and pytest fixtures for writing and testing dirigent blocks."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,8 +11,8 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.17.2",
-    "dirigent-plugin==0.17.2",
+    "dirigent-common==0.18.0",
+    "dirigent-plugin==0.18.0",
     "httpx2>=2.12.0",
     "pydantic>=2.13.5",
     "pytest>=9.1.1",

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/src/dirigent_testing/__init__.py

@@ -1,13 +1,14 @@
 """Test doubles and pytest fixtures for writing and testing dirigent blocks."""
 
 from dirigent_testing.conformance import assert_contribution_conforms, check_pack_examples
-from dirigent_testing.doubles import FakeContext, FakeRuns, FakeSink, FakeStorage, RecordingLogger
+from dirigent_testing.doubles import FakeCapture, FakeContext, FakeRuns, FakeSink, FakeStorage, RecordingLogger
 from dirigent_testing.environment import CONFIGURING_PREFIXES, TEST_WIDTH, pin_terminal, scrub_configuration
 from dirigent_testing.running import call_block
 
 __all__ = [
     "CONFIGURING_PREFIXES",
     "TEST_WIDTH",
+    "FakeCapture",
     "FakeContext",
     "FakeRuns",
     "FakeSink",

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/src/dirigent_testing/conformance.py

@@ -6,8 +6,9 @@ conformance check re-derives the structural half here, over the pack's own ``Con
 and its own example documents. It is deliberately lighter than the engine's preflight: it
 proves an example is a well-formed ``dirigent/v1`` pipeline coded after its file, that every
 block it names is one the pack contributes, that each config fits that block's published
-schema, and that a named connection is carried by the document. It does not resolve
-references, run blocks, or reach for an instance.
+schema, and that a connection a step names is one the document accounts for -- carried, so
+the document runs alone, or named under ``requires``. It does not resolve references, run
+blocks, or reach for an instance.
 """
 
 import re
@@ -76,9 +77,9 @@ def check_pack_examples(contribution: Contribution, examples_dir: Path) -> list[
     is a ``dirigent/v1`` pipeline coded after its file with a description, that every block a
     step names is one ``contribution`` provides, that each step's config fits that block's
     published ``config_schema`` (a ``${...}`` value is left for the run), and that a connection
-    a step names is carried by the document's own ``connections`` block. Every issue is a
-    human-readable line prefixed with the file it was found in; an empty list means the
-    examples conform.
+    a step names is either carried by the document's own ``connections`` block or named under
+    its ``requires.connections``. Every issue is a human-readable line prefixed with the file
+    it was found in; an empty list means the examples conform.
     """
     blocks = _blocks_by_id(contribution)
     issues: list[str] = []
@@ -118,15 +119,25 @@ def _check_document(path: Path, label: Path, blocks: dict[str, AnyOperator | Any
     if not document.get("description"):
         issues.append(f"{label}: has no description")
 
-    connections = document.get("connections")
-    known = set(cast("JsonMap", connections)) if isinstance(connections, dict) else set[str]()
     steps = document.get("steps")
     if isinstance(steps, dict):
+        known = _known_connections(document)
         for name, step in cast("JsonMap", steps).items():
             issues.extend(_check_step(label, str(name), step, blocks, known))
     return issues
 
 
+def _known_connections(document: JsonMap) -> set[str]:
+    """Every connection code a document accounts for: the ones it carries and the ones it names."""
+    carried = document.get("connections")
+    known = set(cast("JsonMap", carried)) if isinstance(carried, dict) else set[str]()
+    requires = document.get("requires")
+    named = cast("JsonMap", requires).get("connections") if isinstance(requires, dict) else None
+    if isinstance(named, list):
+        known |= {one for one in cast("list[object]", named) if isinstance(one, str)}
+    return known
+
+
 def _check_step(
     label: Path,
     name: str,
@@ -134,7 +145,10 @@ def _check_step(
     blocks: dict[str, AnyOperator | AnySensor],
     connections: set[str],
 ) -> list[str]:
-    """Check one step: the block it names, the config it carries, the connection it references."""
+    """Check one step: the block it names, the config it carries, the connection it references.
+
+    ``connections`` is every code the document accounts for, carried or required.
+    """
     if not isinstance(step, dict):
         return [f"{label}: step {name!r} is not a mapping"]
     step_map = cast("JsonMap", step)
@@ -152,7 +166,9 @@ def _check_step(
 
     named = config.get("connection")
     if isinstance(named, str) and not _REFERENCE.search(named) and named not in connections:
-        issues.append(f"{label}: step {name!r} names connection {named!r}, which the document does not carry")
+        issues.append(
+            f"{label}: step {name!r} names connection {named!r}, which the document neither carries nor requires"
+        )
     return issues
 
 

{dirigent_testing-0.17.2 → dirigent_testing-0.18.0}/src/dirigent_testing/doubles.py

@@ -15,6 +15,7 @@ from pydantic import BaseModel, JsonValue
 from dirigent_common import format_checker_with
 from dirigent_plugin import (
     ByteSink,
+    Capture,
     FormatCheck,
     RunRefused,
     RunSnapshot,
@@ -71,6 +72,19 @@ class FakeSink:
         self._handle.close()
 
 
+class FakeCapture:
+    """A captured stream in a test: a sink carrying the URI it was opened under."""
+
+    def __init__(self, uri: str, sink: ByteSink) -> None:
+        """Bind the sink to the URI naming it."""
+        self.uri = uri
+        self._sink = sink
+
+    async def write(self, data: bytes) -> int:
+        """Append bytes to the stream and return how many were accepted."""
+        return await self._sink.write(data)
+
+
 class FakeStorage:
     """A storage facade over one directory, backing the storage blocks in a test."""
 
@@ -237,6 +251,22 @@ class FakeContext:
         """The run-scoped URI prefix."""
         return self.scratch_uri
 
+    def capture(self, name: str, *, content_type: str = "text/plain") -> AbstractAsyncContextManager[Capture]:
+        """Open a captured stream under the scratch prefix, named as the engine names it."""
+        uri = f"{self.scratch_uri.rstrip('/')}/{self._segment()}-{name}"
+
+        @asynccontextmanager
+        async def opened() -> AsyncGenerator[Capture]:
+            async with self.storage.open_write(uri, content_type=content_type) as sink:
+                yield FakeCapture(uri, sink)
+
+        return opened()
+
+    def _segment(self) -> str:
+        """The path this attempt's captures sit under: the step, the fan-out item, and the attempt."""
+        item = f"/{self.run_item_id}" if self.run_item_id is not None else ""
+        return f"{self.step}{item}/attempt-{self.attempt}"
+
     @property
     def work(self) -> Path:
         """The run's directory on this worker's own filesystem, made on first read.