Pyte Terminal Emulator

0.8.2 · active · verified Fri Apr 17

Pyte is a simple, VTXXX-compatible terminal emulator library for Python. It processes ANSI escape sequences and maintains the state of a terminal screen, allowing programmatic interaction with terminal output without a GUI. The current version is 0.8.2, and it has a moderate release cadence, with updates typically for bug fixes and minor features.

Common errors

```
TypeError: a bytes-like object is required, not 'str'
```
cause Attempting to feed a string directly to `pyte.Stream.feed()` instead of a bytes object.

fix Encode the string to bytes before feeding, e.g., `stream.feed('text'.encode())` or use a bytes literal `stream.feed(b'text')`.
```
TypeError: Screen.__init__() got an unexpected keyword argument 'cols'
```
cause Using the old `cols` parameter name for the `pyte.Screen` constructor after version 0.6.0.

fix Change `cols` to `columns` in the `Screen` constructor, e.g., `pyte.Screen(columns=80, rows=24)`.
```
AttributeError: 'pyte.Screen' object has no attribute 'cursor_x'
```
cause Accessing cursor position attributes (e.g., `cursor_x`, `cursor_y`) directly on the `Screen` object. The cursor is an object accessible via `screen.cursor`.

fix Access cursor attributes via the `cursor` object: `screen.cursor.x`, `screen.cursor.y`.

Warnings

breaking The constructor for `pyte.Screen` changed its parameter names in version 0.6.0. The `cols` parameter was renamed to `columns`.
Fix: Update `Screen` instantiation: `Screen(columns=80, rows=24)` instead of `Screen(cols=80, rows=24)`.
gotcha The `pyte.Stream.feed()` method strictly requires a `bytes`-like object. Passing a plain string (str) will result in a `TypeError`.
Fix: Ensure all input to `feed()` is encoded to bytes, for example, `stream.feed(b'some text')` or `stream.feed('some text'.encode('utf-8'))`.
gotcha Pyte aims for VTXXX compatibility. Feeding non-standard or malformed ANSI escape sequences might lead to an inconsistent or unexpected screen state without raising an explicit error, making debugging difficult.
Fix: Validate input sequences if possible, or be prepared to handle non-standard behavior by resetting the screen or carefully processing known sequence subsets.

Install

pip install pyte Install stable version

Imports

Screen
```
from pyte import Screen
```
Stream
```
from pyte import Stream
```

Quickstart

Initializes a `pyte.Screen` and `pyte.Stream`, feeds some basic ANSI-encoded text, and then prints the current state of the screen to standard output, including cursor position and mode.

import pyte
import sys

# Create a screen and a stream
screen = pyte.Screen(columns=80, rows=24)
stream = pyte.Stream(screen)

# Feed some data, must be bytes
stream.feed(b"\x1b[31mHello, \x1b[32mWorld!\x1b[0m\r\n")
stream.feed(b"\x1b[1mThis is bold.\x1b[0m\r\n")
stream.feed(b"\x1b[3mThis is italic.\x1b[0m\r\n")

# Print the current state of the screen
for row_str in screen.display:
    sys.stdout.write(row_str)

print(f"\nCursor position: ({screen.cursor.x}, {screen.cursor.y})")
print(f"Current mode: {screen.mode}")

view raw JSON →