Pexpect

Warnings

• breaking pexpect.spawn is not available on Windows — it requires the pty module which only exists on Unix. Importing pexpect works, but calling pexpect.spawn() raises ImportError or OSError on Windows.
  Fix: On Windows use pexpect.popen_spawn.PopenSpawn instead. PopenSpawn lacks interactive TTY features but works cross-platform.
• breaking The async= parameter was renamed to async_= as async became a Python keyword in 3.7. Using async= raises SyntaxError on Python 3.7+.
  Fix: Replace child.expect('pattern', async=True) with child.expect('pattern', async_=True)
• gotcha Without encoding='utf-8', child.before and child.after return bytes, not str. Most tutorials show str patterns but they fail with bytes. Always specify encoding at spawn time.
  Fix: Always pass encoding='utf-8': pexpect.spawn('cmd', encoding='utf-8'). Then expect() patterns and before/after are strings.
• gotcha pexpect.TIMEOUT and pexpect.EOF are classes, not exceptions. They are passed to expect() as patterns (expect([pexpect.EOF, pexpect.TIMEOUT])), not caught with except. Catching them with except does not work as expected.
  Fix: Pass them as patterns in the expect list and check the returned index: index = child.expect(['pattern', pexpect.EOF, pexpect.TIMEOUT]); if index == 2: handle_timeout()
• gotcha child.before contains output BEFORE the matched pattern. child.after contains the matched pattern itself. Output AFTER the match is buffered internally. Accessing child.before after EOF gives all remaining output.
  Fix: To get all output: child.expect(pexpect.EOF); print(child.before) captures everything before EOF.
• gotcha pexpect.screen and pexpect.ANSI modules are deprecated. Do not import from them.
  Fix: Use the pyte package for terminal emulation instead.

Install

• pip install pexpect Standard

Imports

• pexpect.spawn

  import pexpect
  
  # Unix/Linux only — uses pty module
  child = pexpect.spawn('ssh user@host', encoding='utf-8', timeout=30)
  
  # expect() returns index of matched pattern (or raises TIMEOUT/EOF)
  index = child.expect(['password:', 'yes/no', pexpect.EOF, pexpect.TIMEOUT])
  
  if index == 0:
      child.sendline('mysecretpassword')
  elif index == 1:
      child.sendline('yes')
  elif index == 2:
      print('Connection closed (EOF)')
  elif index == 3:
      raise TimeoutError('SSH timed out')
  
  # Wait for shell prompt
  child.expect(r'\$')
  child.sendline('ls -la')
  child.expect(r'\$')
  print(child.before)

  pexpect.spawn only works on Unix/Linux. On Windows use pexpect.PopenSpawn. Pass encoding='utf-8' to get str instead of bytes from before/after. TIMEOUT and EOF are passed to expect() as patterns, not caught as exceptions.

Quickstart

Always pass encoding='utf-8'. expect() returns index. Use PopenSpawn on Windows.

import pexpect

# Basic spawn with string encoding (recommended)
child = pexpect.spawn(
    'python3 -c "name = input(\"Name: \"); print(f\"Hello {name}!\")"',
    encoding='utf-8',
    timeout=10
)

# expect() waits for a pattern, returns the index of the match
child.expect('Name: ')
child.sendline('Alice')
child.expect(pexpect.EOF)   # wait for program to finish
print(child.before)          # 'Hello Alice!\r\n'

# Multi-pattern expect
index = child.expect(['pattern1', 'pattern2', pexpect.EOF, pexpect.TIMEOUT])
# index 0 = matched 'pattern1'
# index 1 = matched 'pattern2'
# index 2 = EOF (process ended)
# index 3 = timeout

# Windows: use PopenSpawn (no pty, no interactive echo)
from pexpect import popen_spawn
child = popen_spawn.PopenSpawn('python --version', encoding='utf-8')
child.expect(pexpect.EOF)
print(child.before)