ptylink

Modern process interaction library for Python — expect-style automation with PTY support.

Drop-in replacement for pexpect with full type annotations, native async/await, and zero dependencies.

Why ptylink?

Installation

pip install ptylink

Requires Python 3.10+.

Quick Start

import ptylink

with ptylink.spawn("python3") as child:
    child.expect(">>> ")
    child.sendline("print(42)")
    child.expect("42")
    print(child.before)  # text before the match

Context Manager

from ptylink import Spawn

with Spawn("ssh user@host") as child:
    child.expect("password:")
    child.sendline("secret")
    child.expect(r"\$ ")
    child.sendline("ls")
    child.expect(r"\$ ")
    print(child.before)

Async Usage

import asyncio
from ptylink import AsyncSpawn

async def main():
    async with AsyncSpawn("python3") as child:
        await child.expect(">>> ")
        await child.sendline("1 + 1")
        await child.expect("2")

asyncio.run(main())

Pipe-Based (No PTY)

For environments without PTY support (e.g. Windows):

from ptylink import PopenSpawn

with PopenSpawn("echo hello") as child:
    child.expect("hello")

High-Level run()

from ptylink import run

# Simple command
output = run("ls -la")

# With exit status
output, status = run("make test", withexitstatus=True)

# Interactive with events
output = run(
    "sudo apt install foo",
    events={"password:": "secret\n"},
)

SSH Sessions

from ptylink import SSHSession

with SSHSession("server.example.com", username="admin") as ssh:
    ssh.login(password="secret")
    output = ssh.run("uname -a")
    print(output)

Pattern Matching

import re
from ptylink import Spawn, EOF_TYPE, TIMEOUT_TYPE

with Spawn("some_program") as child:
    # String patterns (auto-escaped)
    child.expect("login:")

    # Regex patterns
    child.expect(re.compile(r"[\$#] "))

    # Multiple patterns — returns index of match
    idx = child.expect_list(["error", "success", EOF_TYPE])
    if idx == 0:
        print("Error:", child.after)
    elif idx == 1:
        print("Success!")
    elif idx == 2:
        print("Process ended")

API Reference

Classes and Functions

• Spawn(command, *, timeout=30, encoding='utf-8', env=None, cwd=None) — PTY-based process interaction
• spawn(command, *, timeout=30, encoding='utf-8') — Factory function; returns a Spawn instance
• AsyncSpawn(command, ...) — Async version of Spawn
• PopenSpawn(command, ...) — Pipe-based (no PTY) process interaction
• SSHSession(server, *, username=None, port=22, password=None) — SSH session helper

Spawn Methods

Attributes

• before — Text before the last match
• after — Text of the last match
• match — Match object or string from last expect

Exceptions

• PtylinkError — Base exception
• Timeout — Expect timed out
• EOF — Process closed output
• ExitStatus — Process exited with non-zero status

Sentinels

• EOF_TYPE — Use in pattern lists to match EOF without raising
• TIMEOUT_TYPE — Use in pattern lists to match timeout without raising

ANSI Utilities

from ptylink import strip_ansi, has_ansi

clean = strip_ansi("\x1b[31mred text\x1b[0m")  # "red text"
has_ansi("\x1b[1mbold\x1b[0m")  # True

Migrating from tether

This package was previously named tether. To upgrade:

pip uninstall tether
pip install ptylink

Then update your imports and any exception references:

# Before
import tether
from tether import TetherError

# After
import ptylink
from ptylink import PtylinkError

All other APIs are identical.

pexpect Migration Guide

Zero-Change Migration

# Before
import pexpect

# After — just change the import
import ptylink.compat as pexpect

All pexpect names are available: spawn, run, EOF, TIMEOUT, pxssh.

Manual Migration

Breaking Changes

• EOF and TIMEOUT are sentinel types, not exception classes. Use EOF_TYPE and TIMEOUT_TYPE in pattern lists.
• async_=True parameter is removed. Use AsyncSpawn instead.
• before attribute no longer contains leaked sendline() echo text.

Fixes from pexpect

• #821 — before attribute no longer contains echoed sendline() input
• #817 — No ResourceWarning from os.fork() on Python 3.12+
• #677 — No deprecated @asyncio.coroutine usage; native async def throughout

Benchmarks

License

ISC