pynect 0.0.0__tar.gz → 0.8.13__tar.gz

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.
pynect-0.8.13/PKG-INFO ADDED
@@ -0,0 +1,86 @@
1
+ Metadata-Version: 2.4
2
+ Name: pynect
3
+ Version: 0.8.13
4
+ Summary: Chanx schema export and owned stdio adapter for Pynect
5
+ Author: regbo
6
+ License-Expression: MIT
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3.11
9
+ Classifier: Programming Language :: Python :: 3.12
10
+ Classifier: Programming Language :: Python :: 3.13
11
+ Classifier: Programming Language :: Python :: 3.14
12
+ Classifier: Typing :: Typed
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Requires-Dist: chanx[fast-channels]>=2.13.0,<3
16
+ Requires-Python: >=3.11
17
+ Project-URL: Homepage, https://github.com/regbo/lfp-common/tree/main/packages/py/pynect#readme
18
+ Project-URL: Repository, https://github.com/regbo/lfp-common.git
19
+ Project-URL: Issues, https://github.com/regbo/lfp-common/issues
20
+ Description-Content-Type: text/markdown
21
+
22
+ # pynect
23
+
24
+ `pynect` is Pynect's Python package. It exports Chanx AsyncAPI schemas,
25
+ adds an iterator-aware server consumer, and runs Python-owned Chanx applications
26
+ inside Pynect's one-owner stdio worker.
27
+
28
+ ## Install
29
+
30
+ ```sh
31
+ uv add pynect
32
+ ```
33
+
34
+ Configure the ASGI application in the owning Python project:
35
+
36
+ ```toml
37
+ [tool.pynect]
38
+ app = "server:app"
39
+ ```
40
+
41
+ ## Server iterators
42
+
43
+ Subclass Pynect's consumer, use Chanx's standard `ws_handler`, and annotate an
44
+ iterator return type. Pynect forwards each item and emits Chanx's protocol-level
45
+ `complete` frame when the iterator exits normally.
46
+
47
+ ```py
48
+ from collections.abc import AsyncIterator
49
+ from chanx.core.decorators import ws_handler
50
+ from pynect import AsyncJsonWebsocketConsumer
51
+
52
+ class CatalogConsumer(AsyncJsonWebsocketConsumer):
53
+ @ws_handler
54
+ async def watch(self, message: WatchRequest) -> AsyncIterator[WatchResponse]:
55
+ yield WatchResponse(payload=message.payload)
56
+ ```
57
+
58
+ `pynect.ws_handler` remains available for compatibility but is
59
+ deprecated.
60
+
61
+ The Pynect consumer also accepts synchronous handlers and synchronous
62
+ `Iterator[Response]` streams. Async handlers continue to use Chanx unchanged.
63
+ Chanx's annotations currently type handlers as async-only, so place a portable
64
+ ignore on synchronous decorator applications:
65
+
66
+ ```py
67
+ # Chanx types handlers as async; Pynect adapts synchronous callables.
68
+ @ws_handler # type: ignore
69
+ def watch_sync(self, message: WatchRequest) -> Iterator[WatchResponse]:
70
+ yield WatchResponse(payload=message.payload)
71
+ ```
72
+
73
+ Pynect closes server iterators deterministically after normal completion,
74
+ early return, iteration failure, send failure, or handler cancellation. Normal
75
+ completion emits `complete`; failures remain Chanx handler errors.
76
+
77
+ ## Owned stdio transport
78
+
79
+ The JavaScript `startWorker()` launcher owns the Python process and sends
80
+ byte-length-delimited events over stdin. Python multiplexes response events with
81
+ ordinary stdout and forwards stderr separately. The random per-process marker
82
+ lets Pynect preserve binary application output without requiring it to end with
83
+ a newline. There is no socket endpoint, shared mode, endpoint
84
+ discovery, stale-endpoint cleanup, or parent-PID polling.
85
+
86
+ MIT licensed.
@@ -0,0 +1,65 @@
1
+ # pynect
2
+
3
+ `pynect` is Pynect's Python package. It exports Chanx AsyncAPI schemas,
4
+ adds an iterator-aware server consumer, and runs Python-owned Chanx applications
5
+ inside Pynect's one-owner stdio worker.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ uv add pynect
11
+ ```
12
+
13
+ Configure the ASGI application in the owning Python project:
14
+
15
+ ```toml
16
+ [tool.pynect]
17
+ app = "server:app"
18
+ ```
19
+
20
+ ## Server iterators
21
+
22
+ Subclass Pynect's consumer, use Chanx's standard `ws_handler`, and annotate an
23
+ iterator return type. Pynect forwards each item and emits Chanx's protocol-level
24
+ `complete` frame when the iterator exits normally.
25
+
26
+ ```py
27
+ from collections.abc import AsyncIterator
28
+ from chanx.core.decorators import ws_handler
29
+ from pynect import AsyncJsonWebsocketConsumer
30
+
31
+ class CatalogConsumer(AsyncJsonWebsocketConsumer):
32
+ @ws_handler
33
+ async def watch(self, message: WatchRequest) -> AsyncIterator[WatchResponse]:
34
+ yield WatchResponse(payload=message.payload)
35
+ ```
36
+
37
+ `pynect.ws_handler` remains available for compatibility but is
38
+ deprecated.
39
+
40
+ The Pynect consumer also accepts synchronous handlers and synchronous
41
+ `Iterator[Response]` streams. Async handlers continue to use Chanx unchanged.
42
+ Chanx's annotations currently type handlers as async-only, so place a portable
43
+ ignore on synchronous decorator applications:
44
+
45
+ ```py
46
+ # Chanx types handlers as async; Pynect adapts synchronous callables.
47
+ @ws_handler # type: ignore
48
+ def watch_sync(self, message: WatchRequest) -> Iterator[WatchResponse]:
49
+ yield WatchResponse(payload=message.payload)
50
+ ```
51
+
52
+ Pynect closes server iterators deterministically after normal completion,
53
+ early return, iteration failure, send failure, or handler cancellation. Normal
54
+ completion emits `complete`; failures remain Chanx handler errors.
55
+
56
+ ## Owned stdio transport
57
+
58
+ The JavaScript `startWorker()` launcher owns the Python process and sends
59
+ byte-length-delimited events over stdin. Python multiplexes response events with
60
+ ordinary stdout and forwards stderr separately. The random per-process marker
61
+ lets Pynect preserve binary application output without requiring it to end with
62
+ a newline. There is no socket endpoint, shared mode, endpoint
63
+ discovery, stale-endpoint cleanup, or parent-PID polling.
64
+
65
+ MIT licensed.
@@ -0,0 +1,64 @@
1
+ [project]
2
+ name = "pynect"
3
+ version = "0.8.13"
4
+ description = "Chanx schema export and owned stdio adapter for Pynect"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "MIT"
8
+ classifiers = [
9
+ "Programming Language :: Python :: 3",
10
+ "Programming Language :: Python :: 3.11",
11
+ "Programming Language :: Python :: 3.12",
12
+ "Programming Language :: Python :: 3.13",
13
+ "Programming Language :: Python :: 3.14",
14
+ "Typing :: Typed",
15
+ "Development Status :: 4 - Beta",
16
+ "Environment :: Console",
17
+ ]
18
+ dependencies = ["chanx[fast_channels]>=2.13.0,<3"]
19
+
20
+ [[project.authors]]
21
+ name = "regbo"
22
+
23
+ [project.urls]
24
+ Homepage = "https://github.com/regbo/lfp-common/tree/main/packages/py/pynect#readme"
25
+ Repository = "https://github.com/regbo/lfp-common.git"
26
+ Issues = "https://github.com/regbo/lfp-common/issues"
27
+
28
+ [project.scripts]
29
+ pynect-schema = "pynect.schema:main"
30
+
31
+ [build-system]
32
+ requires = ["uv_build>=0.10.7,<0.11"]
33
+ build-backend = "uv_build"
34
+
35
+ [tool.uv.build-backend]
36
+ module-name = "pynect"
37
+ module-root = "src"
38
+
39
+ [tool.ruff]
40
+ line-length = 120
41
+ target-version = "py311"
42
+ src = [
43
+ "src",
44
+ "tests",
45
+ ]
46
+ exclude = ["src/pynect/_generated"]
47
+
48
+ [tool.ruff.format]
49
+ indent-style = "space"
50
+ line-ending = "lf"
51
+ quote-style = "double"
52
+
53
+ [tool.ruff.lint]
54
+ select = [
55
+ "E",
56
+ "F",
57
+ "I",
58
+ "UP",
59
+ "B",
60
+ "SIM",
61
+ ]
62
+
63
+ [tool.pytest.ini_options]
64
+ testpaths = ["tests"]
@@ -0,0 +1,56 @@
1
+ # ~~ Generated by projen. To modify, edit .projenrc.js and run "bunx projen".
2
+
3
+ [project]
4
+ name = "pynect"
5
+ version = "0.8.13"
6
+ description = "Chanx schema export and owned stdio adapter for Pynect"
7
+ readme = "README.md"
8
+ requires-python = ">=3.11"
9
+ license = "MIT"
10
+ classifiers = [
11
+ "Programming Language :: Python :: 3",
12
+ "Programming Language :: Python :: 3.11",
13
+ "Programming Language :: Python :: 3.12",
14
+ "Programming Language :: Python :: 3.13",
15
+ "Programming Language :: Python :: 3.14",
16
+ "Typing :: Typed",
17
+ "Development Status :: 4 - Beta",
18
+ "Environment :: Console"
19
+ ]
20
+ dependencies = [ "chanx[fast_channels]>=2.13.0,<3" ]
21
+
22
+ [[project.authors]]
23
+ name = "regbo"
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/regbo/lfp-common/tree/main/packages/py/pynect#readme"
27
+ Repository = "https://github.com/regbo/lfp-common.git"
28
+ Issues = "https://github.com/regbo/lfp-common/issues"
29
+
30
+ [project.scripts]
31
+ pynect-schema = "pynect.schema:main"
32
+
33
+ [build-system]
34
+ requires = [ "uv_build>=0.10.7,<0.11" ]
35
+ build-backend = "uv_build"
36
+
37
+ [tool.uv.build-backend]
38
+ module-name = "pynect"
39
+ module-root = "src"
40
+
41
+ [tool.ruff]
42
+ line-length = 120
43
+ target-version = "py311"
44
+ src = [ "src", "tests" ]
45
+ exclude = [ "src/pynect/_generated" ]
46
+
47
+ [tool.ruff.format]
48
+ indent-style = "space"
49
+ line-ending = "lf"
50
+ quote-style = "double"
51
+
52
+ [tool.ruff.lint]
53
+ select = [ "E", "F", "I", "UP", "B", "SIM" ]
54
+
55
+ [tool.pytest.ini_options]
56
+ testpaths = [ "tests" ]
@@ -0,0 +1,7 @@
1
+ """Python handler, schema, and owned-worker adapters for Pynect."""
2
+
3
+ from pynect._generated.metadata import PACKAGE_NAME, PACKAGE_VERSION
4
+ from pynect.handlers import ws_handler
5
+ from pynect.websocket import AsyncJsonWebsocketConsumer
6
+
7
+ __all__ = ["AsyncJsonWebsocketConsumer", "PACKAGE_NAME", "PACKAGE_VERSION", "ws_handler"]
@@ -0,0 +1,18 @@
1
+ """Import configured ASGI application objects."""
2
+
3
+ from importlib import import_module
4
+ from typing import Any
5
+
6
+
7
+ def load_object(target: str) -> Any:
8
+ """Load a dotted object from a ``module:object`` target."""
9
+ module_name, separator, object_path = target.partition(":")
10
+ if not separator or not module_name or not object_path:
11
+ raise ValueError('ASGI app must use the form "module:object"')
12
+
13
+ value: Any = import_module(module_name)
14
+ for name in object_path.split("."):
15
+ if not name.isidentifier():
16
+ raise ValueError('ASGI app must use the form "module:object"')
17
+ value = getattr(value, name)
18
+ return value
@@ -0,0 +1 @@
1
+ """Generated package metadata."""
@@ -0,0 +1,3 @@
1
+ """Package identity synthesized from the shared Projen configuration."""
2
+ PACKAGE_NAME = "pynect"
3
+ PACKAGE_VERSION = "0.8.13"
@@ -0,0 +1,127 @@
1
+ """Iterator adaptation shared by Pynect consumers and legacy decorators."""
2
+
3
+ import inspect
4
+ import warnings
5
+ from collections.abc import AsyncGenerator, AsyncIterator, Generator, Iterator
6
+ from functools import wraps
7
+ from types import UnionType
8
+ from typing import Any, Union, get_args, get_origin, get_type_hints
9
+
10
+ from chanx.core.decorators import ws_handler as chanx_ws_handler
11
+ from chanx.messages.base import BaseMessage
12
+ from chanx.messages.outgoing import CompleteMessage
13
+
14
+ _STREAM_ORIGINS = {AsyncGenerator, AsyncIterator, Generator, Iterator}
15
+ _STREAM_OPERATIONS: set[tuple[str, str]] = set()
16
+
17
+
18
+ def ws_handler(func: Any = None, **options: Any) -> Any:
19
+ """Decorate a Chanx handler with the pre-0.9 Pynect streaming adapter."""
20
+
21
+ warnings.warn(
22
+ "pynect.ws_handler is deprecated; import ws_handler from chanx.core.decorators "
23
+ "and subclass pynect.AsyncJsonWebsocketConsumer instead.",
24
+ DeprecationWarning,
25
+ stacklevel=2,
26
+ )
27
+
28
+ def decorate(handler: Any) -> Any:
29
+ return _adapt_handler(chanx_ws_handler(handler, **options))
30
+
31
+ return decorate if func is None else decorate(func)
32
+
33
+
34
+ def _adapt_handler(handler: Any) -> Any:
35
+ """Adapt synchronous and iterator-annotated Chanx handlers."""
36
+ handler_info = getattr(handler, "_ws_handler_info", None)
37
+ if handler_info is None or handler_info.get("x_pynect_stream"):
38
+ return handler
39
+
40
+ original = inspect.unwrap(handler)
41
+ item_type = _stream_item_type(get_type_hints(original).get("return"))
42
+ if item_type is None:
43
+ return _adapt_sync_handler(handler, original, handler_info)
44
+
45
+ declared_output_type = handler_info.get("output_type")
46
+ output_type = (
47
+ item_type if _stream_item_type(declared_output_type) is not None else declared_output_type or item_type
48
+ )
49
+ _validate_output_type(output_type, original.__name__)
50
+ handler_info["output_type"] = output_type
51
+ handler_info["x_pynect_stream"] = True
52
+ _STREAM_OPERATIONS.add((handler_info["action"], handler_info["input_type"].__name__))
53
+
54
+ @wraps(original)
55
+ async def forward_stream(*args: Any, **kwargs: Any) -> None:
56
+ result = original(*args, **kwargs)
57
+ if inspect.isawaitable(result):
58
+ result = await result
59
+
60
+ consumer = args[0]
61
+ completed = False
62
+ try:
63
+ if isinstance(result, AsyncIterator):
64
+ async for message in result:
65
+ await consumer.send_message(message)
66
+ elif isinstance(result, Iterator):
67
+ for message in result:
68
+ await consumer.send_message(message)
69
+ else:
70
+ raise TypeError(
71
+ f"Streaming handler {original.__name__} returned {type(result).__name__}, expected an iterator."
72
+ )
73
+ completed = True
74
+ finally:
75
+ await _close_iterator(result)
76
+
77
+ if completed and not consumer.should_send_completion:
78
+ await consumer.send_message(CompleteMessage())
79
+
80
+ forward_stream._ws_handler_info = handler_info # type: ignore[attr-defined]
81
+ return forward_stream
82
+
83
+
84
+ def _adapt_sync_handler(handler: Any, original: Any, handler_info: Any) -> Any:
85
+ """Wrap a synchronous handler so Chanx can await it normally."""
86
+ if inspect.iscoroutinefunction(original):
87
+ return handler
88
+
89
+ @wraps(original)
90
+ async def call_sync(*args: Any, **kwargs: Any) -> Any:
91
+ result = original(*args, **kwargs)
92
+ return await result if inspect.isawaitable(result) else result
93
+
94
+ call_sync._ws_handler_info = handler_info # type: ignore[attr-defined]
95
+ return call_sync
96
+
97
+
98
+ async def _close_iterator(iterator: Any) -> None:
99
+ """Deterministically release iterator resources after completion or failure."""
100
+ if close_async := getattr(iterator, "aclose", None):
101
+ await close_async()
102
+ elif close := getattr(iterator, "close", None):
103
+ close()
104
+
105
+
106
+ def stream_operations() -> frozenset[tuple[str, str]]:
107
+ """Return operation and request type pairs for iterator handlers."""
108
+ return frozenset(_STREAM_OPERATIONS)
109
+
110
+
111
+ def _stream_item_type(annotation: Any) -> Any | None:
112
+ origin = get_origin(annotation)
113
+ if origin not in _STREAM_ORIGINS:
114
+ return None
115
+ arguments = get_args(annotation)
116
+ return arguments[0] if arguments else None
117
+
118
+
119
+ def _validate_output_type(output_type: Any, handler_name: str) -> None:
120
+ if isinstance(output_type, list | tuple):
121
+ types = tuple(output_type)
122
+ elif get_origin(output_type) in (UnionType, Union):
123
+ types = get_args(output_type)
124
+ else:
125
+ types = (output_type,)
126
+ if not types or any(not (inspect.isclass(candidate) and issubclass(candidate, BaseMessage)) for candidate in types):
127
+ raise TypeError(f"Streaming handler {handler_name} must yield BaseMessage subclasses.")
@@ -0,0 +1,71 @@
1
+ """Export a Chanx AsyncAPI document from a configured ASGI app."""
2
+
3
+ import json
4
+ import os
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from chanx.fast_channels.views import generate_asyncapi_schema
9
+ from starlette.requests import Request
10
+
11
+ from pynect._app import load_object
12
+ from pynect.handlers import stream_operations
13
+
14
+
15
+ def export_schema(app_target: str, output: Path) -> None:
16
+ """Generate AsyncAPI without starting an HTTP server."""
17
+ app = load_object(app_target)
18
+ request = Request(
19
+ {
20
+ "type": "http",
21
+ "asgi": {"version": "3.0", "spec_version": "2.4"},
22
+ "http_version": "1.1",
23
+ "method": "GET",
24
+ "scheme": "http",
25
+ "path": "/",
26
+ "raw_path": b"/",
27
+ "root_path": "",
28
+ "query_string": b"",
29
+ "headers": [],
30
+ "client": ("127.0.0.1", 0),
31
+ "server": ("localhost", 80),
32
+ "state": {},
33
+ "app": app,
34
+ }
35
+ )
36
+ schema: dict[str, Any] = generate_asyncapi_schema(request=request, app=app)
37
+ for operation_name, input_type_name in stream_operations():
38
+ operation = schema.get("operations", {}).get(operation_name)
39
+ if operation is None:
40
+ continue
41
+ if not any(
42
+ _message_schema_name(schema, message.get("$ref")) == input_type_name
43
+ for message in operation.get("messages", [])
44
+ ):
45
+ continue
46
+ operation["x-pynect-stream"] = True
47
+ output.parent.mkdir(parents=True, exist_ok=True)
48
+ temporary = output.with_name(f".{output.name}.{os.getpid()}.tmp")
49
+ temporary.write_text(json.dumps(schema, indent=2) + "\n", encoding="utf-8")
50
+ temporary.replace(output)
51
+
52
+
53
+ def _message_schema_name(schema: dict[str, Any], message_ref: str | None) -> str | None:
54
+ """Resolve an operation message reference to its Pydantic schema name."""
55
+ if not message_ref:
56
+ return None
57
+ message_name = message_ref.rsplit("/", 1)[-1]
58
+ message = schema.get("components", {}).get("messages", {}).get(message_name, {})
59
+ payload_ref = message.get("payload", {}).get("$ref")
60
+ return payload_ref.rsplit("/", 1)[-1] if payload_ref else None
61
+
62
+
63
+ def main() -> None:
64
+ """Console entry point driven by the Node launcher environment."""
65
+ app_target = os.environ.get("PYNECT_APP")
66
+ output = os.environ.get("PYNECT_SCHEMA_PATH")
67
+ if not app_target:
68
+ raise RuntimeError("PYNECT_APP is required")
69
+ if not output:
70
+ raise RuntimeError("PYNECT_SCHEMA_PATH is required")
71
+ export_schema(app_target, Path(output))
@@ -0,0 +1,29 @@
1
+ """Chanx WebSocket consumer with transparent iterator handler support."""
2
+
3
+ from typing import Any
4
+
5
+ from chanx.core.websocket import ChanxWebsocketConsumerMixin
6
+ from chanx.messages.base import BaseMessage
7
+ from fast_channels.consumer import AsyncJsonWebsocketConsumer as FastChannelsAsyncJsonWebsocketConsumer
8
+ from fast_channels.layers import get_channel_layer
9
+ from typing_extensions import TypeVar
10
+
11
+ from pynect.handlers import _adapt_handler
12
+
13
+ ReceiveEvent = TypeVar("ReceiveEvent", bound=BaseMessage, default=BaseMessage)
14
+
15
+
16
+ class AsyncJsonWebsocketConsumer(ChanxWebsocketConsumerMixin[ReceiveEvent], FastChannelsAsyncJsonWebsocketConsumer):
17
+ """Adapt iterator-annotated Chanx handlers before Chanx registers them."""
18
+
19
+ # Compose the runtime bases directly so stdio applications do not import
20
+ # Chanx's FastAPI documentation package through chanx.fast_channels.
21
+ channel_layer_alias: str
22
+ get_channel_layer = get_channel_layer # type: ignore[assignment]
23
+
24
+ def __init_subclass__(cls, **kwargs: Any) -> None:
25
+ for name, handler in tuple(cls.__dict__.items()):
26
+ if hasattr(handler, "_ws_handler_info"):
27
+ setattr(cls, name, _adapt_handler(handler))
28
+
29
+ super().__init_subclass__(**kwargs)
@@ -0,0 +1 @@
1
+ """Owned stdio transport for Pynect workers."""
@@ -0,0 +1,197 @@
1
+ """Typed marker-and-length records for the owned stdio transport."""
2
+
3
+ import json
4
+ import os
5
+ import sys
6
+ import threading
7
+ from collections.abc import Mapping
8
+ from io import BytesIO
9
+ from typing import Any, BinaryIO, Literal, TypedDict
10
+
11
+ MAX_RECORD_BYTES = 16 * 1024 * 1024
12
+ PROTOCOL_VERSION = 1
13
+
14
+
15
+ class ProtocolError(ValueError):
16
+ """A prefixed record violates the stdio transport contract."""
17
+
18
+
19
+ class OpenEvent(TypedDict):
20
+ """Open the worker's one virtual WebSocket connection."""
21
+
22
+ type: Literal["open"]
23
+ path: str
24
+ query: str
25
+ headers: dict[str, str]
26
+ subprotocols: list[str]
27
+
28
+
29
+ class FrameEvent(TypedDict):
30
+ """Carry one opaque Chanx text frame."""
31
+
32
+ type: Literal["frame"]
33
+ data: str
34
+
35
+
36
+ class CloseEvent(TypedDict):
37
+ """Close the virtual WebSocket connection."""
38
+
39
+ type: Literal["close"]
40
+ code: int
41
+ reason: str
42
+
43
+
44
+ class ShutdownEvent(TypedDict):
45
+ """Request graceful worker termination."""
46
+
47
+ type: Literal["shutdown"]
48
+
49
+
50
+ ParentEvent = OpenEvent | FrameEvent | CloseEvent | ShutdownEvent
51
+
52
+
53
+ def prefix_from_environment() -> bytes:
54
+ """Read and validate the complete random record prefix."""
55
+ value = os.environ.get("PYNECT_STDIO_PREFIX")
56
+ if not value:
57
+ raise RuntimeError("PYNECT_STDIO_PREFIX is required")
58
+ try:
59
+ prefix = value.encode("ascii")
60
+ except UnicodeEncodeError as error:
61
+ raise RuntimeError("PYNECT_STDIO_PREFIX must be ASCII") from error
62
+ if not value.startswith("@pynect:") or not value.endswith(" "):
63
+ raise RuntimeError("PYNECT_STDIO_PREFIX has an invalid shape")
64
+ return prefix
65
+
66
+
67
+ def encode_record(prefix: bytes, event: Mapping[str, Any]) -> bytes:
68
+ """Serialize a marker, decimal byte length, separator, and JSON payload."""
69
+ payload = json.dumps(event, ensure_ascii=False, separators=(",", ":")).encode()
70
+ if len(payload) > MAX_RECORD_BYTES:
71
+ raise ProtocolError(f"Pynect record exceeds {MAX_RECORD_BYTES} bytes")
72
+ return prefix + str(len(payload)).encode("ascii") + b":" + payload
73
+
74
+
75
+ def parse_parent_record(record: bytes, prefix: bytes) -> ParentEvent:
76
+ """Parse one complete in-memory record and reject trailing bytes."""
77
+ input_stream = BytesIO(record)
78
+ event = read_parent_event(input_stream, prefix)
79
+ if event is None:
80
+ raise ProtocolError("stdin ended before a Pynect protocol record")
81
+ if input_stream.read(1):
82
+ raise ProtocolError("Pynect protocol record contains trailing bytes")
83
+ return event
84
+
85
+
86
+ def read_parent_event(input_stream: BinaryIO, prefix: bytes) -> ParentEvent | None:
87
+ """Read exactly one length-prefixed event, independent of line boundaries."""
88
+ marker = _read_exact(input_stream, len(prefix), allow_clean_eof=True)
89
+ if marker is None:
90
+ return None
91
+ if marker != prefix:
92
+ raise ProtocolError("stdin contained an unframed Pynect protocol record")
93
+ digits = bytearray()
94
+ while True:
95
+ byte = _read_exact(input_stream, 1)
96
+ if byte == b":":
97
+ break
98
+ if byte is None or byte < b"0" or byte > b"9" or len(digits) >= 10:
99
+ raise ProtocolError("stdin contained an invalid Pynect record length")
100
+ digits.extend(byte)
101
+ if not digits:
102
+ raise ProtocolError("stdin contained an empty Pynect record length")
103
+ length = int(digits)
104
+ if length > MAX_RECORD_BYTES:
105
+ raise ProtocolError(f"stdin Pynect record exceeds {MAX_RECORD_BYTES} bytes")
106
+ payload = _read_exact(input_stream, length)
107
+ if payload is None:
108
+ raise ProtocolError("stdin ended during a Pynect protocol record")
109
+ try:
110
+ value = json.loads(payload)
111
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
112
+ raise ProtocolError("stdin contained malformed Pynect protocol JSON") from error
113
+ return _validate_parent_event(value)
114
+
115
+
116
+ def _validate_parent_event(value: object) -> ParentEvent:
117
+ if not isinstance(value, dict):
118
+ raise ProtocolError("Pynect protocol events must be JSON objects")
119
+
120
+ event_type = value.get("type")
121
+ if event_type == "open":
122
+ path = _string(value.get("path"), "open.path")
123
+ if not path.startswith("/"):
124
+ raise ProtocolError("open.path must be absolute")
125
+ headers_value = value.get("headers")
126
+ if not isinstance(headers_value, dict) or not all(
127
+ isinstance(name, str) and isinstance(header, str) for name, header in headers_value.items()
128
+ ):
129
+ raise ProtocolError("open.headers must map strings to strings")
130
+ subprotocols_value = value.get("subprotocols")
131
+ if not isinstance(subprotocols_value, list) or not all(
132
+ isinstance(subprotocol, str) for subprotocol in subprotocols_value
133
+ ):
134
+ raise ProtocolError("open.subprotocols must be a string array")
135
+ return {
136
+ "type": "open",
137
+ "path": path,
138
+ "query": _string(value.get("query"), "open.query"),
139
+ "headers": headers_value,
140
+ "subprotocols": subprotocols_value,
141
+ }
142
+ if event_type == "frame":
143
+ return {"type": "frame", "data": _string(value.get("data"), "frame.data")}
144
+ if event_type == "close":
145
+ code = _integer(value.get("code"), "close.code")
146
+ if not 0 <= code <= 4999:
147
+ raise ProtocolError("close.code is out of range")
148
+ return {
149
+ "type": "close",
150
+ "code": code,
151
+ "reason": _string(value.get("reason"), "close.reason"),
152
+ }
153
+ if event_type == "shutdown":
154
+ return {"type": "shutdown"}
155
+ raise ProtocolError(f"unknown Pynect protocol event type: {event_type!r}")
156
+
157
+
158
+ def _read_exact(input_stream: BinaryIO, length: int, *, allow_clean_eof: bool = False) -> bytes | None:
159
+ chunks: list[bytes] = []
160
+ remaining = length
161
+ while remaining > 0:
162
+ chunk = input_stream.read(remaining)
163
+ if not chunk:
164
+ if allow_clean_eof and remaining == length:
165
+ return None
166
+ raise ProtocolError("stdin ended during a Pynect protocol record")
167
+ chunks.append(chunk)
168
+ remaining -= len(chunk)
169
+ return b"".join(chunks)
170
+
171
+
172
+ class ProtocolWriter:
173
+ """Serialize complete protocol writes across application tasks and threads."""
174
+
175
+ def __init__(self, prefix: bytes, output: BinaryIO | None = None) -> None:
176
+ self._prefix = prefix
177
+ self._output = output or sys.stdout.buffer
178
+ self._lock = threading.Lock()
179
+
180
+ def write(self, event: Mapping[str, Any]) -> None:
181
+ """Write and explicitly flush one event without interleaving another."""
182
+ record = encode_record(self._prefix, event)
183
+ with self._lock:
184
+ self._output.write(record)
185
+ self._output.flush()
186
+
187
+
188
+ def _string(value: object, field: str) -> str:
189
+ if not isinstance(value, str):
190
+ raise ProtocolError(f"{field} must be a string")
191
+ return value
192
+
193
+
194
+ def _integer(value: object, field: str) -> int:
195
+ if type(value) is not int:
196
+ raise ProtocolError(f"{field} must be an integer")
197
+ return value
@@ -0,0 +1,256 @@
1
+ """Run one application connection over an owning process's stdin and stdout."""
2
+
3
+ import asyncio
4
+ import logging
5
+ import os
6
+ import sys
7
+ import threading
8
+ from contextlib import suppress
9
+ from dataclasses import dataclass
10
+ from typing import Any, BinaryIO
11
+
12
+ import structlog
13
+
14
+ from pynect._app import load_object
15
+ from pynect.worker.protocol import (
16
+ ParentEvent,
17
+ ProtocolError,
18
+ ProtocolWriter,
19
+ prefix_from_environment,
20
+ read_parent_event,
21
+ )
22
+
23
+ logger = logging.getLogger(__name__)
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class _ApplicationFinished:
28
+ connection: "StdioConnection"
29
+
30
+
31
+ class _EndOfInput:
32
+ pass
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class _InputFailure:
37
+ error: Exception
38
+
39
+
40
+ END_OF_INPUT = _EndOfInput()
41
+ InputItem = ParentEvent | _ApplicationFinished | _EndOfInput | _InputFailure
42
+
43
+
44
+ class StdinPump:
45
+ """Read blocking stdin on a daemon thread so the event loop can stop promptly."""
46
+
47
+ def __init__(self, input_stream: BinaryIO, prefix: bytes, queue: asyncio.Queue[InputItem]) -> None:
48
+ self._input = input_stream
49
+ self._prefix = prefix
50
+ self._queue = queue
51
+ self._loop = asyncio.get_running_loop()
52
+ self._thread = threading.Thread(target=self._read, name="pynect-stdio-reader", daemon=True)
53
+
54
+ def start(self) -> None:
55
+ """Start reading records in source order."""
56
+ self._thread.start()
57
+
58
+ def join(self) -> None:
59
+ """Wait for the reader after a terminal input event."""
60
+ self._thread.join()
61
+
62
+ def _read(self) -> None:
63
+ try:
64
+ while (event := read_parent_event(self._input, self._prefix)) is not None:
65
+ self._enqueue(event)
66
+ if event["type"] == "shutdown":
67
+ return
68
+ except Exception as error:
69
+ self._enqueue(_InputFailure(error))
70
+ finally:
71
+ self._enqueue(END_OF_INPUT)
72
+
73
+ def _enqueue(self, item: ParentEvent | _EndOfInput | _InputFailure) -> None:
74
+ with suppress(RuntimeError):
75
+ self._loop.call_soon_threadsafe(self._queue.put_nowait, item)
76
+
77
+
78
+ class StdioConnection:
79
+ """Adapt one virtual WebSocket to an ASGI application invocation."""
80
+
81
+ def __init__(
82
+ self,
83
+ app: Any,
84
+ event: dict[str, Any],
85
+ writer: ProtocolWriter,
86
+ queue: asyncio.Queue[InputItem],
87
+ ) -> None:
88
+ self._incoming: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
89
+ self._incoming.put_nowait({"type": "websocket.connect"})
90
+ self._writer = writer
91
+ self._disconnected = False
92
+ self.close_sent = False
93
+ path = event["path"]
94
+ headers = [
95
+ (name.lower().encode("latin-1"), value.encode("latin-1")) for name, value in event["headers"].items()
96
+ ]
97
+ scope = {
98
+ "type": "websocket",
99
+ "asgi": {"version": "3.0", "spec_version": "2.4"},
100
+ "http_version": "1.1",
101
+ "scheme": "ws",
102
+ "path": path,
103
+ "raw_path": path.encode(),
104
+ "query_string": event["query"].encode(),
105
+ "headers": headers,
106
+ "client": None,
107
+ "server": None,
108
+ "subprotocols": event["subprotocols"],
109
+ "state": {},
110
+ }
111
+ self.task = asyncio.create_task(app(scope, self.receive, self.send), name="pynect-stdio-application")
112
+ self.task.add_done_callback(lambda _: queue.put_nowait(_ApplicationFinished(self)))
113
+
114
+ async def receive(self) -> dict[str, Any]:
115
+ """Return the next virtual WebSocket input event."""
116
+ return await self._incoming.get()
117
+
118
+ async def send(self, message: dict[str, Any]) -> None:
119
+ """Translate ASGI output into one serialized worker event."""
120
+ message_type = message.get("type")
121
+ if message_type == "websocket.accept":
122
+ return
123
+ if message_type == "websocket.send":
124
+ data = message.get("text")
125
+ if data is None:
126
+ binary = message.get("bytes", b"")
127
+ if not isinstance(binary, bytes):
128
+ raise TypeError("websocket.send bytes must be bytes")
129
+ data = binary.decode()
130
+ if not isinstance(data, str):
131
+ raise TypeError("websocket.send text must be a string")
132
+ self._writer.write({"type": "frame", "data": data})
133
+ return
134
+ if message_type == "websocket.close":
135
+ code = message.get("code", 1000)
136
+ reason = message.get("reason", "")
137
+ if type(code) is not int or not isinstance(reason, str):
138
+ raise TypeError("websocket.close requires an integer code and string reason")
139
+ if not self.close_sent:
140
+ self.close_sent = True
141
+ self._writer.write({"type": "close", "code": code, "reason": reason})
142
+ return
143
+ raise RuntimeError(f"unsupported ASGI WebSocket event: {message_type!r}")
144
+
145
+ def frame(self, data: str) -> None:
146
+ """Deliver one opaque Chanx text frame to the application."""
147
+ if self._disconnected:
148
+ raise ProtocolError("received a frame after the virtual connection closed")
149
+ self._incoming.put_nowait({"type": "websocket.receive", "text": data})
150
+
151
+ def disconnect(self, code: int) -> None:
152
+ """Deliver at most one ASGI disconnect event."""
153
+ if self._disconnected:
154
+ return
155
+ self._disconnected = True
156
+ self._incoming.put_nowait({"type": "websocket.disconnect", "code": code})
157
+
158
+ async def stop(self, code: int) -> None:
159
+ """Let the app observe disconnect, then cancel a task that does not stop."""
160
+ self.disconnect(code)
161
+ if not self.task.done():
162
+ try:
163
+ await asyncio.wait_for(asyncio.shield(self.task), timeout=0.25)
164
+ except TimeoutError:
165
+ self.task.cancel()
166
+ with suppress(asyncio.CancelledError):
167
+ await self.task
168
+
169
+
170
+ async def serve(
171
+ app_target: str,
172
+ prefix: bytes,
173
+ input_stream: BinaryIO | None = None,
174
+ output_stream: BinaryIO | None = None,
175
+ ) -> None:
176
+ """Import the configured app and serve until shutdown or stdin EOF."""
177
+ writer = ProtocolWriter(prefix, output_stream)
178
+ queue: asyncio.Queue[InputItem] = asyncio.Queue()
179
+ pump = StdinPump(input_stream or sys.stdin.buffer, prefix, queue)
180
+ connection: StdioConnection | None = None
181
+ try:
182
+ app = load_object(app_target)
183
+ pump.start()
184
+ while True:
185
+ item = await queue.get()
186
+ if item is END_OF_INPUT:
187
+ pump.join()
188
+ if connection is not None:
189
+ await connection.stop(1001)
190
+ if not connection.close_sent:
191
+ writer.write({"type": "close", "code": 1001, "reason": "stdin closed"})
192
+ writer.write({"type": "bye"})
193
+ return
194
+ if isinstance(item, _InputFailure):
195
+ raise item.error
196
+ if isinstance(item, _ApplicationFinished):
197
+ if item.connection is not connection:
198
+ continue
199
+ if item.connection.task.cancelled():
200
+ raise RuntimeError("ASGI application was cancelled")
201
+ exception = item.connection.task.exception()
202
+ if exception is not None:
203
+ raise RuntimeError("ASGI application failed") from exception
204
+ if not item.connection.close_sent:
205
+ writer.write({"type": "close", "code": 1000, "reason": ""})
206
+ connection = None
207
+ continue
208
+
209
+ event = item
210
+ event_type = event["type"]
211
+ if event_type == "open":
212
+ if connection is not None:
213
+ raise ProtocolError("only one virtual connection may be open")
214
+ connection = StdioConnection(app, event, writer, queue)
215
+ elif event_type == "frame":
216
+ if connection is None:
217
+ raise ProtocolError("received a frame before open")
218
+ connection.frame(event["data"])
219
+ elif event_type == "close":
220
+ if connection is not None:
221
+ current = connection
222
+ connection = None
223
+ await current.stop(event["code"])
224
+ if not current.close_sent:
225
+ writer.write({"type": "close", "code": event["code"], "reason": event["reason"]})
226
+ elif event_type == "shutdown":
227
+ pump.join()
228
+ if connection is not None:
229
+ await connection.stop(1001)
230
+ if not connection.close_sent:
231
+ writer.write({"type": "close", "code": 1001, "reason": "worker shutdown"})
232
+ writer.write({"type": "bye"})
233
+ return
234
+ except Exception as error:
235
+ with suppress(Exception):
236
+ writer.write({"type": "error", "message": str(error)})
237
+ raise
238
+
239
+
240
+ def main() -> None:
241
+ """Console entry point driven by the JavaScript stdio launcher."""
242
+ level_name = os.environ.get("PYNECT_LOG_LEVEL", "WARNING").upper()
243
+ level = logging.getLevelNamesMapping().get(level_name)
244
+ if level is None:
245
+ raise ValueError(f"Unknown PYNECT_LOG_LEVEL: {level_name}")
246
+ logging.basicConfig(
247
+ level=level,
248
+ format="%(message)s",
249
+ )
250
+ structlog.configure(wrapper_class=structlog.make_filtering_bound_logger(level))
251
+ app_target = os.environ.get("PYNECT_APP")
252
+ if not app_target:
253
+ raise RuntimeError("PYNECT_APP is required")
254
+ prefix = prefix_from_environment()
255
+ with suppress(KeyboardInterrupt):
256
+ asyncio.run(serve(app_target, prefix))
pynect-0.0.0/PKG-INFO DELETED
@@ -1,22 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: pynect
3
- Version: 0.0.0
4
- Summary: Typed Python interoperability for Node.js and Bun.
5
- Keywords: python,nodejs,bun,typescript,interop
6
- Author: Reggie Bowser
7
- License-Expression: MIT
8
- Classifier: Development Status :: 2 - Pre-Alpha
9
- Classifier: License :: OSI Approved :: MIT License
10
- Classifier: Programming Language :: Python :: 3
11
- Classifier: Typing :: Typed
12
- Requires-Python: >=3.9
13
- Project-URL: Homepage, https://github.com/regbo/pyts-bridge
14
- Project-URL: Repository, https://github.com/regbo/pyts-bridge
15
- Project-URL: Issues, https://github.com/regbo/pyts-bridge/issues
16
- Description-Content-Type: text/markdown
17
-
18
- # Pynect
19
-
20
- Pynect connects Python code to Node.js and Bun with generated TypeScript types.
21
-
22
- This `0.0.0` package reserves the public package name while active development continues at [regbo/pyts-bridge](https://github.com/regbo/pyts-bridge). A usable release will replace this placeholder.
pynect-0.0.0/README.md DELETED
@@ -1,5 +0,0 @@
1
- # Pynect
2
-
3
- Pynect connects Python code to Node.js and Bun with generated TypeScript types.
4
-
5
- This `0.0.0` package reserves the public package name while active development continues at [regbo/pyts-bridge](https://github.com/regbo/pyts-bridge). A usable release will replace this placeholder.
@@ -1,24 +0,0 @@
1
- [build-system]
2
- requires = ["uv_build>=0.9.0,<1.0.0"]
3
- build-backend = "uv_build"
4
-
5
- [project]
6
- name = "pynect"
7
- version = "0.0.0"
8
- description = "Typed Python interoperability for Node.js and Bun."
9
- readme = "README.md"
10
- requires-python = ">=3.9"
11
- license = "MIT"
12
- authors = [{ name = "Reggie Bowser" }]
13
- keywords = ["python", "nodejs", "bun", "typescript", "interop"]
14
- classifiers = [
15
- "Development Status :: 2 - Pre-Alpha",
16
- "License :: OSI Approved :: MIT License",
17
- "Programming Language :: Python :: 3",
18
- "Typing :: Typed",
19
- ]
20
-
21
- [project.urls]
22
- Homepage = "https://github.com/regbo/pyts-bridge"
23
- Repository = "https://github.com/regbo/pyts-bridge"
24
- Issues = "https://github.com/regbo/pyts-bridge/issues"
@@ -1,5 +0,0 @@
1
- """Pynect package metadata for the initial public name claim."""
2
-
3
- __version__ = "0.0.0"
4
-
5
- __all__ = ["__version__"]
File without changes