readchar Python Library

The library is designed to be portable, but support varies by platform:

• Actively Supported: Linux, Windows
• Supported (but not actively tested): macOS, FreeBSD, OpenBSD, Android
• Unix-based systems: Theoretically supported, but not actively tested.

Install the readchar library using pip to enable single character and keystroke reading in your Python applications.

pip install readchar

The readchar.config class is a static class used to modify the library's behavior. You can override its attributes to change how the library handles specific keys.

Attributes:

• INTERRUPT_KEYS: A list of keys that, when pressed, cause readkey() to raise a KeyboardInterrupt.
  • Default: [key.CTRL_C]

To build interactive CLI tools, import the key module to compare the output of readkey() against platform-independent constants. This ensures your code is portable across different operating systems.

from readchar import readkey, key

while True:
  k = readkey()
  if k == "a":
    # do stuff
  if k == key.DOWN:
    # do stuff
  if k == key.ENTER:
    break

Use readchar.readchar() to read exactly one character from stdin, returning it as a string of length 1. This method waits until a character is available.

Warning: This method only handles single ASCII characters. For any keys involving escape sequences (like arrows or function keys), use readkey() instead.

import readchar

char = readchar.readchar()

Use readchar.readkey() to read the next keystroke from stdin. This method is preferred over readchar() because it handles multi-character sequences like arrow keys, function keys, and combinations with ALT or CTRL.

Keystroke types handled:

• Single characters (e.g., a, Z, 9)
• Special characters (e.g., ENTER, BACKSPACE, TAB)
• CTRL combinations (e.g., CTRL+A)
• Cursor/Arrow keys (e.g., 🡩, 🡪, 🡫, 🡨)
• Navigation keys (e.g., INSERT, HOME)
• Function keys (F1 to F12)
• ALT combinations
• CTRL + ALT combinations

Note: CTRL+C is not returned by readkey(); it raises a KeyboardInterrupt by default.

import readchar

key = readchar.readkey()

Use readchar.readchar() to read a single character from the standard input. This is useful for simple character-based interactions.

import readchar

char = readchar.readchar()
print(f'You pressed: {char}')

The readchar.config class serves as a static container for constants used throughout the library. You should access its attributes directly; do not attempt to instantiate the class, as doing so will raise a SyntaxError.

One available attribute is INTERRUPT_KEYS, which contains a list of keys that trigger an interrupt (e.g., CTRL_C).

from readchar import config

# Accessing constants directly
print(config.INTERRUPT_KEYS)

The readchar.key module provides access to constants representing special keyboard keys (e.g., UP, DOWN, ENTER, ESC). This module is provided for backwards compatibility and allows you to import these constants directly via import readchar.key or from readchar import key.

import readchar

# Accessing key constants
if key == readchar.key.UP:
    print("User pressed the UP arrow")

Use readchar.readkey() to read a full key stroke (including special keys like arrow keys or function keys) as a string. This is the preferred method for handling complex keyboard input.

import readchar

key = readchar.readkey()
print(f'Key pressed: {key}')