green-screen-client 1.2.0__tar.gz

green_screen_client-1.2.0/.gitignore

@@ -0,0 +1,18 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.DS_Store
+.claude/
+apps/demo/.env
+apps/demo/.env.local
+apps/demo/e2e/screenshots/
+.wrangler/
+test-results/
+.env
+reference/
+debug/
+DEBUG_NOTES.md
+BUG_LOG.md
+*.code-workspace
+__pycache__/
+*.pyc

green_screen_client-1.2.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: green-screen-client
+Version: 1.2.0
+Summary: Python client for green-screen-proxy — typed async REST + WebSocket adapter for TN5250/TN3270/VT/HP6530 terminal emulation
+Project-URL: Homepage, https://github.com/legacybridge-software/green-screen-react
+Project-URL: Repository, https://github.com/legacybridge-software/green-screen-react
+Project-URL: Issues, https://github.com/legacybridge-software/green-screen-react/issues
+License: MIT
+Keywords: as400,emulator,green-screen,ibm-i,terminal,tn3270,tn5250
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# green-screen-client
+
+Python client for [`green-screen-proxy`](https://github.com/legacybridge-software/green-screen-react/tree/main/packages/proxy) — typed async REST + WebSocket adapter for TN5250, TN3270, VT, and HP 6530 terminal emulation.
+
+This is a **standalone package**. It is not bundled with or required by `green-screen-react` — install it separately when your integration runs on Python.
+
+## Install
+
+```bash
+pip install green-screen-client
+```
+
+## Three layers, pick what fits
+
+### 1. Low-level REST (`RestClient`)
+
+Thin wrapper over the proxy's HTTP endpoints. One method per endpoint, dataclasses in/out.
+
+```python
+from green_screen_client import RestClient, ConnectConfig
+
+async with RestClient("http://proxy:3001") as client:
+    await client.connect(ConnectConfig(
+        host="pub400.com",
+        protocol="tn5250",
+        username="alice",
+        password="secret",
+    ))
+    screen = await client.get_screen()
+    print(screen.content)
+    await client.send_text("1")
+    await client.send_key("Enter")
+```
+
+### 2. Low-level WebSocket (`WsClient`)
+
+Single WebSocket, real-time screen pushes, reattach for session recovery, lifecycle events (`session.lost`, `session.resumed`).
+
+```python
+from green_screen_client import WsClient
+
+async with WsClient("http://proxy:3001") as client:
+    await client.reattach("abc-123")   # reattach after page reload / process restart
+    client.on_screen(lambda s: print("screen update:", s.cursor_row, s.cursor_col))
+    client.on_session_lost(lambda sid, status: print("lost:", sid, status.status))
+    async for event in client.events():
+        if event.type == "screen":
+            ...
+```
+
+### 3. High-level `ProxyTerminalClient` + `ScreenBuffer`
+
+Drop-in shape for integrations that already read `client.screen.fields`, `client.screen.cursor_row`, etc.
+
+```python
+from green_screen_client import ProxyTerminalClient
+
+async with ProxyTerminalClient("http://proxy:3001", host="pub400.com") as client:
+    await client.login("alice", "secret")
+    await client.send_key("PF3")
+    print(client.screen.cursor_row, client.screen.cursor_col)
+    for field in client.screen.fields:
+        print(field)
+```
+
+## v1.2.0 primitives
+
+- `read_mdt(modified_only=True)` — cheap post-write verification via per-field MDT bits.
+- `resume_session(session_id)` — REST probe for "is this session still alive?"
+- `mark_authenticated(username)` — flip session status after your own sign-on cascade (the proxy stays protocol-generic).
+- `wait_for_fields(min_fields, timeout_ms=...)` — wait until a form with N input fields appears.
+
+## License
+
+MIT.

green_screen_client-1.2.0/README.md

@@ -0,0 +1,75 @@
+# green-screen-client
+
+Python client for [`green-screen-proxy`](https://github.com/legacybridge-software/green-screen-react/tree/main/packages/proxy) — typed async REST + WebSocket adapter for TN5250, TN3270, VT, and HP 6530 terminal emulation.
+
+This is a **standalone package**. It is not bundled with or required by `green-screen-react` — install it separately when your integration runs on Python.
+
+## Install
+
+```bash
+pip install green-screen-client
+```
+
+## Three layers, pick what fits
+
+### 1. Low-level REST (`RestClient`)
+
+Thin wrapper over the proxy's HTTP endpoints. One method per endpoint, dataclasses in/out.
+
+```python
+from green_screen_client import RestClient, ConnectConfig
+
+async with RestClient("http://proxy:3001") as client:
+    await client.connect(ConnectConfig(
+        host="pub400.com",
+        protocol="tn5250",
+        username="alice",
+        password="secret",
+    ))
+    screen = await client.get_screen()
+    print(screen.content)
+    await client.send_text("1")
+    await client.send_key("Enter")
+```
+
+### 2. Low-level WebSocket (`WsClient`)
+
+Single WebSocket, real-time screen pushes, reattach for session recovery, lifecycle events (`session.lost`, `session.resumed`).
+
+```python
+from green_screen_client import WsClient
+
+async with WsClient("http://proxy:3001") as client:
+    await client.reattach("abc-123")   # reattach after page reload / process restart
+    client.on_screen(lambda s: print("screen update:", s.cursor_row, s.cursor_col))
+    client.on_session_lost(lambda sid, status: print("lost:", sid, status.status))
+    async for event in client.events():
+        if event.type == "screen":
+            ...
+```
+
+### 3. High-level `ProxyTerminalClient` + `ScreenBuffer`
+
+Drop-in shape for integrations that already read `client.screen.fields`, `client.screen.cursor_row`, etc.
+
+```python
+from green_screen_client import ProxyTerminalClient
+
+async with ProxyTerminalClient("http://proxy:3001", host="pub400.com") as client:
+    await client.login("alice", "secret")
+    await client.send_key("PF3")
+    print(client.screen.cursor_row, client.screen.cursor_col)
+    for field in client.screen.fields:
+        print(field)
+```
+
+## v1.2.0 primitives
+
+- `read_mdt(modified_only=True)` — cheap post-write verification via per-field MDT bits.
+- `resume_session(session_id)` — REST probe for "is this session still alive?"
+- `mark_authenticated(username)` — flip session status after your own sign-on cascade (the proxy stays protocol-generic).
+- `wait_for_fields(min_fields, timeout_ms=...)` — wait until a form with N input fields appears.
+
+## License
+
+MIT.

green_screen_client-1.2.0/green_screen_client/__init__.py

@@ -0,0 +1,67 @@
+"""green-screen-client — Python client for green-screen-proxy.
+
+Typed async REST + WebSocket adapter that mirrors the wire format of
+`green-screen-types` and the adapter contract of `green-screen-react`.
+
+Three layers, pick the one that matches your integration style:
+
+1. `RestClient` — low-level async REST wrapper. One method per HTTP
+   endpoint; raw dataclasses in/out; bring your own session management.
+
+2. `WsClient` — low-level async WebSocket wrapper. Single WS, real-time
+   `onScreen`/`onStatus`/`onSessionLost` callbacks plus an async event
+   iterator.
+
+3. `ProxyTerminalClient` + `ScreenBuffer` — high-level drop-in for
+   integrations that already have code reading `client.screen.fields`,
+   `client.screen.cursor_row`, etc. Owns the REST client and maintains
+   an up-to-date buffer cache on every operation.
+
+Published separately from `green-screen-react` — install via PyPI:
+
+    pip install green-screen-client
+"""
+
+from .buffer import ProxyTerminalClient, ScreenBuffer
+from .rest import RestClient
+from .types import (
+    CellExtAttr,
+    ConnectConfig,
+    ConnectionStatus,
+    Field,
+    FieldColor,
+    FieldValue,
+    ProtocolType,
+    ScreenData,
+    SelectionChoice,
+    SelectionField,
+    SendResult,
+    ShiftType,
+    Window,
+)
+from .ws import WsClient, WsEvent
+
+__version__ = "1.2.0"
+
+__all__ = [
+    # Clients
+    "RestClient",
+    "WsClient",
+    "WsEvent",
+    "ProxyTerminalClient",
+    "ScreenBuffer",
+    # Types
+    "CellExtAttr",
+    "ConnectConfig",
+    "ConnectionStatus",
+    "Field",
+    "FieldColor",
+    "FieldValue",
+    "ProtocolType",
+    "ScreenData",
+    "SelectionChoice",
+    "SelectionField",
+    "SendResult",
+    "ShiftType",
+    "Window",
+]

green_screen_client-1.2.0/green_screen_client/buffer.py

@@ -0,0 +1,261 @@
+"""ScreenBuffer-style convenience wrapper over RestClient.
+
+Provides a synchronous-looking cached view of the current screen state
+(cursor position, fields, content, signature, OIA flags) that mirrors the
+attribute shape many IBM i integrations already use. Each `refresh()` or
+mutating operation updates the cache from the underlying RestClient.
+
+This module exists so that existing Python integrations that were reading
+attributes like `client.screen.fields`, `client.screen.cursor_row` can
+adopt green-screen-client with minimal code churn.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Optional
+
+from .rest import RestClient
+from .types import ConnectConfig, ConnectionStatus, FieldValue, ScreenData, SendResult
+
+logger = logging.getLogger(__name__)
+
+
+class ScreenBuffer:
+    """Mutable cache of the current screen state.
+
+    Fields are populated from the most recent RestClient response. A fresh
+    ScreenBuffer (before any operation has been performed) has empty
+    strings and zero counters — callers should check `.content` or call
+    `refresh()` before reading.
+    """
+
+    def __init__(self) -> None:
+        self.rows: int = 24
+        self.cols: int = 80
+        self.cursor_row: int = 0
+        self.cursor_col: int = 0
+        self.content: str = ""
+        self.screen_signature: str = ""
+        self.fields: List[dict] = []
+        self.keyboard_locked: bool = False
+        self.message_waiting: bool = False
+        self.alarm: bool = False
+        self.insert_mode: bool = False
+        self.windows: List[dict] = []
+        self.selection_fields: List[dict] = []
+        self.screen_stack_depth: int = 0
+        self.is_popup: bool = False
+        self.ext_attrs: dict = {}
+        self.dbcs_cont: List[int] = []
+        self.code_page: str = "cp37"
+
+    def apply(self, screen: Optional[ScreenData]) -> None:
+        if screen is None:
+            return
+        self.rows = screen.rows
+        self.cols = screen.cols
+        self.cursor_row = screen.cursor_row
+        self.cursor_col = screen.cursor_col
+        self.content = screen.content
+        self.screen_signature = screen.screen_signature
+        self.fields = [self._field_to_dict(f) for f in screen.fields]
+        self.keyboard_locked = bool(screen.keyboard_locked)
+        self.message_waiting = bool(screen.message_waiting)
+        self.alarm = bool(screen.alarm)
+        self.insert_mode = bool(screen.insert_mode)
+        self.windows = [vars(w) for w in (screen.windows or [])]
+        self.selection_fields = [
+            {
+                "row": sf.row,
+                "col": sf.col,
+                "num_rows": sf.num_rows,
+                "num_cols": sf.num_cols,
+                "choices": [vars(c) for c in sf.choices],
+            }
+            for sf in (screen.selection_fields or [])
+        ]
+        self.screen_stack_depth = screen.screen_stack_depth or 0
+        self.is_popup = bool(screen.is_popup)
+        self.ext_attrs = {k: vars(v) for k, v in (screen.ext_attrs or {}).items()}
+        self.dbcs_cont = list(screen.dbcs_cont or [])
+        self.code_page = screen.code_page or "cp37"
+
+    @staticmethod
+    def _field_to_dict(field) -> dict:  # type: ignore[no-untyped-def]
+        # Reconstruct a dict shape that legacy code expects, including the
+        # conventional 5250 'attr' byte (bit 0x08 = protected).
+        attr = 0x28 if field.is_protected else 0x20
+        if field.is_highlighted:
+            attr |= 0x02
+        return {
+            "row": field.row,
+            "col": field.col,
+            "length": field.length,
+            "attr": attr,
+            "is_input": field.is_input,
+            "is_protected": field.is_protected,
+            "is_highlighted": bool(field.is_highlighted),
+            "is_reverse": bool(field.is_reverse),
+            "is_underscored": bool(field.is_underscored),
+            "is_non_display": bool(field.is_non_display),
+            "is_mandatory": False,
+            "color": field.color,
+            "shift_type": field.shift_type,
+            "monocase": bool(field.monocase),
+            "is_dbcs": bool(field.is_dbcs),
+            "self_check_mod10": bool(field.self_check_mod10),
+            "self_check_mod11": bool(field.self_check_mod11),
+            "resequence": field.resequence,
+            "progression_id": field.progression_id,
+            "highlight_entry_attr": field.highlight_entry_attr,
+            "modified": bool(field.modified) if field.modified is not None else False,
+        }
+
+
+class ProxyTerminalClient:
+    """High-level drop-in replacement for legacy ProxyTN5250Client-style
+    classes. Owns a RestClient + a ScreenBuffer cache and exposes the
+    familiar async method shape (connect, login, send_text, send_key,
+    set_cursor, get_screen, read_mdt, disconnect).
+
+    Example (LegacyBridge migration path):
+
+        client = ProxyTerminalClient("http://proxy:3001", host="pub400.com")
+        await client.connect()
+        await client.login("alice", "secret")      # uses proxy auto sign-on
+        await client.send_key("PF3")
+        print(client.screen.cursor_row, client.screen.cursor_col)
+        await client.disconnect()
+    """
+
+    def __init__(
+        self,
+        proxy_url: str,
+        *,
+        host: str,
+        port: int = 23,
+        protocol: str = "tn5250",
+        terminal_type: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._rest = RestClient(proxy_url, timeout=timeout)
+        self._host = host
+        self._port = port
+        self._protocol = protocol
+        self._terminal_type = terminal_type
+        self.screen = ScreenBuffer()
+        self._connected = False
+        self._error_message: Optional[str] = None
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    @property
+    def session_id(self) -> Optional[str]:
+        return self._rest.session_id
+
+    @property
+    def error_message(self) -> Optional[str]:
+        return self._error_message
+
+    async def __aenter__(self) -> "ProxyTerminalClient":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.disconnect()
+
+    async def connect(self) -> bool:
+        result = await self._rest.connect(
+            ConnectConfig(
+                host=self._host,
+                port=self._port,
+                protocol=self._protocol,  # type: ignore[arg-type]
+                terminal_type=self._terminal_type,
+                connect_timeout=int(self._rest._timeout * 1000),
+            )
+        )
+        self._connected = result.success
+        self._error_message = result.error
+        # Snap an initial screen if one is available
+        try:
+            self.screen.apply(await self._rest.get_screen())
+        except Exception as e:
+            logger.debug("initial get_screen after connect failed: %s", e)
+        return result.success
+
+    async def login(self, username: str, password: str) -> bool:
+        """Connect with the proxy's built-in auto-sign-on (sends credentials
+        in the /connect body). For multi-step IBM i post-sign-on cascades,
+        prefer composing: `connect()` → type credentials → Enter → drive
+        intermediate screens → `mark_authenticated(username)`."""
+        result = await self._rest.connect(
+            ConnectConfig(
+                host=self._host,
+                port=self._port,
+                protocol=self._protocol,  # type: ignore[arg-type]
+                terminal_type=self._terminal_type,
+                username=username,
+                password=password,
+                connect_timeout=int(self._rest._timeout * 1000),
+            )
+        )
+        self._connected = result.success
+        self._error_message = result.error
+        try:
+            self.screen.apply(await self._rest.get_screen())
+        except Exception:
+            pass
+        return result.success
+
+    async def disconnect(self) -> None:
+        try:
+            await self._rest.disconnect()
+        finally:
+            self._connected = False
+            await self._rest.close()
+
+    async def get_screen(self) -> str:
+        screen = await self._rest.get_screen()
+        self.screen.apply(screen)
+        return self.screen.content
+
+    async def send_text(self, text: str) -> bool:
+        result = await self._rest.send_text(text)
+        if result.success:
+            # Fetch the updated screen so callers see the effect
+            self.screen.apply(await self._rest.get_screen())
+        return result.success
+
+    async def send_key(self, key: str) -> bool:
+        result = await self._rest.send_key(key)
+        if result.success:
+            self.screen.apply(await self._rest.get_screen())
+        return result.success
+
+    async def send_enter(self) -> bool:
+        return await self.send_key("Enter")
+
+    async def send_tab(self) -> bool:
+        return await self.send_key("Tab")
+
+    async def set_cursor(self, row: int, col: int) -> bool:
+        result = await self._rest.set_cursor(row, col)
+        if result.success:
+            self.screen.cursor_row = result.cursor_row or row
+            self.screen.cursor_col = result.cursor_col or col
+        return result.success
+
+    async def read_mdt(self, modified_only: bool = True) -> List[FieldValue]:
+        return await self._rest.read_mdt(modified_only=modified_only)
+
+    async def mark_authenticated(self, username: str) -> bool:
+        result = await self._rest.mark_authenticated(username)
+        return result.success
+
+    async def wait_for_fields(self, min_fields: int, *, timeout_ms: int = 5000) -> bool:
+        return await self._rest.wait_for_fields(min_fields, timeout_ms=timeout_ms) is not None
+
+    async def get_status(self) -> ConnectionStatus:
+        return await self._rest.get_status()