stitch-pty

stitch-pty is a high-performance, cross-platform pseudo-terminal (PTY) library for Python, written in Rust with PyO3 bindings. It provides true PTY semantics on Linux, macOS, and Windows, with a built-in VT100/VT220/xterm-compatible terminal emulator for rendering ANSI escape sequences with scrollback history.

Why stitch-pty?

Table of Contents

• Why stitch-pty?
• Table of Contents
• Quick Start
• Installation
• API Reference
  • Core Functions
  • ExitStatus
  • PtySession
  • PtyMaster
  • PtyChild
  • TerminalState
  • Winsize
  • Error Types
• Architecture
  • High-Level Overview
  • PTY Backend
    • POSIX (platform_unix.rs)
    • Windows (platform_windows.rs)
  • Terminal Emulation (terminal/)
  • GIL Management Strategy
  • Memory Safety
• Examples
  • Simple Command Execution
  • Interactive Shell
  • pexpect-Style Expect
  • Raw PTY (No Child)
  • PySide6 Terminal Emulator (GUI)
• Building from Source
  • Prerequisites
  • Development Workflow
  • Cross-Compilation
• Source Projects & Dependencies
  • portable-pty — PTY Abstraction Layer
  • pyte — Terminal Emulation
  • vte — ANSI Escape Sequence Parser
  • Dependency Summary
• Platform Support
• License

Quick Start

import asyncio
from stitch_pty import spawn

async def main():
    # Spawn a shell in a real PTY
    session = await spawn("bash", ["-i"])

    # Read output (auto-fed into the terminal emulator)
    data = await session.read(4096)
    print(session.display)          # visible screen → list[str]
    print(session.scrollback)       # scrollback history → list[str]
    print(session.full_display)     # history + visible → list[str]

    # Write to the PTY
    await session.write(b"echo hello from stitch-pty\n")

    # Resize the terminal
    session.resize(50, 120)

    # Graceful shutdown
    await session.terminate(5.0)

asyncio.run(main())

Installation

pip install stitch-pty

Pre-built wheels are available for:

Requirements: Python ≥ 3.12

API Reference

Core Functions

spawn(program, args=None, env=None, winsize=None, scrollback=1000, raw_output_cap=1_048_576, cwd=None) → PtySession

Spawn a program in a PTY and return a session handle.

Returns: PtySession — a combined PTY I/O + child process manager with integrated terminal emulation.

Example:

session = await spawn("python3", ["-c", "print('hello')"])
output = await session.interact()
print(output.decode())  # b"hello\n"

poll_events() → list[tuple[str, object]] (PtySession method)

Drain the ordered low-frequency event log for this frame — one FFI crossing instead of polling each signal separately. Tags: ("bell", None) (also consumes take_bell()), ("title", str), ("icon", str), ("cwd", str), ("altscreen", bool), ("scrollback_grew", int).

for tag, payload in session.poll_events():
    if tag == "bell":
        flash_tab_dot()
    elif tag == "title":
        set_tab_title(payload)

open_pty(winsize=None) → PtyMaster

Async. Opens a PTY pair without spawning a child process.

Returns: PtyMaster — raw PTY I/O handle (no terminal emulation, no child management).

Example:

pty = await open_pty(Winsize(24, 80, 0, 0))
data = await pty.read(4096)
await pty.write(b"hello\n")

ExitStatus

Frozen dataclass returned by await wait() (or None if the child was already reaped).

from stitch_pty import ExitStatus

status = await session.wait()
if status:
    print(f"PID {status.pid} exited with code {status.exit_code}")

PtySession

The primary interface for most use cases. Combines PTY I/O, child process management, and terminal emulation.

Properties:

Context Manager:

async with spawn("bash", ["-i"]) as session:
    await session.write(b"echo hello\n")
    output = await session.interact()
# session.terminate(2.0) called automatically on exit

PtyMaster

Raw PTY I/O without terminal emulation or child management.

PtyChild

Child process management.

TerminalState

VT100/VT220/xterm-compatible terminal emulation with scrollback.

Styled Viewport Cell Layout:

# Each cell: (text, fg, bg, attrs_bitmask)
# fg/bg formats: "default", ANSI name ("red", "brightblue"), or 6-hex RGB ("ff0000")
# attrs bitmask: bit 0=bold, 1=dim, 2=italics, 3=underscore,
#                4=blink, 5=reverse, 6=hidden, 7=strikethrough

Winsize

Terminal window dimensions.

