Pyrophone 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyrophone/__init__.py +62 -0
- pyrophone/_channels.py +125 -0
- pyrophone/_compile.py +118 -0
- pyrophone/_control.py +229 -0
- pyrophone/_driver.py +91 -0
- pyrophone/_entry.py +53 -0
- pyrophone/_exceptions.py +42 -0
- pyrophone/_graph.py +283 -0
- pyrophone/_graph_display.py +117 -0
- pyrophone/_inspection.py +50 -0
- pyrophone/_node.py +216 -0
- pyrophone/_ports.py +105 -0
- pyrophone/_properties.py +64 -0
- pyrophone/_runner.py +83 -0
- pyrophone/_runtime.py +140 -0
- pyrophone/_schema.py +197 -0
- pyrophone/_shell.py +130 -0
- pyrophone/_terminal.py +73 -0
- pyrophone/_trace.py +93 -0
- pyrophone/cabe.py +222 -0
- pyrophone/jq.py +65 -0
- pyrophone/mqtt.py +122 -0
- pyrophone/nodes.py +110 -0
- pyrophone/py.typed +0 -0
- pyrophone/script.py +74 -0
- pyrophone-0.1.0.dist-info/METADATA +38 -0
- pyrophone-0.1.0.dist-info/RECORD +29 -0
- pyrophone-0.1.0.dist-info/WHEEL +4 -0
- pyrophone-0.1.0.dist-info/licenses/doc/LICENSE +202 -0
pyrophone/_node.py
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
"""Node registration and the private runtime allocation boundary."""
|
|
2
|
+
|
|
3
|
+
import inspect
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from copy import deepcopy
|
|
6
|
+
from math import isfinite
|
|
7
|
+
from types import MappingProxyType, UnionType
|
|
8
|
+
from typing import TYPE_CHECKING, ClassVar, TypeVar, Union, cast, get_args, get_origin
|
|
9
|
+
|
|
10
|
+
from ._exceptions import ConfigurationError, SchemaError
|
|
11
|
+
from ._inspection import Printable, node_details
|
|
12
|
+
from ._ports import Input, Output
|
|
13
|
+
from ._properties import Property
|
|
14
|
+
from ._schema import (
|
|
15
|
+
NodeTypeSchema,
|
|
16
|
+
PortSchema,
|
|
17
|
+
PropertySchema,
|
|
18
|
+
substitute_type,
|
|
19
|
+
validate_property,
|
|
20
|
+
validate_type,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
if TYPE_CHECKING:
|
|
24
|
+
from ._graph import NodeDeclaration
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class _NodeMeta(type):
|
|
28
|
+
def __call__(cls, /, **configuration: object) -> "NodeDeclaration":
|
|
29
|
+
from ._graph import NodeDeclaration
|
|
30
|
+
|
|
31
|
+
return NodeDeclaration(cast(type[Node], cls), configuration)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class Node(Printable, metaclass=_NodeMeta):
|
|
35
|
+
"""Base for node implementations. Runtime construction is framework-owned."""
|
|
36
|
+
|
|
37
|
+
_configuration: Mapping[str, object]
|
|
38
|
+
_inputs: Mapping[str, object]
|
|
39
|
+
_outputs: Mapping[str, object]
|
|
40
|
+
# Internal contract for built-ins that forward an input's exact value/type.
|
|
41
|
+
_output_type_sources: ClassVar[Mapping[str, str]] = {}
|
|
42
|
+
|
|
43
|
+
def __repr__(self) -> str:
|
|
44
|
+
return f"<{type(self).__name__}>"
|
|
45
|
+
|
|
46
|
+
def _describe(self) -> str:
|
|
47
|
+
return node_details(
|
|
48
|
+
type(self), self._configuration, node_type_schema(type(self))
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
async def run(self) -> None:
|
|
52
|
+
raise NotImplementedError("Node subclasses must implement run()")
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _generic_contexts(cls: type[Node]) -> dict[type, dict[TypeVar, object]]:
|
|
56
|
+
contexts: dict[type, dict[TypeVar, object]] = {}
|
|
57
|
+
|
|
58
|
+
def visit(current: type, context: dict[TypeVar, object]) -> None:
|
|
59
|
+
if current in contexts:
|
|
60
|
+
return
|
|
61
|
+
contexts[current] = context
|
|
62
|
+
declared_bases = current.__dict__.get("__orig_bases__", current.__bases__)
|
|
63
|
+
for base in declared_bases:
|
|
64
|
+
origin = get_origin(base) or base
|
|
65
|
+
if not isinstance(origin, type):
|
|
66
|
+
continue
|
|
67
|
+
parameters = getattr(origin, "__type_params__", ()) or getattr(
|
|
68
|
+
origin, "__parameters__", ()
|
|
69
|
+
)
|
|
70
|
+
arguments = get_args(base)
|
|
71
|
+
resolved = {
|
|
72
|
+
parameter: substitute_type(argument, context)
|
|
73
|
+
for parameter, argument in zip(parameters, arguments, strict=False)
|
|
74
|
+
if isinstance(parameter, TypeVar)
|
|
75
|
+
}
|
|
76
|
+
visit(origin, resolved)
|
|
77
|
+
|
|
78
|
+
visit(cls, {})
|
|
79
|
+
return contexts
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def node_type[N: Node](cls: type[N]) -> type[N]:
|
|
83
|
+
"""Register a class's immutable schema without constructing an instance."""
|
|
84
|
+
if not issubclass(cls, Node):
|
|
85
|
+
raise SchemaError("node_type requires a Node subclass")
|
|
86
|
+
properties: dict[str, PropertySchema] = {}
|
|
87
|
+
inputs: dict[str, PortSchema] = {}
|
|
88
|
+
outputs: dict[str, PortSchema] = {}
|
|
89
|
+
contexts = _generic_contexts(cls)
|
|
90
|
+
seen: set[str] = set()
|
|
91
|
+
for owner in cls.__mro__:
|
|
92
|
+
for name, declaration in vars(owner).items():
|
|
93
|
+
if name in seen:
|
|
94
|
+
continue
|
|
95
|
+
seen.add(name)
|
|
96
|
+
if not isinstance(declaration, (Property, Input, Output)):
|
|
97
|
+
continue
|
|
98
|
+
arguments = get_args(getattr(declaration, "__orig_class__", None))
|
|
99
|
+
if len(arguments) != 1:
|
|
100
|
+
raise SchemaError(f"{name}: an explicit generic type is required")
|
|
101
|
+
spec = substitute_type(arguments[0], contexts.get(owner, {}))
|
|
102
|
+
validate_type(spec, name)
|
|
103
|
+
if isinstance(declaration, Property):
|
|
104
|
+
prop = PropertySchema(
|
|
105
|
+
name=name,
|
|
106
|
+
type=spec,
|
|
107
|
+
default=deepcopy(declaration.default),
|
|
108
|
+
title=declaration.title,
|
|
109
|
+
description=declaration.description,
|
|
110
|
+
minimum=declaration.minimum,
|
|
111
|
+
maximum=declaration.maximum,
|
|
112
|
+
step=declaration.step,
|
|
113
|
+
)
|
|
114
|
+
_validate_property_schema(prop)
|
|
115
|
+
properties[name] = prop
|
|
116
|
+
else:
|
|
117
|
+
ports = inputs if isinstance(declaration, Input) else outputs
|
|
118
|
+
if declaration.default and any(port.default for port in ports.values()):
|
|
119
|
+
raise SchemaError(
|
|
120
|
+
f"{name}: multiple default ports in one direction"
|
|
121
|
+
)
|
|
122
|
+
ports[name] = PortSchema(
|
|
123
|
+
name, spec, declaration.description, declaration.default
|
|
124
|
+
)
|
|
125
|
+
cls._node_type_schema = NodeTypeSchema( # type: ignore[attr-defined]
|
|
126
|
+
cls.__name__, inspect.getdoc(cls), properties, inputs, outputs
|
|
127
|
+
)
|
|
128
|
+
return cls
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def _validate_property_schema(schema: PropertySchema) -> None:
|
|
132
|
+
for name in ("minimum", "maximum", "step"):
|
|
133
|
+
value = getattr(schema, name)
|
|
134
|
+
if value is None:
|
|
135
|
+
continue
|
|
136
|
+
if (
|
|
137
|
+
not isinstance(value, (int, float))
|
|
138
|
+
or isinstance(value, bool)
|
|
139
|
+
or (isinstance(value, float) and not isfinite(value))
|
|
140
|
+
):
|
|
141
|
+
raise SchemaError(f"{schema.name}: {name} must be a finite number")
|
|
142
|
+
if not _numeric_type(schema.type):
|
|
143
|
+
raise SchemaError(f"{schema.name}: {name} requires a numeric property")
|
|
144
|
+
if schema.minimum is not None and schema.maximum is not None:
|
|
145
|
+
if schema.minimum > schema.maximum:
|
|
146
|
+
raise SchemaError(f"{schema.name}: minimum exceeds maximum")
|
|
147
|
+
if schema.step is not None and schema.step <= 0:
|
|
148
|
+
raise SchemaError(f"{schema.name}: step must be positive")
|
|
149
|
+
if not schema.required:
|
|
150
|
+
try:
|
|
151
|
+
validate_property(schema.default, schema)
|
|
152
|
+
except ConfigurationError as error:
|
|
153
|
+
raise SchemaError(f"{schema.name}: invalid default: {error}") from error
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def _numeric_type(spec: object) -> bool:
|
|
157
|
+
if get_origin(spec) in (Union, UnionType):
|
|
158
|
+
types = [arg for arg in get_args(spec) if arg is not type(None)]
|
|
159
|
+
return bool(types) and all(_numeric_type(arg) for arg in types)
|
|
160
|
+
return (
|
|
161
|
+
isinstance(spec, type) and spec is not bool and issubclass(spec, (int, float))
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def node_type_schema(cls: type[Node]) -> NodeTypeSchema:
|
|
166
|
+
"""Return this class's schema; subclasses require their own registration."""
|
|
167
|
+
schema = vars(cls).get("_node_type_schema")
|
|
168
|
+
if not isinstance(schema, NodeTypeSchema):
|
|
169
|
+
raise SchemaError(f"{cls.__name__} is not a registered node type")
|
|
170
|
+
return schema
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _resolve_configuration(
|
|
174
|
+
schema: NodeTypeSchema, configuration: Mapping[str, object]
|
|
175
|
+
) -> dict[str, object]:
|
|
176
|
+
unknown = configuration.keys() - schema.properties.keys()
|
|
177
|
+
if unknown:
|
|
178
|
+
raise ConfigurationError(f"unknown properties: {', '.join(sorted(unknown))}")
|
|
179
|
+
values: dict[str, object] = {}
|
|
180
|
+
for name, prop in schema.properties.items():
|
|
181
|
+
if name in configuration:
|
|
182
|
+
value = configuration[name]
|
|
183
|
+
elif prop.required:
|
|
184
|
+
raise ConfigurationError(f"{name}: required property is missing")
|
|
185
|
+
else:
|
|
186
|
+
value = prop.default
|
|
187
|
+
validate_property(value, prop)
|
|
188
|
+
values[name] = deepcopy(value)
|
|
189
|
+
return values
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def _bind_node[N: Node](
|
|
193
|
+
cls: type[N],
|
|
194
|
+
configuration: Mapping[str, object],
|
|
195
|
+
inputs: Mapping[str, object],
|
|
196
|
+
outputs: Mapping[str, object],
|
|
197
|
+
) -> N:
|
|
198
|
+
"""Allocate a live node and bind state before its no-argument initializer.
|
|
199
|
+
|
|
200
|
+
Graph declarations must never use this path. Each invocation owns fresh
|
|
201
|
+
configuration and port mappings; endpoints themselves belong to the runtime.
|
|
202
|
+
"""
|
|
203
|
+
schema = node_type_schema(cls)
|
|
204
|
+
values = _resolve_configuration(schema, configuration)
|
|
205
|
+
for kind, supplied, expected in (
|
|
206
|
+
("input", inputs, schema.inputs),
|
|
207
|
+
("output", outputs, schema.outputs),
|
|
208
|
+
):
|
|
209
|
+
if supplied.keys() != expected.keys():
|
|
210
|
+
raise ConfigurationError(f"{kind} bindings must match declared ports")
|
|
211
|
+
instance = object.__new__(cls)
|
|
212
|
+
instance._configuration = MappingProxyType(values)
|
|
213
|
+
instance._inputs = MappingProxyType(dict(inputs))
|
|
214
|
+
instance._outputs = MappingProxyType(dict(outputs))
|
|
215
|
+
instance.__init__() # type: ignore[misc]
|
|
216
|
+
return instance
|
pyrophone/_ports.py
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
"""Port declarations and the typed interfaces seen by running nodes."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import AsyncIterator
|
|
6
|
+
from typing import TYPE_CHECKING, Never, Protocol, cast, overload
|
|
7
|
+
|
|
8
|
+
from ._exceptions import SchemaError
|
|
9
|
+
|
|
10
|
+
if TYPE_CHECKING:
|
|
11
|
+
from ._node import Node
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class InputPort[T](Protocol):
|
|
15
|
+
async def recv(self) -> T:
|
|
16
|
+
"""Receive the next value; cancellation follows the runtime task."""
|
|
17
|
+
...
|
|
18
|
+
|
|
19
|
+
async def close(self) -> None:
|
|
20
|
+
"""Stop accepting values, waking any blocked senders."""
|
|
21
|
+
...
|
|
22
|
+
|
|
23
|
+
def __aiter__(self) -> AsyncIterator[T]: ...
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class OutputPort[T](Protocol):
|
|
27
|
+
async def send(self, value: T) -> None:
|
|
28
|
+
"""Wait until a receiver accepts the value, without processing acknowledgement."""
|
|
29
|
+
...
|
|
30
|
+
|
|
31
|
+
async def close(self) -> None:
|
|
32
|
+
"""Announce end of stream and reject unaccepted sends."""
|
|
33
|
+
...
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class Input[T]:
|
|
37
|
+
def __init__(
|
|
38
|
+
self, *, description: str | None = None, default: bool = False
|
|
39
|
+
) -> None:
|
|
40
|
+
self.description = description
|
|
41
|
+
self.default = default
|
|
42
|
+
self._name = ""
|
|
43
|
+
self._owner: type[Node] | None = None
|
|
44
|
+
|
|
45
|
+
def __set_name__(self, owner: type[Node], name: str) -> None:
|
|
46
|
+
if self._owner is not None and (owner is not self._owner or name != self._name):
|
|
47
|
+
raise SchemaError(
|
|
48
|
+
f"{name}: cannot reuse declaration {self._owner.__name__}.{self._name}"
|
|
49
|
+
)
|
|
50
|
+
self._owner = owner
|
|
51
|
+
self._name = name
|
|
52
|
+
|
|
53
|
+
@overload
|
|
54
|
+
def __get__(self, instance: None, owner: type[Node] | None = None) -> Input[T]: ...
|
|
55
|
+
|
|
56
|
+
@overload
|
|
57
|
+
def __get__(
|
|
58
|
+
self, instance: Node, owner: type[Node] | None = None
|
|
59
|
+
) -> InputPort[T]: ...
|
|
60
|
+
|
|
61
|
+
def __get__(
|
|
62
|
+
self, instance: Node | None, owner: type[Node] | None = None
|
|
63
|
+
) -> Input[T] | InputPort[T]:
|
|
64
|
+
if instance is None:
|
|
65
|
+
return self
|
|
66
|
+
return cast(InputPort[T], instance._inputs[self._name])
|
|
67
|
+
|
|
68
|
+
def __set__(self, instance: Node, value: Never) -> Never:
|
|
69
|
+
raise AttributeError(f"{self._name} is a read-only input binding")
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class Output[T]:
|
|
73
|
+
def __init__(
|
|
74
|
+
self, *, description: str | None = None, default: bool = False
|
|
75
|
+
) -> None:
|
|
76
|
+
self.description = description
|
|
77
|
+
self.default = default
|
|
78
|
+
self._name = ""
|
|
79
|
+
self._owner: type[Node] | None = None
|
|
80
|
+
|
|
81
|
+
def __set_name__(self, owner: type[Node], name: str) -> None:
|
|
82
|
+
if self._owner is not None and (owner is not self._owner or name != self._name):
|
|
83
|
+
raise SchemaError(
|
|
84
|
+
f"{name}: cannot reuse declaration {self._owner.__name__}.{self._name}"
|
|
85
|
+
)
|
|
86
|
+
self._owner = owner
|
|
87
|
+
self._name = name
|
|
88
|
+
|
|
89
|
+
@overload
|
|
90
|
+
def __get__(self, instance: None, owner: type[Node] | None = None) -> Output[T]: ...
|
|
91
|
+
|
|
92
|
+
@overload
|
|
93
|
+
def __get__(
|
|
94
|
+
self, instance: Node, owner: type[Node] | None = None
|
|
95
|
+
) -> OutputPort[T]: ...
|
|
96
|
+
|
|
97
|
+
def __get__(
|
|
98
|
+
self, instance: Node | None, owner: type[Node] | None = None
|
|
99
|
+
) -> Output[T] | OutputPort[T]:
|
|
100
|
+
if instance is None:
|
|
101
|
+
return self
|
|
102
|
+
return cast(OutputPort[T], instance._outputs[self._name])
|
|
103
|
+
|
|
104
|
+
def __set__(self, instance: Node, value: Never) -> Never:
|
|
105
|
+
raise AttributeError(f"{self._name} is a read-only output binding")
|
pyrophone/_properties.py
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"""Read-only configuration descriptors used by node authors."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import TYPE_CHECKING, Never, cast, overload
|
|
6
|
+
|
|
7
|
+
from ._exceptions import SchemaError
|
|
8
|
+
from ._schema import _MISSING, _Missing
|
|
9
|
+
|
|
10
|
+
if TYPE_CHECKING:
|
|
11
|
+
from ._node import Node
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class Property[T]:
|
|
15
|
+
"""Declare a typed property; omitting default makes it required.
|
|
16
|
+
|
|
17
|
+
Values are bound separately for each runtime instance. Configuration is
|
|
18
|
+
shallowly read-only: callers may still mutate a mutable value's contents.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
def __init__(
|
|
22
|
+
self,
|
|
23
|
+
*,
|
|
24
|
+
default: T | _Missing = _MISSING,
|
|
25
|
+
title: str | None = None,
|
|
26
|
+
description: str | None = None,
|
|
27
|
+
minimum: int | float | None = None,
|
|
28
|
+
maximum: int | float | None = None,
|
|
29
|
+
step: int | float | None = None,
|
|
30
|
+
) -> None:
|
|
31
|
+
self.default = default
|
|
32
|
+
self.title = title
|
|
33
|
+
self.description = description
|
|
34
|
+
self.minimum = minimum
|
|
35
|
+
self.maximum = maximum
|
|
36
|
+
self.step = step
|
|
37
|
+
self._name = ""
|
|
38
|
+
self._owner: type[Node] | None = None
|
|
39
|
+
|
|
40
|
+
def __set_name__(self, owner: type[Node], name: str) -> None:
|
|
41
|
+
if self._owner is not None and (owner is not self._owner or name != self._name):
|
|
42
|
+
raise SchemaError(
|
|
43
|
+
f"{name}: cannot reuse declaration {self._owner.__name__}.{self._name}"
|
|
44
|
+
)
|
|
45
|
+
self._owner = owner
|
|
46
|
+
self._name = name
|
|
47
|
+
|
|
48
|
+
@overload
|
|
49
|
+
def __get__(
|
|
50
|
+
self, instance: None, owner: type[Node] | None = None
|
|
51
|
+
) -> Property[T]: ...
|
|
52
|
+
|
|
53
|
+
@overload
|
|
54
|
+
def __get__(self, instance: Node, owner: type[Node] | None = None) -> T: ...
|
|
55
|
+
|
|
56
|
+
def __get__(
|
|
57
|
+
self, instance: Node | None, owner: type[Node] | None = None
|
|
58
|
+
) -> Property[T] | T:
|
|
59
|
+
if instance is None:
|
|
60
|
+
return self
|
|
61
|
+
return cast(T, instance._configuration[self._name])
|
|
62
|
+
|
|
63
|
+
def __set__(self, instance: Node, value: Never) -> Never:
|
|
64
|
+
raise AttributeError(f"{self._name} is read-only configuration")
|
pyrophone/_runner.py
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""Synchronous execution without command-line policy."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
import inspect
|
|
5
|
+
from collections.abc import Awaitable, Callable, Coroutine
|
|
6
|
+
|
|
7
|
+
from ._compile import CompiledGraph
|
|
8
|
+
from ._control import Runtime
|
|
9
|
+
from ._graph import Graph
|
|
10
|
+
from ._runtime import _Session, run_async
|
|
11
|
+
|
|
12
|
+
type _Factory = Callable[[], Graph | Awaitable[Graph]]
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _run_entry(entry: Callable[[], Coroutine[object, object, None]]) -> None:
|
|
16
|
+
# Check before constructing a coroutine, so misuse cannot leak an unawaited one.
|
|
17
|
+
try:
|
|
18
|
+
asyncio.get_running_loop()
|
|
19
|
+
except RuntimeError:
|
|
20
|
+
pass
|
|
21
|
+
else:
|
|
22
|
+
raise RuntimeError(
|
|
23
|
+
"A synchronous Pyrophone entry point cannot run inside an active "
|
|
24
|
+
"event loop; use await pyrophone.run_async(graph) instead."
|
|
25
|
+
)
|
|
26
|
+
try:
|
|
27
|
+
asyncio.run(entry())
|
|
28
|
+
except KeyboardInterrupt:
|
|
29
|
+
# asyncio.run has already cancelled tasks and awaited their cleanup.
|
|
30
|
+
pass
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def run_sync(
|
|
34
|
+
graph: Graph | _Factory,
|
|
35
|
+
*,
|
|
36
|
+
on_graph: Callable[[CompiledGraph], None] | None = None,
|
|
37
|
+
execute: bool = True,
|
|
38
|
+
on_runtime: Callable[[Runtime], None] | None = None,
|
|
39
|
+
session: _Session | None = None,
|
|
40
|
+
) -> None:
|
|
41
|
+
"""Run a graph or zero-argument graph factory in a new event loop.
|
|
42
|
+
|
|
43
|
+
Graph factories may be synchronous or asynchronous. Construction and graph
|
|
44
|
+
execution share the same loop. No command-line arguments are parsed.
|
|
45
|
+
on_graph observes the validated snapshot before live node creation;
|
|
46
|
+
execute=False stops after validation and observation. on_runtime receives
|
|
47
|
+
editing handles after initialization, before node tasks start.
|
|
48
|
+
|
|
49
|
+
Ctrl-C cancels execution and completes cooperative cleanup without a
|
|
50
|
+
traceback. Other failures propagate. Inside an existing event loop, use
|
|
51
|
+
``await run_async(graph)`` instead.
|
|
52
|
+
"""
|
|
53
|
+
_run_entry(
|
|
54
|
+
lambda: _run_target(
|
|
55
|
+
graph,
|
|
56
|
+
on_graph=on_graph,
|
|
57
|
+
execute=execute,
|
|
58
|
+
on_runtime=on_runtime,
|
|
59
|
+
session=session,
|
|
60
|
+
)
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
async def _run_target(
|
|
65
|
+
target: Graph | _Factory,
|
|
66
|
+
*,
|
|
67
|
+
on_graph: Callable[[CompiledGraph], None] | None,
|
|
68
|
+
execute: bool,
|
|
69
|
+
on_runtime: Callable[[Runtime], None] | None,
|
|
70
|
+
session: _Session | None,
|
|
71
|
+
) -> None:
|
|
72
|
+
graph = target if isinstance(target, Graph) else target()
|
|
73
|
+
if inspect.isawaitable(graph):
|
|
74
|
+
graph = await graph
|
|
75
|
+
if not isinstance(graph, Graph):
|
|
76
|
+
raise TypeError("A Pyrophone graph factory must return a Graph")
|
|
77
|
+
await run_async(
|
|
78
|
+
graph,
|
|
79
|
+
on_graph=on_graph,
|
|
80
|
+
execute=execute,
|
|
81
|
+
on_runtime=on_runtime,
|
|
82
|
+
session=session,
|
|
83
|
+
)
|
pyrophone/_runtime.py
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
"""One-shot execution of validated graph snapshots with structured task ownership."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
from collections.abc import Awaitable, Callable
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
|
|
7
|
+
from ._channels import Channel, ReceiveEndpoint, SendEndpoint
|
|
8
|
+
from ._compile import CompiledGraph, CompiledNode, compile_graph
|
|
9
|
+
from ._control import NodeHandle, Runtime
|
|
10
|
+
from ._exceptions import NodeExecutionError
|
|
11
|
+
from ._graph import Graph
|
|
12
|
+
from ._node import Node, _bind_node
|
|
13
|
+
|
|
14
|
+
type _Session = Callable[[Graph, CompiledGraph, asyncio.Task[None]], Awaitable[None]]
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass
|
|
18
|
+
class _Bindings:
|
|
19
|
+
inputs: dict[str, ReceiveEndpoint[object]] = field(default_factory=dict)
|
|
20
|
+
outputs: dict[str, SendEndpoint[object]] = field(default_factory=dict)
|
|
21
|
+
|
|
22
|
+
async def close(self) -> None:
|
|
23
|
+
for output in self.outputs.values():
|
|
24
|
+
await output.close()
|
|
25
|
+
for input_port in self.inputs.values():
|
|
26
|
+
await input_port.close()
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
async def _execute(
|
|
30
|
+
node: CompiledNode, instance: Node, bindings: _Bindings, handle: NodeHandle
|
|
31
|
+
) -> None:
|
|
32
|
+
try:
|
|
33
|
+
await instance.run()
|
|
34
|
+
except Exception as error:
|
|
35
|
+
raise NodeExecutionError(node.id, node.node_type) from error
|
|
36
|
+
finally:
|
|
37
|
+
handle._close()
|
|
38
|
+
await bindings.close()
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
async def run_async(
|
|
42
|
+
graph: Graph,
|
|
43
|
+
*,
|
|
44
|
+
on_graph: Callable[[CompiledGraph], None] | None = None,
|
|
45
|
+
execute: bool = True,
|
|
46
|
+
on_runtime: Callable[[Runtime], None] | None = None,
|
|
47
|
+
session: _Session | None = None,
|
|
48
|
+
) -> None:
|
|
49
|
+
"""Run a fresh instance of each node after validating the entire graph.
|
|
50
|
+
|
|
51
|
+
on_graph observes the validated snapshot before any live nodes are allocated.
|
|
52
|
+
execute=False validates and observes the graph without running it. Neither
|
|
53
|
+
option parses command-line arguments. An optional session runs alongside
|
|
54
|
+
the graph; completion of either cancels and awaits the other.
|
|
55
|
+
on_runtime receives editing handles after all initializers finish, before
|
|
56
|
+
node tasks or the session start. execute=False skips this callback too.
|
|
57
|
+
|
|
58
|
+
Normal return closes a node's outputs and inputs. A failed node cancels its
|
|
59
|
+
siblings; cancellation awaits their cooperative cleanup. Run failures appear
|
|
60
|
+
in TaskGroup exception groups containing one or more NodeExecutionErrors,
|
|
61
|
+
each retaining the original exception as its cause. Initialization failures
|
|
62
|
+
raise NodeExecutionError directly, before any node run tasks are started.
|
|
63
|
+
|
|
64
|
+
Nodes should own asynchronous resources inside run(), using async context
|
|
65
|
+
managers or try/finally. The runtime closes its endpoints, but cannot unwind
|
|
66
|
+
arbitrary resources acquired by user initializers. There are no forced
|
|
67
|
+
cancellation timeouts, restart policies, or background runtime tasks.
|
|
68
|
+
"""
|
|
69
|
+
compiled = compile_graph(graph)
|
|
70
|
+
if on_graph is not None:
|
|
71
|
+
on_graph(compiled)
|
|
72
|
+
if not execute:
|
|
73
|
+
return
|
|
74
|
+
if session is None:
|
|
75
|
+
await _run_compiled(compiled, on_runtime)
|
|
76
|
+
return
|
|
77
|
+
ready = asyncio.Event()
|
|
78
|
+
|
|
79
|
+
def runtime_ready(runtime: Runtime) -> None:
|
|
80
|
+
if on_runtime is not None:
|
|
81
|
+
on_runtime(runtime)
|
|
82
|
+
ready.set()
|
|
83
|
+
|
|
84
|
+
async with asyncio.TaskGroup() as tasks:
|
|
85
|
+
graph_task = tasks.create_task(
|
|
86
|
+
_run_compiled(compiled, runtime_ready), name="pyrophone:graph"
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
async def interact() -> None:
|
|
90
|
+
await ready.wait()
|
|
91
|
+
await session(graph, compiled, graph_task)
|
|
92
|
+
|
|
93
|
+
session_task = tasks.create_task(interact(), name="pyrophone:session")
|
|
94
|
+
_, pending = await asyncio.wait(
|
|
95
|
+
(graph_task, session_task), return_when=asyncio.FIRST_COMPLETED
|
|
96
|
+
)
|
|
97
|
+
for task in pending:
|
|
98
|
+
task.cancel()
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
async def _run_compiled(
|
|
102
|
+
compiled: CompiledGraph, on_runtime: Callable[[Runtime], None] | None = None
|
|
103
|
+
) -> None:
|
|
104
|
+
bindings = {node.id: _Bindings() for node in compiled.nodes}
|
|
105
|
+
channels: list[Channel[object]] = []
|
|
106
|
+
handles: list[NodeHandle] = []
|
|
107
|
+
try:
|
|
108
|
+
for edge in compiled.edges:
|
|
109
|
+
channel = Channel[object]()
|
|
110
|
+
channels.append(channel)
|
|
111
|
+
bindings[edge.source_id].outputs[edge.source_port] = channel.output
|
|
112
|
+
bindings[edge.destination_id].inputs[edge.destination_port] = channel.input
|
|
113
|
+
instances: list[Node] = []
|
|
114
|
+
for node in compiled.nodes:
|
|
115
|
+
ports = bindings[node.id]
|
|
116
|
+
try:
|
|
117
|
+
instance = _bind_node(
|
|
118
|
+
node.node_type, node.configuration, ports.inputs, ports.outputs
|
|
119
|
+
)
|
|
120
|
+
except Exception as error:
|
|
121
|
+
raise NodeExecutionError(node.id, node.node_type) from error
|
|
122
|
+
instances.append(instance)
|
|
123
|
+
handles.append(NodeHandle(node, instance))
|
|
124
|
+
runtime = Runtime(compiled, tuple(handles))
|
|
125
|
+
if on_runtime is not None:
|
|
126
|
+
on_runtime(runtime)
|
|
127
|
+
async with asyncio.TaskGroup() as tasks:
|
|
128
|
+
for node, instance, handle in zip(
|
|
129
|
+
compiled.nodes, instances, handles, strict=True
|
|
130
|
+
):
|
|
131
|
+
tasks.create_task(
|
|
132
|
+
_execute(node, instance, bindings[node.id], handle),
|
|
133
|
+
name=f"pyrophone:{node.node_type.__name__}:{node.id}",
|
|
134
|
+
)
|
|
135
|
+
finally:
|
|
136
|
+
for handle in handles:
|
|
137
|
+
handle._close()
|
|
138
|
+
# Covers initialization failure and tasks cancelled before first execution.
|
|
139
|
+
for channel in channels:
|
|
140
|
+
await channel.output.close()
|