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/_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")
@@ -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()