ws = Winsize(50, 120, 0, 0)

Error Types

EOF note: after the child exits, read()/read_timeout() return b"" instead of raising; natively the condition is PtyErrorKind::Eof, surfaced as an OSError with errno == 0 and a stable kind == "eof" attribute.

Architecture

High-Level Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Python Layer                            │
│  ┌──────────────┐  ┌────────────────────────────────────────┐   │
│  │ PtySession   │  │ TerminalState (pyte_rs)                │   │
│  │ (Python)     │  │ ├─ Parser (ANSI stream → Screen)       │   │
│  │              │  │ ├─ HistoryScreen (scrollback buffer)   │   │
│  │              │  │ └─ Screen (Char grid, cursor, SGR)     │   │
│  └──────┬───────┘  └────────────────────────────────────────┘   │
│         │                                                       │
│  ┌──────┴──────────────────────────────────────────────────┐    │
│  │         stitch_pty._core (PyO3 / Rust)                  │    │
│  │  ┌──────────────────────────────────────────────────┐   │    │
│  │  │     Platform Abstraction Layer                   │   │    │
│  │  │  ┌──────────────────┐  ┌──────────────────────┐  │   │    │
│  │  │  │  POSIX Backend   │  │  Windows Backend     │  │   │    │
│  │  │  │  ── openpty()    │  │  ── ConPTY (dyn load)│  │   │    │
│  │  │  │  ── fork()       │  │  ── NamedPipe (async)│  │   │    │
│  │  │  │  ── AsyncFd      │  │  ── CreateProcessW   │  │   │    │
│  │  │  │  ── waitpid()    │  │  ── GetExitCodeProc  │  │   │    │
│  │  │  └──────────────────┘  └──────────────────────┘  │   │    │
│  │  └──────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

PTY Backend

POSIX (platform_unix.rs)

Async I/O Pattern:

loop {
    let mut guard = self.async_fd.readable().await?;
    match guard.try_io(|inner| {
        libc::read(*inner.get_ref(), buf.as_mut_ptr(), buf.len())
    }) {
        Ok(result) => return result,
        Err(_would_block) => continue,
    }
}

Windows (platform_windows.rs)

Send-Safe Windows Types:

SendSyncHandle wraps HANDLE with Send + Sync + Clone, allowing Windows non-Send types to cross .await boundaries. All non-Send locals (STARTUPINFOEXW, PROCESS_INFORMATION, attribute list) are scoped to a block ending before the first .await after CreateProcessW.

Terminal Emulation (terminal/)

Embedded from pyte_rs. Provides VT100/VT220/xterm-compatible rendering.

ANSI Parser (ansi_parser.rs)

ECMA-48 state machine with 14 states:

Parser Limits: Max 32 params (sub-param groups), 2 intermediates, 16 OSC params, 1024 OSC bytes, 4-byte UTF-8 partial buffer.

Screen Buffer (screen.rs)

Scrollback (history.rs)

GIL Management Strategy

PyO3 native async automatically releases the GIL at .await:

Python call (GIL held)
    → future_into_py (GIL released)
    → tokio I/O await (GIL released)
    → completion: GIL reacquired
    → Rust value → Python object conversion

GIL is released across .await: async reads/writes run on tokio threads without the GIL; it is reacquired to hand results back to Python.

GIL is held by:

1. Converting Vec<u8> → PyBytes
2. Raising PyErr exceptions
3. Synchronous TerminalState emulator calls (feed, display, styled_viewport, …) — parsing and screen-building run under the GIL

Memory Safety

POSIX ownership:

PtyPair (owns master_fd + slave_fd)
    ├── master_fd → UnixPtyMaster (via mem::forget)
    │   └── Drop: close(fd)
    └── slave_fd → child process (via fork)
        └── Child closes on exec, parent closes after fork

Windows ownership:

WinPtyBackend (owns HPCON + NamedPipeServer handles)
    ├── input_pipe → NamedPipeServer (Drop: drop)
    ├── output_pipe → NamedPipeServer (Drop: drop)
    └── conpty → ConPTY (Drop: ClosePseudoConsole)

RAII guarantees:

Examples

Simple Command Execution

import asyncio
from stitch_pty import spawn

async def main():
    session = await spawn("echo", ["hello", "world"])
    output = await session.interact()
    print(output.decode())  # b"hello world\n"

asyncio.run(main())

Interactive Shell

import asyncio
from stitch_pty import spawn

