Typing Stubs for pexpect

Warnings

• breaking Type changes in pexpect.spawn().before from 'str' to 'AnyStr | None' in types-pexpect 4.9.0 stubs. If your code previously assumed `pexpect.spawn().before` would always be `str` and directly called `.decode()` without checking for `None` or handling `bytes`, type checkers will now flag this as an error.
  Fix: Explicitly check if `child.before` is `None` before attempting to decode it, and handle the possibility of it being `bytes` by calling `.decode()`.
• gotcha Installing `types-pexpect` does not install the `pexpect` runtime library itself. You must install `pexpect` separately for your code to run, as `types-pexpect` only provides type information.
  Fix: Always ensure both `pexpect` and `types-pexpect` are installed via `pip install pexpect types-pexpect`.
• gotcha Regular expression matching for end-of-line (`$` or `\n`) in `expect()` can be tricky due to how pseudo-TTYs handle line endings (typically `\r\n`). `$` often matches the end of the *current buffer*, not a logical line end, because Pexpect reads character by character.
  Fix: Explicitly expect `\r\n` for line endings. For general stream matching, avoid `$` for end-of-line and understand that regular expressions operate on the incrementally read buffer.
• gotcha A common 'timing issue with send() and sendline()' exists when interacting with applications that prompt for passwords. If `sendline()` is called immediately after `expect()` for a password prompt, the password might be echoed before the child application turns off echo.
  Fix: Pexpect 4.0+ mitigates this with a default delay. If issues persist, consider adding a small `time.sleep()` before `sendline()`, or adjust the `delaybeforesend` attribute of the `spawn` object.

Install

• pip install pexpect types-pexpect Install pexpect and its typing stubs

Imports

• spawn

  import pexpect
  child = pexpect.spawn('command')

  types-pexpect is a stub-only package. You import symbols directly from the 'pexpect' library, and type checkers will automatically use the installed stubs for static analysis.
• EOF

  import pexpect
  child.expect(pexpect.EOF)

  types-pexpect does not contain runtime code; it only provides type information for existing pexpect symbols.

Quickstart

This quickstart demonstrates a basic usage of pexpect with type checking. First, ensure both `pexpect` and `types-pexpect` are installed. The example spawns a simple Python script, captures its output, and decodes it. A type checker like MyPy can then verify the type correctness, leveraging the `types-pexpect` stubs. For instance, the `child.before` attribute's type (AnyStr | None) is correctly recognized.

import pexpect
import os

def run_and_check_type() -> str:
    # Simulate a command that prints to stdout
    script_path = 'temp_script.py'
    with open(script_path, 'w') as f:
        f.write("import sys; sys.stdout.write('hello world\n')")
    
    try:
        child = pexpect.spawn(f'python {script_path}')
        child.expect('hello world\r\n') # pexpect typically sees \r\n
        # In pexpect 4.9, 'before' is AnyStr | None
        # You need to explicitly decode if you expect a str and were expecting bytes
        # The types-pexpect 4.9.0 stubs reflect this (Issue #11382 on typeshed).
        output_bytes = child.before
        if output_bytes is None:
            return ''
        return output_bytes.decode('utf-8')

    except pexpect.exceptions.TIMEOUT:
        print('TIMEOUT exception')
        return ''
    except pexpect.exceptions.EOF:
        print('EOF exception')
        return ''
    finally:
        if os.path.exists(script_path):
            os.remove(script_path)

if __name__ == '__main__':
    result = run_and_check_type()
    print(f"Captured output: {result}")

    # To run type checking, save this as `your_script.py`
    # Then run: `mypy your_script.py` after installing `mypy`
    # Expected output: No issues found