ibm5250 0.1.0.dev0__tar.gz → 0.1.0.dev2__tar.gz

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/.github/copilot-instructions.md

@@ -53,7 +53,7 @@ interact.
    row*cols+col — always use `encode_addr`/`decode_addr`/`rowcol_to_pos`/
    `pos_to_rowcol` rather than hand-rolling the math).
 6. **`exceptions.py`** — all custom exceptions derive from `IBM5250Error`.
-   Note `RecvTimeout` is *not* fatal (socket alive, server just idle) — it's
+   Note `RecvTimeout` is _not_ fatal (socket alive, server just idle) — it's
    distinct from `ConnectionError`.
 
 Key stateful quirk: after a server-initiated **SAVE_SCREEN**/**RESTORE_SCREEN**

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/.github/workflows/README.md

@@ -7,11 +7,11 @@ tokens or secrets are stored in this repository.
 
 ## Branch behavior
 
-| Branch                | Test | Build | Publish | Version format          |
-|------------------------|:----:|:-----:|:-------:|--------------------------|
-| `main`                 | ✅   | ✅    | ✅ (real PyPI, production) | `X.Y.Z` (patch auto-incremented from the latest published release for that `X.Y`) |
-| `develop`              | ✅   | ✅    | ✅ (real PyPI, development) | `X.Y.Z.devN` (`N` auto-incremented per base version) |
-| any other branch       | ✅   | ✅    | ❌      | n/a (build artifact only, not published) |
+| Branch           | Test | Build |           Publish           | Version format                                                                    |
+| ---------------- | :--: | :---: | :-------------------------: | --------------------------------------------------------------------------------- |
+| `main`           |  ✅  |  ✅   | ✅ (real PyPI, production)  | `X.Y.Z` (patch auto-incremented from the latest published release for that `X.Y`) |
+| `develop`        |  ✅  |  ✅   | ✅ (real PyPI, development) | `X.Y.Z.devN` (`N` auto-incremented per base version)                              |
+| any other branch |  ✅  |  ✅   |             ❌              | n/a (build artifact only, not published)                                          |
 
 The base version (`project.version` in `pyproject.toml`) is **never modified in
 the repository**. `scripts/compute_version.py` queries PyPI's public JSON API
@@ -19,6 +19,15 @@ the repository**. `scripts/compute_version.py` queries PyPI's public JSON API
 version number, and `uv version` applies it only to the ephemeral CI checkout
 before `uv build` runs.
 
+## Formatting
+
+A separate `format` job runs [Prettier](https://prettier.io/) (via
+`npx prettier --check .`) against the repo — predominantly YAML and Markdown
+files — to keep formatting consistent, using Prettier's default rules (no
+project-level config). `build` depends on both `test` and `format` passing.
+Run `npx prettier --write .` locally to auto-fix formatting issues before
+pushing.
+
 ## One-time setup required on PyPI
 
 Trusted Publishing must be configured on the `ibm5250` project at

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/.github/workflows/publish.yml

@@ -28,9 +28,24 @@ jobs:
       - name: Run tests
         run: uv run pytest
 
+  format:
+    name: Format (Prettier)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Check formatting with Prettier
+        run: npx --yes prettier --check .
+
   build:
     name: Build
-    needs: test
+    needs: [test, format]
     runs-on: ubuntu-latest
     outputs:
       version: ${{ steps.version.outputs.version }}

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/.gitignore

@@ -18,3 +18,7 @@ venv/
 
 # Python Caches
 .pytest_cache/
+.ruff_cache/
+
+# Node.js (Prettier tooling)
+node_modules/

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ibm5250
-Version: 0.1.0.dev0
+Version: 0.1.0.dev2
 Summary: IBM 5250 terminal automation library
 License-File: LICENSE
 Requires-Python: >=3.11

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/README.md

@@ -59,11 +59,11 @@ sure `ruff check` and `pytest` both pass.
 Every push runs the test suite in CI. What gets built and published to PyPI
 depends on the branch:
 
-| Branch            | Tested | Built | Published to PyPI | Version format |
-|--------------------|:------:|:-----:|:------------------:|-----------------|
-| `main`             | ✅     | ✅    | ✅ production       | `X.Y.Z` (patch auto-incremented from the latest release) |
-| `develop`          | ✅     | ✅    | ✅ development       | `X.Y.Z.devN` |
-| any other branch   | ✅     | ✅    | ❌ (build artifact only) | n/a |
+| Branch           | Tested | Built |    Published to PyPI     | Version format                                           |
+| ---------------- | :----: | :---: | :----------------------: | -------------------------------------------------------- |
+| `main`           |   ✅   |  ✅   |      ✅ production       | `X.Y.Z` (patch auto-incremented from the latest release) |
+| `develop`        |   ✅   |  ✅   |      ✅ development      | `X.Y.Z.devN`                                             |
+| any other branch |   ✅   |  ✅   | ❌ (build artifact only) | n/a                                                      |
 
 - Contribute by branching off `develop` and opening PRs into `develop`.
   `develop` publishes `.devN` releases so changes can be tried out before

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ibm5250"
-version = "0.1.0.dev0"
+version = "0.1.0.dev2"
 description = "IBM 5250 terminal automation library"
 requires-python = ">=3.11"
 

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/src/ibm5250/connection.py

@@ -52,6 +52,19 @@ _VAR_HDR_OP_HI = 0x08  # TN5250E variable-header opcode byte 0
 _VAR_HDR_OP_LO = 0x2C  # TN5250E variable-header opcode byte 1
 _SAVE_SCREEN_RESP_CC1 = 0x01  # CC1 value in the Save Screen response variable header
 
+# TN5250E header byte 7 (request/response flags). Real emulators set bit 0x40
+# here to signal the Attention (Attn) key -- a header-only INPUT record with no
+# AID and no variable header. Observed on the wire when the PC "Esc" key (mapped
+# to Attn) is pressed: 00 0a 12 a0 00 00 04 40 00 00.
+_TN5250E_ATTN_FLAG = 0x40
+
+# TN5250E header byte 9 operation code (RFC 2877 §4.3). After the workstation
+# sends Attn, the host cancels its outstanding read invite by sending a
+# header-only Cancel-Invite record (opcode 0x0A, no payload). The workstation
+# must acknowledge it by echoing the same Cancel-Invite record back before the
+# host will run its Attention program (e.g. the System Request / Assist menu).
+_TN5250E_OP_CANCEL_INVITE = 0x0A
+
 _MAX_NEG_PASSES = 40  # Maximum Telnet option exchange iterations during negotiation
 
 
@@ -244,13 +257,61 @@ class TN5250Connection:
 
         frame += bytes([TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD])
 
+        self._send_frame(frame, description=f"→ {len(data)} payload bytes: {data.hex()}")
+
+    def _send_frame(self, frame: bytes, *, description: str) -> None:
+        """Send a fully-framed (IAC-EOR terminated) record under the send lock."""
+        if self._sock is None:
+            raise ConnectionError("Not connected")
+        log.debug(description)
         with self._lock:
             try:
                 self._sock.sendall(frame)
             except OSError as exc:
                 raise ConnectionError(f"Send failed: {exc}") from exc
 
-        log.debug("→ %d payload bytes: %s", len(data), data.hex())
+    def send_attn(self) -> None:
+        """Send the Attention (Attn) signal to the host.
+
+        Attn is *not* an AID key. In TN5250E it is a header-only INPUT record
+        whose byte 7 carries the Attn flag (``0x40``) with no variable header
+        and no payload -- exactly what emulators emit when the PC "Esc" key
+        (mapped to Attn) is pressed. On the AS/400 this typically raises the
+        System Request / Assist menu. In basic (non-TN5250E) mode the Attn key
+        is signalled with a Telnet BREAK (RFC 1205).
+        """
+        if not self._tn5250e_active:
+            # Basic TN5250: the Attn key is signalled with a Telnet BREAK.
+            frame = bytes(
+                [
+                    TelnetCmd.INTERPRET_AS_COMMAND,
+                    TelnetCmd.BREAK,
+                    TelnetCmd.INTERPRET_AS_COMMAND,
+                    TelnetCmd.END_OF_RECORD,
+                ]
+            )
+        else:
+            # Header-only INPUT record: byte 7 carries the Attn flag.
+            frame = _build_tn5250e_frame(req_resp=_TN5250E_ATTN_FLAG, opcode=0x00)
+
+        self._send_frame(frame, description="Sending Attn signal")
+
+    def send_cancel_invite_response(self) -> None:
+        """Acknowledge a host Cancel-Invite by echoing it back.
+
+        After the workstation sends Attn, the host replies with a header-only
+        Cancel-Invite record (opcode ``0x0A``, no payload) to cancel its
+        outstanding read invite. The workstation must echo the identical record
+        back; only then does the host run its Attention program (which raises,
+        for example, the System Request / Assist menu). Without this ack the
+        host stalls and never sends the follow-up screen.
+        """
+        if not self._tn5250e_active:
+            return  # cancel-invite handshake only occurs in TN5250E mode
+
+        # Header-only INPUT record: byte 9 opcode = Cancel-Invite, no payload.
+        frame = _build_tn5250e_frame(req_resp=0x00, opcode=_TN5250E_OP_CANCEL_INVITE)
+        self._send_frame(frame, description="Sending Cancel-Invite response")
 
     def send_save_screen_response(self) -> None:
         """Send the TN5250E-level Save Screen acknowledgment.
@@ -261,42 +322,16 @@ class TN5250Connection:
         send).  This is a protocol-level exchange with no 5250 data stream
         payload.
         """
-        if self._sock is None:
-            raise ConnectionError("Not connected")
         if not self._tn5250e_active:
             return  # save/restore handshake only occurs in TN5250E mode
 
-        # 4-byte variable header: [ESC, RESTORE_SCREEN, CC1, CC2.RESET_MDT]
+        # 4-byte variable header: [ESC, RESTORE_SCREEN, CC1, CC2.RESET_MDT].
+        # byte 9 of the fixed header carries the variable-header length.
         var_hdr = bytes(
             [Command.ESC, Command.RESTORE_SCREEN, _SAVE_SCREEN_RESP_CC1, CC2.RESET_MDT]
         )
-        total = _TN5250E_HEADER_LEN + len(var_hdr)  # 14
-        frame = (
-            bytes(
-                [
-                    (total >> 8) & 0xFF,
-                    total & 0xFF,  # record length
-                    _GDS_RECORD_ID_HI,
-                    _GDS_RECORD_ID_LO,  # GDS identifier
-                    0x00,
-                    0x00,  # flags
-                    TN5250EDataType.INPUT,  # data type (matches request)
-                    0x00,
-                    0x00,  # seq / asap-exit
-                    len(var_hdr),  # variable header length = 4
-                ]
-            )
-            + var_hdr
-        )
-        frame = _iac_escape(frame) + bytes(
-            [TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD]
-        )
-        log.debug("Sending Save Screen response")
-        with self._lock:
-            try:
-                self._sock.sendall(frame)
-            except OSError as exc:
-                raise ConnectionError(f"Send failed: {exc}") from exc
+        frame = _build_tn5250e_frame(req_resp=0x00, opcode=len(var_hdr), var_hdr=var_hdr)
+        self._send_frame(frame, description="Sending Save Screen response")
 
     def recv_record(self) -> bytes:
         """Block until a complete record arrives; return the raw 5250 payload."""
@@ -369,6 +404,24 @@ class TN5250Connection:
         """True if TN5250E enhanced mode was successfully negotiated."""
         return self._tn5250e_active
 
+    @property
+    def last_recv_opcode(self) -> int:
+        """Return byte 9 (opcode/var_len) from the last received TN5250E frame.
+
+        Read-poll responses must echo this value back to the server.
+        """
+        return self._last_recv_opcode
+
+    @property
+    def last_recv_was_cancel_invite(self) -> bool:
+        """True if the last received TN5250E record was a Cancel-Invite.
+
+        The host sends a header-only Cancel-Invite (opcode ``0x0A``, no 5250
+        payload) after the workstation presses Attn. It must be acknowledged
+        via :meth:`send_cancel_invite_response`.
+        """
+        return self._last_recv_opcode == _TN5250E_OP_CANCEL_INVITE
+
     # ------------------------------------------------------------------
     # Internal — Telnet negotiation
     # ------------------------------------------------------------------
@@ -698,3 +751,40 @@ class TN5250Connection:
 def _iac_escape(data: bytes) -> bytes:
     """Double any IAC (0xFF) bytes in *data* for safe Telnet transmission."""
     return data.replace(b"\xff", b"\xff\xff")
+
+
+def _build_tn5250e_frame(*, req_resp: int, opcode: int, var_hdr: bytes = b"") -> bytes:
+    """Build an IAC-EOR-terminated TN5250E frame with no 5250 payload.
+
+    Produces the fixed 10-byte header (RFC 2877 §3.3) followed by an optional
+    variable header, IAC-escapes it, and appends the IAC-EOR record terminator.
+    Used for the header-only control records: Attn, Cancel-Invite response and
+    Save Screen response.
+
+    Parameters
+    ----------
+    req_resp:
+        Byte 7 (request/response flags) — e.g. the Attn flag.
+    opcode:
+        Byte 9 (operation code / variable-header length).
+    var_hdr:
+        Optional variable-header bytes appended after the fixed header.
+    """
+    total = _TN5250E_HEADER_LEN + len(var_hdr)
+    header = bytes(
+        [
+            (total >> 8) & 0xFF,
+            total & 0xFF,  # 0-1: logical record length
+            _GDS_RECORD_ID_HI,
+            _GDS_RECORD_ID_LO,  # 2-3: GDS identifier
+            0x00,
+            0x00,  # 4-5: reserved
+            TN5250EDataType.INPUT,  # 6: data type (workstation → host)
+            req_resp,  # 7: request/response flags
+            0x00,  # 8: error recovery
+            opcode,  # 9: opcode / variable-header length
+        ]
+    )
+    return _iac_escape(header + var_hdr) + bytes(
+        [TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD]
+    )

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/src/ibm5250/data-stream-logic.md

@@ -44,16 +44,16 @@ The **DataStreamParser** takes a raw 5250 payload (one record from the connectio
 
 Every 5250 record starts with a **command byte**:
 
-| Command | Meaning |
-|---------|---------|
-| `0x11` (Write to Display) | Main screen update — followed by CC1, CC2, then orders/data |
-| `0x02` (Save Screen) | Server wants to save the current screen (same format as WTD) |
-| `0x12` (Restore Screen) | Server wants to restore a previously saved screen |
-| `0x04` (ESC) | Escape prefix — next byte is the real command (WTD, WSF, Save, Restore) |
-| `0xF3` (Write Structured Field) | Carries structured data like Query commands |
-| `0x42/0x52/0x72/0x62` | Read commands — server asks client to send back screen/field data |
-| `0x21` (Write Error Code) | Display error on status line |
-| `0x50` (Clear Format Table) | Discard field definitions |
+| Command                         | Meaning                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| `0x11` (Write to Display)       | Main screen update — followed by CC1, CC2, then orders/data             |
+| `0x02` (Save Screen)            | Server wants to save the current screen (same format as WTD)            |
+| `0x12` (Restore Screen)         | Server wants to restore a previously saved screen                       |
+| `0x04` (ESC)                    | Escape prefix — next byte is the real command (WTD, WSF, Save, Restore) |
+| `0xF3` (Write Structured Field) | Carries structured data like Query commands                             |
+| `0x42/0x52/0x72/0x62`           | Read commands — server asks client to send back screen/field data       |
+| `0x21` (Write Error Code)       | Display error on status line                                            |
+| `0x50` (Clear Format Table)     | Discard field definitions                                               |
 
 ### Control Characters (CC1 / CC2)
 
@@ -73,18 +73,18 @@ After a WTD or Save Screen command, two bytes control screen-level behavior:
 
 After the command + CC bytes, the rest of the record is a stream of **orders** intermixed with **data bytes**:
 
-| Order | What it does |
-|-------|-------------|
-| **SBA** — Set Buffer Address (`0x11`) + row + col | Move the write position to a specific screen cell |
-| **SF** — Start Field (`0x1D`) + FFW [+ FCWs] | Define a new input/output field at the current position. The FFW (Field Format Word, 2 bytes) defines field type — bypass/input, numeric, non-display, etc. Optional FCW (Field Control Word) pairs add behaviours like mandatory entry, right-adjust, or monocase. |
-| **MF** — Modify Field (`0x2C`) + FFW [+ FCWs] | Modify an existing field's attributes |
-| **IC** — Insert Cursor (`0x13`) | Place the cursor at the current position |
-| **MC** — Move Cursor (`0x14`) + row + col | Move the cursor to a specific position |
-| **RA** — Repeat to Address (`0x3C`) + row + col + char | Repeat a character from current position up to the target |
-| **EA** — Erase to Address (`0x12`) + row + col | Erase (fill with nulls) from current position to target |
-| **TD** — Transparent Data (`0x10`) + length + data | Write raw bytes (transparent, no order interpretation) |
-| **SA** — Set Attribute (`0x28`) + type + value | Set a display attribute (colour, underline, etc.) |
-| **SOH** — Start of Header (`0x01`) + length + data | Metadata block, skipped |
+| Order                                                  | What it does                                                                                                                                                                                                                                                        |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **SBA** — Set Buffer Address (`0x11`) + row + col      | Move the write position to a specific screen cell                                                                                                                                                                                                                   |
+| **SF** — Start Field (`0x1D`) + FFW [+ FCWs]           | Define a new input/output field at the current position. The FFW (Field Format Word, 2 bytes) defines field type — bypass/input, numeric, non-display, etc. Optional FCW (Field Control Word) pairs add behaviours like mandatory entry, right-adjust, or monocase. |
+| **MF** — Modify Field (`0x2C`) + FFW [+ FCWs]          | Modify an existing field's attributes                                                                                                                                                                                                                               |
+| **IC** — Insert Cursor (`0x13`)                        | Place the cursor at the current position                                                                                                                                                                                                                            |
+| **MC** — Move Cursor (`0x14`) + row + col              | Move the cursor to a specific position                                                                                                                                                                                                                              |
+| **RA** — Repeat to Address (`0x3C`) + row + col + char | Repeat a character from current position up to the target                                                                                                                                                                                                           |
+| **EA** — Erase to Address (`0x12`) + row + col         | Erase (fill with nulls) from current position to target                                                                                                                                                                                                             |
+| **TD** — Transparent Data (`0x10`) + length + data     | Write raw bytes (transparent, no order interpretation)                                                                                                                                                                                                              |
+| **SA** — Set Attribute (`0x28`) + type + value         | Set a display attribute (colour, underline, etc.)                                                                                                                                                                                                                   |
+| **SOH** — Start of Header (`0x01`) + length + data     | Metadata block, skipped                                                                                                                                                                                                                                             |
 
 Anything that isn't a recognized order byte is treated as **EBCDIC (Extended Binary Coded Decimal Interchange Code)** character data and written sequentially into the screen buffer.
 
@@ -99,6 +99,7 @@ When the server sends a WSF Query command, the parser emits a **QUERY** event. T
 ### Events Produced
 
 Each order/data run becomes a `DSEvent` with a type like:
+
 - `CLEAR_SCREEN` — wipe the buffer
 - `RESIZE_SCREEN` — change dimensions
 - `SET_POS` — move write cursor

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/src/ibm5250/terminal.py

@@ -217,6 +217,20 @@ class Terminal:
         """Send an AID key by name, e.g. ``"Enter"``, ``"F3"``, ``"Clear"``."""
         self.send_key(AID.from_name(name), wait=wait)
 
+    def send_attn(self, *, wait: bool = True) -> None:
+        """Send the Attention (Attn) signal to the host.
+
+        Attn is a protocol-level attention indication -- *not* an AID key -- and
+        is what 5250 emulators send for the PC "Esc" key. On the AS/400 it
+        typically raises the System Request / Assist menu. By default this
+        blocks until the host responds; pass ``wait=False`` to return
+        immediately after sending.
+        """
+        self._conn.send_attn()
+        self._screen._keyboard_locked = True
+        if wait:
+            self._recv_and_apply()
+
     def type_into(
         self,
         field: Field | FieldProxy,
@@ -517,6 +531,14 @@ class Terminal:
 
     def _recv_and_apply(self) -> None:
         received_payload = self._conn.recv_record()
+        # A header-only Cancel-Invite (no 5250 payload) is the host's reply to
+        # our Attn: it cancels the outstanding read invite. We must echo it back
+        # to let the host run its Attention program (e.g. the Assist menu);
+        # otherwise the host stalls and never sends the follow-up screen.
+        if not received_payload and self._conn.last_recv_was_cancel_invite:
+            log.debug("Received Cancel-Invite; echoing acknowledgment")
+            self._conn.send_cancel_invite_response()
+            return
         parsed_events = list(self._parser.parse(received_payload))
         # If this record has screen content, the pending save is no longer back-to-back
         for ev in parsed_events:

{ibm5250-0.1.0.dev0 → ibm5250-0.1.0.dev2}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "ibm5250"
-version = "0.1.0.dev0"
+version = "0.1.0.dev2"
 source = { editable = "." }
 
 [package.dev-dependencies]