async def main():
    session = await spawn("bash", ["-i"])

    # Send a command
    await session.write(b"ls -la\n")

    # Wait for output
    output = await session.interact()
    print(output.decode())

    # Cleanup
    await session.terminate()

asyncio.run(main())

pexpect-Style Expect

import asyncio
from stitch_pty import spawn

async def main():
    import re
    session = await spawn("bash", ["-i"])

    # Wait for a prompt (single literal → index 0)
    prompt = await session.expect(b"$ ", timeout=10.0)
    print(f"Got: {bytes(prompt).decode()}")

    # Send command
    await session.write(b"uname -a\n")

    # Wait for whichever comes first: output line or an error banner.
    # Lists match in list order; regex hits carry a match object.
    output = await session.expect(
        [re.compile(rb"Linux .*"), b"command not found"], timeout=5.0
    )
    print(f"Output [{output.index}]: {output.buffer.decode()}")
    if output.match is not None:
        print(f"Matched: {output.match.group(0).decode()}")

    await session.terminate()

asyncio.run(main())

expect() returns an ExpectResult(index, match, buffer): index is the winning pattern's position, match is the regex match (or None for literal hits), and buffer holds everything read so far. Timeouts and EOF raise TimeoutError with the bytes seen attached as .buffer. Legacy call sites keep working: b"…" in result, result == b"…", and bytes(result) all read from buffer — only .decode() needs spelling out now.

Raw PTY (No Child)

import asyncio
from stitch_pty import open_pty, Winsize

async def main():
    pty = await open_pty(Winsize(24, 80, 0, 0))

    # Write and read raw bytes
    await pty.write(b"hello from raw PTY\n")
    data = await pty.read(4096)
    print(data.decode())

asyncio.run(main())

PySide6 Terminal Emulator (GUI)

A full terminal emulator with real-time rendering, keyboard input, resize handling, and styled viewport:

pip install PySide6 stitch-pty
python examples/terminal_emulator.py
python examples/terminal_emulator.py --cmd "whoami"
python examples/terminal_emulator.py --rows 30 --cols 100

Key features demonstrated:

• Async PTY + Qt event loop integration (background thread)
• Real-time styled rendering via styled_viewport() with HTML
• Cursor position tracking via absolute_cursor()
• Keyboard input forwarding with Ctrl+key → ANSI sequences
• Window resize forwarding (rate-limited during drag)
• Graceful shutdown on window close

Building from Source

stitch-pty is designed to be used both as a standalone Rust crate and as a Python extension. The Python bindings are decoupled and gated behind the python feature flag.

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install maturin
pip install maturin

Building as a Rust Crate

To use stitch-pty in a Rust project, add it to your Cargo.toml. The Python bindings are disabled by default, allowing for a pure Rust build without PyO3 overhead.

[dependencies]
stitch-pty = "0.9.0"

To build and test the pure Rust code locally:

cargo build
cargo test

Building as a Python Extension

The Python extension is built using maturin. The pyproject.toml is configured to automatically enable the python feature when building wheels.

# Clone
git clone https://github.com/opticsWolf/stitch-pty.git
cd stitch-pty

# Development build (fast, unoptimized)
maturin develop

# Alternatively, using uv to test:
uv run --extra dev pytest

# Run Python tests (platform-specific tests auto-skip)
pytest tests/ -v

# Type check
mypy python/stitch_pty/

# Lint
ruff check .

# Production wheel
maturin build --release

Cross-Compilation

# Linux ARM64 from x86_64 host
maturin build --release --target aarch64-unknown-linux-gnu

# macOS universal2
maturin build --release --target universal2-apple-darwin

# Windows from Linux (requires cross toolchain)
maturin build --release --target x86_64-pc-windows-gnu

Source Projects & Dependencies

stitch-pty is built on three foundational open-source projects. Each contributed significant portions of code, architecture patterns, and design decisions that were adapted, extended, or embedded into this project.

1. portable-pty — PTY Abstraction Layer

What was taken:

• ChildKiller trait — deadlock-free kill/wait separation pattern (cloneable killer split from ChildBackend to avoid blocking .wait threads)
• ExitStatus / ProcessExit structs — unified exit code + signal representation
• PtySize → Winsize — window size struct with rows/cols/pixels
• close_random_fds() — macOS Big Sur / Linux FD leak prevention (closes all FDs > 2 via /dev/fd listing)
• ArgvQuote algorithm — proper Windows command-line quoting (backslash/quote escaping)
• SafeAttributeList pattern — Win32 PROC_THREAD_ATTRIBUTE_LIST lifecycle management (Initialize → Update → Delete) for ConPTY attachment
• ProcessSignaller — cross-platform signal delivery abstraction

