ddp_utils.console.cursor

import ddp_utils.console.cursor

Provide cross-platform terminal cursor control with safe fallbacks.

Examples

Clear and replace one terminal row:

cursor = ConsoleCursor(warn=True)
cursor.clear_and_write_at(2, 1, "Ready")

class ddp_utils.console.cursor.ConsoleCursor(warn: bool = True, unix_probe_timeout: float = 0.2, output_stream: TextIO | None = None, input_stream: TextIO | None = None, error_stream: TextIO | None = None)

Bases: object

Control terminal cursor movement, erasure, visibility, and positioning.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor(warn=True)
cursor.clear_line()

Initialize capability detection and platform-specific cursor state.

Parameters

Name	Type	Description
warn	bool	Emit one-time diagnostics when a requested capability is unavailable.
unix_probe_timeout	float	Maximum seconds allowed for Unix cursor-position probing.
output_stream	TextIO | None	Stream that owns the cursor. Defaults to sys.stdout.
input_stream	TextIO | None	Stream used for Unix cursor queries. Defaults to sys.stdin.
error_stream	TextIO | None	Stream used for one-time warnings. Defaults to sys.stderr.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor(warn=True, unix_probe_timeout=0.1)

property is_windows: bool

Report whether the current platform is Windows.

Returns

True on Windows; otherwise False.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
supported = cursor.is_windows

property stdout_is_tty: bool

Report whether standard output is attached to a terminal.

Returns

True when standard output is a TTY.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
supported = cursor.stdout_is_tty

property stdin_is_tty: bool

Report whether standard input is attached to a terminal.

Returns

True when standard input is a TTY.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
supported = cursor.stdin_is_tty

set_window_title(title: str) → None

Set the terminal window title when the platform supports it.

Parameters

Name	Type	Description
title	str	New terminal window title.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.set_window_title("Worker")

get_position() → Tuple[int, int] | None

Return the current one-based cursor row and column when available.

Returns

Type	Description
Tuple[int, int] | None	A one-based (row, column) tuple, or None when unavailable.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.get_position()

set_position(row: int, col: int) → None

Move the cursor to a one-based absolute row and column.

Parameters

Name	Type	Description
row	int	One-based terminal row.
col	int	One-based terminal column.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.set_position(row=2, col=4)

move_up(lines: int = 1) → None

Move the cursor upward by a positive number of rows.

Parameters

Name	Type	Description
lines	int	Number of rows to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.move_up(lines=2)

move_down(lines: int = 1) → None

Move the cursor downward by a positive number of rows.

Parameters

Name	Type	Description
lines	int	Number of rows to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.move_down(lines=2)

move_left(cols: int = 1) → None

Move the cursor left by a positive number of columns.

Parameters

Name	Type	Description
cols	int	Number of columns to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.move_left(cols=2)

move_right(cols: int = 1) → None

Move the cursor right by a positive number of columns.

Parameters

Name	Type	Description
cols	int	Number of columns to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.move_right(cols=2)

move_to_column(col: int = 1) → None

Move the cursor to a one-based column on its current row.

Parameters

Name	Type	Description
col	int	One-based terminal column.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.move_to_column(col=4)

carriage_return() → None

Move the cursor to the first column of its current row.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.carriage_return()

clear_line() → None

Erase the current line while preserving the cursor column when possible.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_line()

clear_to_line_start() → None

Erase from the first column through the cursor position.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_to_line_start()

clear_to_line_end() → None

Erase from the cursor position through the line end.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_to_line_end()

clear_lines_above(lines: int = 1) → None

Erase existing rows above the cursor and restore its position.

Parameters

Name	Type	Description
lines	int	Number of rows to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_lines_above(lines=2)

clear_lines_below(lines: int = 1) → None

Erase existing rows below the cursor and restore its position.

Parameters

Name	Type	Description
lines	int	Number of rows to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_lines_below(lines=2)

clear_left(cols: int = 1) → None

Overwrite columns left of the cursor with spaces without shifting text.

Parameters

Name	Type	Description
cols	int	Number of columns to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_left(cols=4)

clear_right(cols: int = 1) → None

Overwrite columns right of the cursor with spaces without shifting text.

Parameters

Name	Type	Description
cols	int	Number of columns to move or erase; non-positive values are ignored.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_right(cols=4)

save_position() → None

Save the current cursor position using ANSI or an in-memory fallback.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.save_position()

restore_position() → None

Restore the cursor position saved by save_position().

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.restore_position()

write_at(row: int, col: int, text: str, restore: bool = True) → None

Write text at an absolute position and optionally restore the cursor.

Parameters

Name	Type	Description
row	int	One-based terminal row.
col	int	One-based terminal column.
text	str	Text written at the target position.
restore	bool	Restore the original cursor position after writing when true.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.write_at(row=2, col=4, text="Ready", restore=True)

clear_and_write_at(row: int, col: int, text: str, restore: bool = True) → None

Erase a target row and write replacement text at an absolute position.

Parameters

Name	Type	Description
row	int	One-based terminal row.
col	int	One-based terminal column.
text	str	Text written at the target position.
restore	bool	Restore the original cursor position after writing when true.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.clear_and_write_at(row=2, col=4, text="Ready", restore=True)

hide_cursor() → None

Hide the terminal cursor when ANSI control is available.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.hide_cursor()

show_cursor() → None

Show the terminal cursor when ANSI control is available.

Examples

Use cursor control with capability-aware fallbacks:

cursor = ConsoleCursor()
cursor.show_cursor()