Metadata-Version: 2.4
Name: pynect
Version: 0.8.16
Summary: Chanx schema export and owned stdio adapter for Pynect
Author: regbo
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Requires-Dist: chanx[fast-channels]>=2.13.0,<3
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/regbo/lfp-common/tree/main/packages/py/pynect#readme
Project-URL: Repository, https://github.com/regbo/lfp-common.git
Project-URL: Issues, https://github.com/regbo/lfp-common/issues
Description-Content-Type: text/markdown

# pynect

`pynect` is Pynect's Python package. It exports Chanx AsyncAPI schemas,
adds an iterator-aware server consumer, and runs Python-owned Chanx applications
inside Pynect's one-owner stdio worker.

## Install

```sh
uv add pynect
```

Configure the ASGI application in the owning Python project:

```toml
[tool.pynect]
app = "server:app"
```

## Server iterators

Subclass Pynect's consumer, use Chanx's standard `ws_handler`, and annotate an
iterator return type. Pynect forwards each item and emits Chanx's protocol-level
`complete` frame when the iterator exits normally.

```py
from collections.abc import AsyncIterator
from chanx.core.decorators import ws_handler
from pynect import AsyncJsonWebsocketConsumer

class CatalogConsumer(AsyncJsonWebsocketConsumer):
    @ws_handler
    async def watch(self, message: WatchRequest) -> AsyncIterator[WatchResponse]:
        yield WatchResponse(payload=message.payload)
```

The Pynect consumer also accepts synchronous handlers and synchronous
`Iterator[Response]` streams. Async handlers continue to use Chanx unchanged.
Chanx's annotations currently type handlers as async-only, so place a portable
ignore on synchronous decorator applications:

```py
# Chanx types handlers as async; Pynect adapts synchronous callables.
@ws_handler  # type: ignore
def watch_sync(self, message: WatchRequest) -> Iterator[WatchResponse]:
    yield WatchResponse(payload=message.payload)
```

Pynect closes server iterators deterministically after normal completion,
early return, iteration failure, send failure, or handler cancellation. Normal
completion emits `complete`; failures remain Chanx handler errors.

## Owned stdio transport

The JavaScript `startWorker()` launcher owns the Python process and sends
byte-length-delimited events over stdin. Python multiplexes response events with
ordinary stdout and forwards stderr separately. The random per-process marker
lets Pynect preserve binary application output without requiring it to end with
a newline. There is no socket endpoint, shared mode, endpoint
discovery, stale-endpoint cleanup, or parent-PID polling.

MIT licensed.