What changed:

• Rewritten for tokio async (portable-pty uses blocking I/O)
• Replaced nix 0.28 → nix 0.31 with additional features (signal, poll, ioctl)
• Replaced winapi → windows crate (0.62, modern MSFT bindings)
• Replaced anyhow → thiserror for zero-cost error propagation
• Added Tokio NamedPipes for Windows async I/O (portable-pty uses spawn_blocking)
• Added dynamic ConPTY loading via GetProcAddress for graceful fallback
• GIL management for Python integration

2. pyte — Terminal Emulation

What was taken:

• Screen — 2D Char grid, cursor management, tab stops, dirty tracking
• Char cell — data, fg/bg colors, bold/dim/italics/underscore/blink/reverse/hidden/strikethrough
• Cursor — position, attributes, save/restore stack
• Margins — scroll region top/bottom
• CursorStyle — block/underline/beam variants
• SGR color handling — 8 ANSI, 8 aixterm bright, 256-color palette, 24-bit RGB
• Mode management — public ANSI (IRM, LNM) + private DEC (DECOM, DECAWM, DECCOLM, etc.)
• Character set designation — G0/G1 with DEC Special line drawing map
• OSC title/icon dispatch — OSC 0/1/2; icon name and window title
• CSI cursor movement — CUU/CUD/CUF/CUB/CUP/CNL/CPL/CHA
• CSI erase — ED (display), EL (line), DC (characters), DL/IL (lines)
• Unicode handling — unicode-width for width-1/width-2 chars, combining marks
• Kitty Keyboard Protocol — mode push/pop/replace
• Device status — DA0/DA1 identification, cursor position report

What changed:

• Ported from Python to Rust with PyO3 bindings
• Added HistoryScreen — scrollback buffer (not in upstream pyte)
• Added styled_viewport() — full buffer as (text, fg, bg, attrs_bitmask) cells
• Added total_lines() and absolute_cursor() for scroll-aware positioning
• Added unicode-segmentation for proper grapheme boundary handling
• SGR subparameter parsing (: as param separator) — differs from vte crate
• Color stored as hex strings ("ff0000") instead of RGB tuples for Python serialization

3. vte — ANSI Escape Sequence Parser

What was taken:

• ECMA-48 state machine — 14-state ANSI parser (Ground, CsiEntry, CsiParam, CsiIntermediate, CsiIgnore, OscString, DcsEntry, DcsPassthrough, Escape, EscapeIntermediate)
• Parser struct — state, intermediates, params, UTF-8 partial buffer, OSC raw buffer
• Params struct — sub-parameter groups with MAX_PARAMS = 32 limit
• Perform trait — print, execute, hook, put, unhook, osc_dispatch, csi_dispatch, esc_dispatch, terminated
• UTF-8 handling — partial byte buffer (4 bytes), invalid byte replacement with \u{FFFD}
• OSC handling — MAX_OSC_PARAMS = 16, MAX_OSC_RAW = 1024, BEL/ST termination
• DCS passthrough — hook/passthrough/unhook state transitions
• C0/C1 control handling — C0 (\x00–\x1f), C1 (\x80–\x9f)
• Parameter parsing — : subparameter separator, ; param separator, overflow saturation

What changed:

• Embedded directly as source (not a crate dependency) — allows custom Perform impl
• Perform trait extended with esc_dispatch for legacy ESC sequences
• CSI parameter parsing: : treated as param separator (not subparam like upstream vte)
• Added escape.rs designator constants (RIS, IND, NEL, HTS, etc.)
• Added charsets.rs DEC Special line drawing map
• Added control.rs C0/C1 constants
• Added extensive unit tests for parser edge cases (overflow, reset, partial UTF-8)

Dependency Summary

Note: stitch-pty is licensed MIT OR Apache-2.0. The LGPL-3.0 dependency (pyte) is satisfied by the "exception to section 3" clause: the terminal emulation is embedded as a module, not linked as a library. The MIT and Apache-2.0 licenses are compatible with stitch-pty's dual licensing.

Platform Support

ExitStatus.core_dumped exists on all platforms but is always False (reserved for future WCOREDUMP reporting — the reaper currently discards the core flag).

Platform Differences

License

MIT OR Apache-2.0