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/__init__.py
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Typed declarations for asynchronous message-processing nodes."""
|
|
2
|
+
|
|
3
|
+
from ._compile import CompiledEdge, CompiledGraph, CompiledNode, compile_graph
|
|
4
|
+
from ._control import NodeHandle, PortHandle, Runtime
|
|
5
|
+
from ._entry import main
|
|
6
|
+
from ._exceptions import (
|
|
7
|
+
ChannelClosedError,
|
|
8
|
+
ConfigurationError,
|
|
9
|
+
EndOfStream,
|
|
10
|
+
GraphError,
|
|
11
|
+
NodeExecutionError,
|
|
12
|
+
PyrophoneError,
|
|
13
|
+
SchemaError,
|
|
14
|
+
)
|
|
15
|
+
from ._graph import Edge, Graph, NodeDeclaration, PortReference
|
|
16
|
+
from ._node import Node, node_type, node_type_schema
|
|
17
|
+
from ._ports import Input, InputPort, Output, OutputPort
|
|
18
|
+
from ._properties import Property
|
|
19
|
+
from ._runner import run_sync
|
|
20
|
+
from ._runtime import run_async
|
|
21
|
+
from ._schema import NodeTypeSchema, PortSchema, PropertySchema
|
|
22
|
+
from ._trace import Trace
|
|
23
|
+
|
|
24
|
+
# Compatibility with the original asynchronous entry point.
|
|
25
|
+
run = run_async
|
|
26
|
+
|
|
27
|
+
__all__ = [
|
|
28
|
+
"ChannelClosedError",
|
|
29
|
+
"CompiledEdge",
|
|
30
|
+
"CompiledGraph",
|
|
31
|
+
"CompiledNode",
|
|
32
|
+
"ConfigurationError",
|
|
33
|
+
"Edge",
|
|
34
|
+
"EndOfStream",
|
|
35
|
+
"Graph",
|
|
36
|
+
"GraphError",
|
|
37
|
+
"Input",
|
|
38
|
+
"InputPort",
|
|
39
|
+
"Node",
|
|
40
|
+
"NodeDeclaration",
|
|
41
|
+
"NodeExecutionError",
|
|
42
|
+
"NodeHandle",
|
|
43
|
+
"NodeTypeSchema",
|
|
44
|
+
"Output",
|
|
45
|
+
"OutputPort",
|
|
46
|
+
"PortHandle",
|
|
47
|
+
"PortReference",
|
|
48
|
+
"PortSchema",
|
|
49
|
+
"Property",
|
|
50
|
+
"PropertySchema",
|
|
51
|
+
"PyrophoneError",
|
|
52
|
+
"Runtime",
|
|
53
|
+
"SchemaError",
|
|
54
|
+
"Trace",
|
|
55
|
+
"compile_graph",
|
|
56
|
+
"main",
|
|
57
|
+
"node_type",
|
|
58
|
+
"node_type_schema",
|
|
59
|
+
"run",
|
|
60
|
+
"run_async",
|
|
61
|
+
"run_sync",
|
|
62
|
+
]
|
pyrophone/_channels.py
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
"""Unbuffered, FIFO handoff between asynchronous producer and consumer ports."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
from collections import deque
|
|
5
|
+
from collections.abc import AsyncIterator
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
|
|
8
|
+
from ._exceptions import ChannelClosedError, EndOfStream
|
|
9
|
+
from ._trace import _notify, _TraceCallbacks
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass(eq=False)
|
|
13
|
+
class _PendingSend[T]:
|
|
14
|
+
value: T
|
|
15
|
+
accepted: asyncio.Future[None]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class Channel[T]:
|
|
19
|
+
"""One edge's rendezvous state, confined to one asyncio event loop.
|
|
20
|
+
|
|
21
|
+
Waiters are matched in arrival order. A handoff accepts the value immediately;
|
|
22
|
+
cancellation after acceptance does not undo delivery. Pending sends retain
|
|
23
|
+
their values only while the sender is waiting, never as buffered arrivals.
|
|
24
|
+
Closing either end rejects unaccepted sends and ends outstanding receives.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
def __init__(self) -> None:
|
|
28
|
+
self._closed = False
|
|
29
|
+
self._senders: deque[_PendingSend[T]] = deque()
|
|
30
|
+
self._receivers: deque[asyncio.Future[T]] = deque()
|
|
31
|
+
self.input = ReceiveEndpoint(self)
|
|
32
|
+
self.output = SendEndpoint(self)
|
|
33
|
+
|
|
34
|
+
async def _send(self, value: T) -> None:
|
|
35
|
+
if self._closed:
|
|
36
|
+
raise ChannelClosedError("channel is closed")
|
|
37
|
+
while self._receivers:
|
|
38
|
+
receiver = self._receivers.popleft()
|
|
39
|
+
if not receiver.done():
|
|
40
|
+
receiver.set_result(value)
|
|
41
|
+
self._trace(value)
|
|
42
|
+
return
|
|
43
|
+
accepted: asyncio.Future[None] = asyncio.get_running_loop().create_future()
|
|
44
|
+
pending = _PendingSend(value, accepted)
|
|
45
|
+
self._senders.append(pending)
|
|
46
|
+
try:
|
|
47
|
+
await accepted
|
|
48
|
+
finally:
|
|
49
|
+
# A matched or closed waiter has already been removed.
|
|
50
|
+
if pending in self._senders:
|
|
51
|
+
self._senders.remove(pending)
|
|
52
|
+
|
|
53
|
+
async def _recv(self) -> T:
|
|
54
|
+
while self._senders:
|
|
55
|
+
pending = self._senders.popleft()
|
|
56
|
+
if not pending.accepted.done():
|
|
57
|
+
pending.accepted.set_result(None)
|
|
58
|
+
self._trace(pending.value)
|
|
59
|
+
return pending.value
|
|
60
|
+
if self._closed:
|
|
61
|
+
raise EndOfStream("channel is closed")
|
|
62
|
+
receiver: asyncio.Future[T] = asyncio.get_running_loop().create_future()
|
|
63
|
+
self._receivers.append(receiver)
|
|
64
|
+
try:
|
|
65
|
+
return await receiver
|
|
66
|
+
finally:
|
|
67
|
+
if receiver in self._receivers:
|
|
68
|
+
self._receivers.remove(receiver)
|
|
69
|
+
|
|
70
|
+
def _trace(self, value: T) -> None:
|
|
71
|
+
# Snapshot both ends before callbacks can change registrations. Delivery
|
|
72
|
+
# has already been accepted; no await separates either side's observers.
|
|
73
|
+
outgoing = self.output._traces.snapshot()
|
|
74
|
+
incoming = self.input._traces.snapshot()
|
|
75
|
+
_notify(outgoing, value)
|
|
76
|
+
_notify(incoming, value)
|
|
77
|
+
|
|
78
|
+
def _close(self) -> None:
|
|
79
|
+
self._closed = True
|
|
80
|
+
self.output._traces.close()
|
|
81
|
+
self.input._traces.close()
|
|
82
|
+
while self._senders:
|
|
83
|
+
pending = self._senders.popleft()
|
|
84
|
+
if not pending.accepted.done():
|
|
85
|
+
pending.accepted.set_exception(ChannelClosedError("channel is closed"))
|
|
86
|
+
while self._receivers:
|
|
87
|
+
receiver = self._receivers.popleft()
|
|
88
|
+
if not receiver.done():
|
|
89
|
+
receiver.set_exception(EndOfStream("channel is closed"))
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
class ReceiveEndpoint[T]:
|
|
93
|
+
"""Consumer view of a channel; closing withdraws consumer interest."""
|
|
94
|
+
|
|
95
|
+
def __init__(self, channel: Channel[T]) -> None:
|
|
96
|
+
self._channel = channel
|
|
97
|
+
self._traces = _TraceCallbacks[T]()
|
|
98
|
+
|
|
99
|
+
async def recv(self) -> T:
|
|
100
|
+
return await self._channel._recv()
|
|
101
|
+
|
|
102
|
+
async def close(self) -> None:
|
|
103
|
+
self._channel._close()
|
|
104
|
+
|
|
105
|
+
async def __aiter__(self) -> AsyncIterator[T]:
|
|
106
|
+
while True:
|
|
107
|
+
try:
|
|
108
|
+
value = await self.recv()
|
|
109
|
+
except EndOfStream:
|
|
110
|
+
return
|
|
111
|
+
yield value
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
class SendEndpoint[T]:
|
|
115
|
+
"""Producer view of a channel; closing announces end of stream."""
|
|
116
|
+
|
|
117
|
+
def __init__(self, channel: Channel[T]) -> None:
|
|
118
|
+
self._channel = channel
|
|
119
|
+
self._traces = _TraceCallbacks[T]()
|
|
120
|
+
|
|
121
|
+
async def send(self, value: T) -> None:
|
|
122
|
+
await self._channel._send(value)
|
|
123
|
+
|
|
124
|
+
async def close(self) -> None:
|
|
125
|
+
self._channel._close()
|
pyrophone/_compile.py
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""Validate fundamental graphs and detach execution snapshots."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Mapping
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from types import MappingProxyType
|
|
6
|
+
|
|
7
|
+
from ._exceptions import GraphError
|
|
8
|
+
from ._graph import Graph, PortReference, _resolved_schema, _validate_connection
|
|
9
|
+
from ._inspection import Printable, node_details
|
|
10
|
+
from ._node import Node, _resolve_configuration
|
|
11
|
+
from ._schema import NodeTypeSchema
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass(frozen=True)
|
|
15
|
+
class CompiledNode(Printable):
|
|
16
|
+
"""Configured occurrence retaining its original declaration ID.
|
|
17
|
+
|
|
18
|
+
Configuration is shallowly read-only, with nested values detached from the
|
|
19
|
+
authoring declaration so subsequent graph edits cannot change execution.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
id: str
|
|
23
|
+
node_type: type[Node]
|
|
24
|
+
configuration: Mapping[str, object]
|
|
25
|
+
schema: NodeTypeSchema
|
|
26
|
+
|
|
27
|
+
def __repr__(self) -> str:
|
|
28
|
+
return f"<CompiledNode {self.node_type.__name__}#{self.id[:8]}>"
|
|
29
|
+
|
|
30
|
+
def _describe(self) -> str:
|
|
31
|
+
return node_details(
|
|
32
|
+
self.node_type,
|
|
33
|
+
self.configuration,
|
|
34
|
+
self.schema,
|
|
35
|
+
kind="CompiledNode",
|
|
36
|
+
node_id=self.id,
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True)
|
|
41
|
+
class CompiledEdge(Printable):
|
|
42
|
+
source_id: str
|
|
43
|
+
source_port: str
|
|
44
|
+
destination_id: str
|
|
45
|
+
destination_port: str
|
|
46
|
+
|
|
47
|
+
def __repr__(self) -> str:
|
|
48
|
+
return (
|
|
49
|
+
f"<CompiledEdge {self.source_id[:8]}.{self.source_port} -> "
|
|
50
|
+
f"{self.destination_id[:8]}.{self.destination_port}>"
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
def _describe(self) -> str:
|
|
54
|
+
return (
|
|
55
|
+
"CompiledEdge:\n"
|
|
56
|
+
f" From: {self.source_id}.{self.source_port}\n"
|
|
57
|
+
f" To: {self.destination_id}.{self.destination_port}"
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass(frozen=True)
|
|
62
|
+
class CompiledGraph(Printable):
|
|
63
|
+
nodes: tuple[CompiledNode, ...]
|
|
64
|
+
edges: tuple[CompiledEdge, ...]
|
|
65
|
+
|
|
66
|
+
def __repr__(self) -> str:
|
|
67
|
+
return f"CompiledGraph(nodes={len(self.nodes)}, edges={len(self.edges)})"
|
|
68
|
+
|
|
69
|
+
def _describe(self) -> str:
|
|
70
|
+
from ._graph_display import format_graph
|
|
71
|
+
|
|
72
|
+
return format_graph(self, title="CompiledGraph")
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def compile_graph(graph: Graph) -> CompiledGraph:
|
|
76
|
+
"""Validate every connection and configuration without allocating live nodes.
|
|
77
|
+
|
|
78
|
+
Every declared input and output must have exactly one channel. Empty graphs
|
|
79
|
+
and portless nodes are valid. The returned tuples and copied configuration
|
|
80
|
+
are independent of later authoring graph changes.
|
|
81
|
+
"""
|
|
82
|
+
nodes, edges = graph.nodes, graph.edges
|
|
83
|
+
members = set(nodes)
|
|
84
|
+
connected: set[PortReference] = set()
|
|
85
|
+
incoming = {edge.destination: edge.source for edge in edges}
|
|
86
|
+
for edge in edges:
|
|
87
|
+
_validate_connection(
|
|
88
|
+
edge.source, edge.destination, connected, incoming=incoming
|
|
89
|
+
)
|
|
90
|
+
if edge.source.node not in members or edge.destination.node not in members:
|
|
91
|
+
raise GraphError("connection references a node outside the graph")
|
|
92
|
+
connected.update((edge.source, edge.destination))
|
|
93
|
+
for node in nodes:
|
|
94
|
+
for name in (*node.schema.inputs, *node.schema.outputs):
|
|
95
|
+
if node.port(name) not in connected:
|
|
96
|
+
raise GraphError(f"{node.schema.name}: unconnected port {name!r}")
|
|
97
|
+
return CompiledGraph(
|
|
98
|
+
tuple(
|
|
99
|
+
CompiledNode(
|
|
100
|
+
node.id,
|
|
101
|
+
node.node_type,
|
|
102
|
+
MappingProxyType(
|
|
103
|
+
_resolve_configuration(node.schema, node.configuration)
|
|
104
|
+
),
|
|
105
|
+
_resolved_schema(node, incoming),
|
|
106
|
+
)
|
|
107
|
+
for node in nodes
|
|
108
|
+
),
|
|
109
|
+
tuple(
|
|
110
|
+
CompiledEdge(
|
|
111
|
+
edge.source.node.id,
|
|
112
|
+
edge.source.name,
|
|
113
|
+
edge.destination.node.id,
|
|
114
|
+
edge.destination.name,
|
|
115
|
+
)
|
|
116
|
+
for edge in edges
|
|
117
|
+
),
|
|
118
|
+
)
|
pyrophone/_control.py
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
"""External handles for synchronous edits to per-instance configuration."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
from collections.abc import Callable, Mapping
|
|
5
|
+
from copy import deepcopy
|
|
6
|
+
from types import MappingProxyType
|
|
7
|
+
from typing import Literal, cast
|
|
8
|
+
|
|
9
|
+
from ._channels import ReceiveEndpoint, SendEndpoint
|
|
10
|
+
from ._compile import CompiledGraph, CompiledNode
|
|
11
|
+
from ._inspection import Printable, node_details, type_name
|
|
12
|
+
from ._node import Node
|
|
13
|
+
from ._schema import NodeTypeSchema, PortSchema, validate_property
|
|
14
|
+
from ._trace import Trace, _TraceCallbacks
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class NodeHandle(Printable):
|
|
18
|
+
"""Runtime-owned editing access to one node, without exposing its instance.
|
|
19
|
+
|
|
20
|
+
Attribute assignment validates and immediately replaces a property value.
|
|
21
|
+
Edits must run on the node's event loop while the node is active. Reads and
|
|
22
|
+
configuration snapshots are detached copies; edit containers by assignment.
|
|
23
|
+
For names colliding with handle metadata/methods, use get_property/set_property.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
def __init__(self, definition: CompiledNode, instance: Node) -> None:
|
|
27
|
+
object.__setattr__(self, "_definition", definition)
|
|
28
|
+
object.__setattr__(self, "_instance", instance)
|
|
29
|
+
object.__setattr__(self, "_active", True)
|
|
30
|
+
object.__setattr__(self, "_loop", asyncio.get_running_loop())
|
|
31
|
+
ports = {}
|
|
32
|
+
for direction, endpoints in (
|
|
33
|
+
("input", instance._inputs),
|
|
34
|
+
("output", instance._outputs),
|
|
35
|
+
):
|
|
36
|
+
for name, endpoint in endpoints.items():
|
|
37
|
+
port = cast(ReceiveEndpoint[object] | SendEndpoint[object], endpoint)
|
|
38
|
+
ports[name] = PortHandle(
|
|
39
|
+
self,
|
|
40
|
+
name,
|
|
41
|
+
cast(Literal["input", "output"], direction),
|
|
42
|
+
port._traces,
|
|
43
|
+
)
|
|
44
|
+
object.__setattr__(self, "_ports", ports)
|
|
45
|
+
|
|
46
|
+
_definition: CompiledNode
|
|
47
|
+
_instance: Node
|
|
48
|
+
_active: bool
|
|
49
|
+
_loop: asyncio.AbstractEventLoop
|
|
50
|
+
_ports: dict[str, "PortHandle"]
|
|
51
|
+
|
|
52
|
+
@property
|
|
53
|
+
def id(self) -> str:
|
|
54
|
+
return self._definition.id
|
|
55
|
+
|
|
56
|
+
@property
|
|
57
|
+
def node_type(self) -> type[Node]:
|
|
58
|
+
return self._definition.node_type
|
|
59
|
+
|
|
60
|
+
@property
|
|
61
|
+
def schema(self) -> NodeTypeSchema:
|
|
62
|
+
return self._definition.schema
|
|
63
|
+
|
|
64
|
+
@property
|
|
65
|
+
def active(self) -> bool:
|
|
66
|
+
return self._active
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
def configuration(self) -> Mapping[str, object]:
|
|
70
|
+
"""Return a detached, read-only snapshot of current property values."""
|
|
71
|
+
return MappingProxyType(deepcopy(dict(self._instance._configuration)))
|
|
72
|
+
|
|
73
|
+
def __getattr__(self, name: str) -> object:
|
|
74
|
+
if name in self._ports:
|
|
75
|
+
return self.port(name)
|
|
76
|
+
return self.get_property(name)
|
|
77
|
+
|
|
78
|
+
def port(self, name: str) -> "PortHandle":
|
|
79
|
+
"""Inspect or trace a named runtime port, including reserved names."""
|
|
80
|
+
if name not in self._ports:
|
|
81
|
+
raise AttributeError(f"{self.schema.name}: no port named {name!r}")
|
|
82
|
+
return self._ports[name]
|
|
83
|
+
|
|
84
|
+
def __setattr__(self, name: str, value: object) -> None:
|
|
85
|
+
if name.startswith("_") or hasattr(type(self), name):
|
|
86
|
+
raise AttributeError(f"{name} is read-only handle metadata")
|
|
87
|
+
self.set_property(name, value)
|
|
88
|
+
|
|
89
|
+
def __dir__(self) -> list[str]:
|
|
90
|
+
return sorted(
|
|
91
|
+
set(super().__dir__()) | self.schema.properties.keys() | self._ports.keys()
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
def get_property(self, name: str) -> object:
|
|
95
|
+
"""Read a property by name, including names reserved by the handle."""
|
|
96
|
+
if name not in self.schema.properties:
|
|
97
|
+
raise AttributeError(f"{self.schema.name}: no property named {name!r}")
|
|
98
|
+
return deepcopy(self._instance._configuration[name])
|
|
99
|
+
|
|
100
|
+
def set_property(self, name: str, value: object) -> None:
|
|
101
|
+
"""Validate, copy, and apply one value without yielding or invoking hooks."""
|
|
102
|
+
if name not in self.schema.properties:
|
|
103
|
+
raise AttributeError(f"{self.schema.name}: no property named {name!r}")
|
|
104
|
+
self._check_active()
|
|
105
|
+
copied = deepcopy(value)
|
|
106
|
+
validate_property(copied, self.schema.properties[name])
|
|
107
|
+
configuration = dict(self._instance._configuration)
|
|
108
|
+
configuration[name] = copied
|
|
109
|
+
object.__setattr__(
|
|
110
|
+
self._instance, "_configuration", MappingProxyType(configuration)
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
def _check_active(self) -> None:
|
|
114
|
+
if not self.active:
|
|
115
|
+
raise RuntimeError(f"{self.schema.name}: node has stopped")
|
|
116
|
+
try:
|
|
117
|
+
loop = asyncio.get_running_loop()
|
|
118
|
+
except RuntimeError:
|
|
119
|
+
loop = None
|
|
120
|
+
if loop is not self._loop:
|
|
121
|
+
raise RuntimeError("runtime changes must run on the node's event loop")
|
|
122
|
+
|
|
123
|
+
def _close(self) -> None:
|
|
124
|
+
object.__setattr__(self, "_active", False)
|
|
125
|
+
for port in self._ports.values():
|
|
126
|
+
port._traces.close()
|
|
127
|
+
|
|
128
|
+
def __repr__(self) -> str:
|
|
129
|
+
status = "active" if self.active else "stopped"
|
|
130
|
+
return f"<NodeHandle {self.node_type.__name__}#{self.id[:8]} ({status})>"
|
|
131
|
+
|
|
132
|
+
def _describe(self) -> str:
|
|
133
|
+
return node_details(
|
|
134
|
+
self.node_type,
|
|
135
|
+
self.configuration,
|
|
136
|
+
self.schema,
|
|
137
|
+
kind="NodeHandle",
|
|
138
|
+
node_id=self.id,
|
|
139
|
+
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class PortHandle(Printable):
|
|
143
|
+
"""Inspection and tracing access to one live port; it cannot send or receive."""
|
|
144
|
+
|
|
145
|
+
def __init__(
|
|
146
|
+
self,
|
|
147
|
+
node: NodeHandle,
|
|
148
|
+
name: str,
|
|
149
|
+
direction: Literal["input", "output"],
|
|
150
|
+
traces: _TraceCallbacks[object],
|
|
151
|
+
) -> None:
|
|
152
|
+
self._node, self._name, self._direction, self._traces = (
|
|
153
|
+
node,
|
|
154
|
+
name,
|
|
155
|
+
direction,
|
|
156
|
+
traces,
|
|
157
|
+
)
|
|
158
|
+
|
|
159
|
+
@property
|
|
160
|
+
def node(self) -> NodeHandle:
|
|
161
|
+
return self._node
|
|
162
|
+
|
|
163
|
+
@property
|
|
164
|
+
def name(self) -> str:
|
|
165
|
+
return self._name
|
|
166
|
+
|
|
167
|
+
@property
|
|
168
|
+
def direction(self) -> Literal["input", "output"]:
|
|
169
|
+
return self._direction
|
|
170
|
+
|
|
171
|
+
@property
|
|
172
|
+
def schema(self) -> PortSchema:
|
|
173
|
+
ports = (
|
|
174
|
+
self.node.schema.inputs
|
|
175
|
+
if self.direction == "input"
|
|
176
|
+
else self.node.schema.outputs
|
|
177
|
+
)
|
|
178
|
+
return ports[self.name]
|
|
179
|
+
|
|
180
|
+
def trace(self, callback: Callable[[object], None]) -> Trace:
|
|
181
|
+
"""Observe accepted transfers synchronously. The callback must not block."""
|
|
182
|
+
self.node._check_active()
|
|
183
|
+
return self._traces.add(callback)
|
|
184
|
+
|
|
185
|
+
def __repr__(self) -> str:
|
|
186
|
+
return f"<PortHandle {self.node.node_type.__name__}#{self.node.id[:8]}.{self.name} ({self.direction})>"
|
|
187
|
+
|
|
188
|
+
def _describe(self) -> str:
|
|
189
|
+
return (
|
|
190
|
+
f"Port: {self.node.node_type.__name__}.{self.name}\n"
|
|
191
|
+
f" Node ID: {self.node.id}\n"
|
|
192
|
+
f" Direction: {self.direction}\n"
|
|
193
|
+
f" Type: {type_name(self.schema.type)}\n"
|
|
194
|
+
f" Traces: {len(self._traces.snapshot())}"
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class Runtime(Printable):
|
|
199
|
+
"""Runtime-owned controller exposing handles in graph insertion order."""
|
|
200
|
+
|
|
201
|
+
def __init__(
|
|
202
|
+
self, compiled_graph: CompiledGraph, nodes: tuple[NodeHandle, ...]
|
|
203
|
+
) -> None:
|
|
204
|
+
self._compiled_graph = compiled_graph
|
|
205
|
+
self._nodes = nodes
|
|
206
|
+
|
|
207
|
+
@property
|
|
208
|
+
def nodes(self) -> tuple[NodeHandle, ...]:
|
|
209
|
+
return self._nodes
|
|
210
|
+
|
|
211
|
+
@property
|
|
212
|
+
def compiled_graph(self) -> CompiledGraph:
|
|
213
|
+
"""The startup snapshot; live edits do not mutate it."""
|
|
214
|
+
return self._compiled_graph
|
|
215
|
+
|
|
216
|
+
def __repr__(self) -> str:
|
|
217
|
+
return f"Runtime(nodes={len(self.nodes)}, active={sum(n.active for n in self.nodes)})"
|
|
218
|
+
|
|
219
|
+
def _describe(self) -> str:
|
|
220
|
+
from ._graph_display import format_graph
|
|
221
|
+
|
|
222
|
+
current = CompiledGraph(
|
|
223
|
+
tuple(
|
|
224
|
+
CompiledNode(node.id, node.node_type, node.configuration, node.schema)
|
|
225
|
+
for node in self.nodes
|
|
226
|
+
),
|
|
227
|
+
self.compiled_graph.edges,
|
|
228
|
+
)
|
|
229
|
+
return format_graph(current, title="Runtime")
|
pyrophone/_driver.py
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"""Shared command-line preparation for Python scripts and a future CLI."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
import asyncio
|
|
5
|
+
import sys
|
|
6
|
+
from collections.abc import Sequence
|
|
7
|
+
|
|
8
|
+
from ._compile import CompiledGraph
|
|
9
|
+
from ._control import Runtime
|
|
10
|
+
from ._graph import Graph
|
|
11
|
+
from ._graph_display import GRAPH_FORMATS, render_graph
|
|
12
|
+
from ._runner import _Factory, run_sync
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def drive(target: Graph | _Factory, *, argv: Sequence[str] | None = None) -> None:
|
|
16
|
+
"""Parse runtime arguments before building or executing a graph.
|
|
17
|
+
|
|
18
|
+
``argv=None`` reads the process arguments, as for any argparse program.
|
|
19
|
+
Graph inspection occurs after factory resolution and validation, before
|
|
20
|
+
live nodes are created, using the exact snapshot execution will use.
|
|
21
|
+
"""
|
|
22
|
+
parser = argparse.ArgumentParser(
|
|
23
|
+
description="Run a Pyrophone graph.",
|
|
24
|
+
epilog="Graph formats: " + ", ".join(GRAPH_FORMATS) + ".",
|
|
25
|
+
)
|
|
26
|
+
parser.add_argument(
|
|
27
|
+
"--pp-show-graph",
|
|
28
|
+
nargs="?",
|
|
29
|
+
const="pretty",
|
|
30
|
+
choices=GRAPH_FORMATS,
|
|
31
|
+
metavar="FORMAT",
|
|
32
|
+
help="show the final graph on stderr before execution (default: pretty)",
|
|
33
|
+
)
|
|
34
|
+
parser.add_argument(
|
|
35
|
+
"--pp-dump-graph",
|
|
36
|
+
nargs="?",
|
|
37
|
+
const="yaml",
|
|
38
|
+
choices=GRAPH_FORMATS,
|
|
39
|
+
metavar="FORMAT",
|
|
40
|
+
help="dump the final graph to stdout and exit without execution (default: yaml)",
|
|
41
|
+
)
|
|
42
|
+
parser.add_argument(
|
|
43
|
+
"--pp-shell",
|
|
44
|
+
action="store_true",
|
|
45
|
+
help="open an async Python REPL on stdio alongside the graph",
|
|
46
|
+
)
|
|
47
|
+
options = parser.parse_args(argv)
|
|
48
|
+
if (
|
|
49
|
+
options.pp_show_graph is None
|
|
50
|
+
and options.pp_dump_graph is None
|
|
51
|
+
and not options.pp_shell
|
|
52
|
+
):
|
|
53
|
+
run_sync(target)
|
|
54
|
+
return
|
|
55
|
+
|
|
56
|
+
def inspect_graph(graph: CompiledGraph) -> None:
|
|
57
|
+
if options.pp_show_graph is not None:
|
|
58
|
+
print(
|
|
59
|
+
render_graph(graph, options.pp_show_graph),
|
|
60
|
+
file=sys.stderr,
|
|
61
|
+
end="",
|
|
62
|
+
flush=True,
|
|
63
|
+
)
|
|
64
|
+
if options.pp_dump_graph is not None:
|
|
65
|
+
print(render_graph(graph, options.pp_dump_graph), end="", flush=True)
|
|
66
|
+
|
|
67
|
+
runtime: Runtime | None = None
|
|
68
|
+
|
|
69
|
+
def inspect_runtime(controller: Runtime) -> None:
|
|
70
|
+
nonlocal runtime
|
|
71
|
+
runtime = controller
|
|
72
|
+
|
|
73
|
+
async def shell_session(
|
|
74
|
+
graph: Graph, compiled: CompiledGraph, graph_task: asyncio.Task[None]
|
|
75
|
+
) -> None:
|
|
76
|
+
from ._shell import run_shell
|
|
77
|
+
|
|
78
|
+
# Sessions begin only after all instances and handles are initialized.
|
|
79
|
+
assert runtime is not None
|
|
80
|
+
await run_shell(graph, compiled, graph_task, runtime)
|
|
81
|
+
|
|
82
|
+
session = None
|
|
83
|
+
if options.pp_shell and options.pp_dump_graph is None:
|
|
84
|
+
session = shell_session
|
|
85
|
+
run_sync(
|
|
86
|
+
target,
|
|
87
|
+
on_graph=inspect_graph,
|
|
88
|
+
execute=options.pp_dump_graph is None,
|
|
89
|
+
session=session,
|
|
90
|
+
on_runtime=inspect_runtime if session is not None else None,
|
|
91
|
+
)
|
pyrophone/_entry.py
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""Import-safe script decorators and direct driver entry points."""
|
|
2
|
+
|
|
3
|
+
from typing import Protocol, overload
|
|
4
|
+
|
|
5
|
+
from ._driver import drive
|
|
6
|
+
from ._graph import Graph
|
|
7
|
+
from ._runner import _Factory
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def _decorate[F: _Factory](factory: F, /) -> F:
|
|
11
|
+
if factory.__module__ == "__main__":
|
|
12
|
+
drive(factory)
|
|
13
|
+
return factory
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class _Decorator(Protocol):
|
|
17
|
+
def __call__[F: _Factory](self, factory: F, /) -> F: ...
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@overload
|
|
21
|
+
def main(target: Graph, /) -> None: ...
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@overload
|
|
25
|
+
def main[F: _Factory](target: F, /) -> F: ...
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@overload
|
|
29
|
+
def main() -> _Decorator: ...
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def main(target: Graph | _Factory | None = None, /) -> _Factory | _Decorator | None:
|
|
33
|
+
"""Run a graph directly, or mark a graph factory as a script entry point.
|
|
34
|
+
|
|
35
|
+
``main(graph)`` immediately invokes the command-line driver, even on import.
|
|
36
|
+
The driver parses arguments before executing the graph or its factory.
|
|
37
|
+
``@main`` and ``@main()`` execute a zero-argument sync or async factory only
|
|
38
|
+
when its module is __main__. The factory and graph share an event loop.
|
|
39
|
+
Decoration always returns the original function; imported factories remain
|
|
40
|
+
callable and retain their static types.
|
|
41
|
+
|
|
42
|
+
Put decorated entry points after their dependencies: execution begins when
|
|
43
|
+
Python evaluates the decorator. Empty parentheses reserve space for future
|
|
44
|
+
options; no configuration arguments are currently accepted.
|
|
45
|
+
"""
|
|
46
|
+
if target is None:
|
|
47
|
+
return _decorate
|
|
48
|
+
if isinstance(target, Graph):
|
|
49
|
+
drive(target)
|
|
50
|
+
return None
|
|
51
|
+
if callable(target):
|
|
52
|
+
return _decorate(target)
|
|
53
|
+
raise TypeError("pyrophone.main expects a Graph or a graph factory")
|