ddp_utils.console.common¶

import ddp_utils.console.common

Expose shared cursor wrappers and lightweight console printing helpers.

The module owns one package-wide ConsoleCursor, delegates styling to styler.py, and preserves the historical cursor and printer convenience API without duplicating platform-specific terminal logic.

Examples

Print a styled status through the compatibility dispatcher:

from ddp_utils.console.common import printer

printer("Ready", color="green", style="bold")

ddp_utils.console.common.get_cursor() → ConsoleCursor¶

Return the shared console cursor helper used by the package.

This function is the single public entrypoint for direct cursor access. Any module that needs low-level cursor operations should prefer this helper instead of creating its own ConsoleCursor instance.

Returns

Type	Description
ConsoleCursor	Shared `ConsoleCursor` instance.

Examples

Reuse the package cursor backend:

cursor = get_cursor()

ddp_utils.console.common.print_stack() → None¶

Print the current Python call stack to stderr.

This function is kept as a small utility and as a backward-compatible part of the historical console API.

Examples

Emit a diagnostic stack at the current call site:

print_stack()

ddp_utils.console.common.cursor_send(cmd: str) → None¶

Send a raw terminal control sequence to stdout.

This is a backward-compatible helper. For new code, higher-level cursor operations are preferred when possible.

Parameters

Name	Type	Description
cmd	str	Raw terminal control sequence to write.

Examples

Send a terminal reset sequence:

cursor_send("[0m")

ddp_utils.console.common.clear_n_top_line(n: int = 1) → None¶

Clear n lines above the current cursor position.

Historical behavior:

move one line up;
clear that line;
repeat n times.

The implementation now routes through ConsoleCursor instead of duplicating ANSI sequences locally.

Parameters

Name	Type	Description
n	int	Number of lines above the cursor to clear; non-positive values do nothing.

Examples

Remove two previously rendered lines:

clear_n_top_line(2)

ddp_utils.console.common.clear_line() → None¶

Clear the current console line.

The cursor backend preserves the current column whenever the backend is able to determine it. This is more robust than the old raw ESC[2K helper.

Examples

Erase the active status line:

clear_line()

ddp_utils.console.common.cursor_up(n: int = 1) → None¶

Move the cursor up by n lines.

Parameters

Name	Type	Description
n	int	Number of lines to move.

Examples

Move to the previous output row:

cursor_up(1)

ddp_utils.console.common.cursor_down(n: int = 1) → None¶

Move the cursor down by n lines.

Parameters

Name	Type	Description
n	int	Number of lines to move.

Examples

Move down two terminal rows:

cursor_down(2)

ddp_utils.console.common.cursor_left(n: int = 1) → None¶

Move the cursor left by n columns.

Parameters

Name	Type	Description
n	int	Number of columns to move.

Examples

Move back over one rendered character:

cursor_left()

ddp_utils.console.common.cursor_right(n: int = 1) → None¶

Move the cursor right by n columns.

Parameters

Name	Type	Description
n	int	Number of columns to move.

Examples

Move forward four columns:

cursor_right(4)

ddp_utils.console.common.move_to_column(col: int = 1) → None¶

Move the cursor to the given 1-based column on the current line.

Parameters

Name	Type	Description
col	int	Target one-based column.

Examples

Return to the first column:

move_to_column(1)

ddp_utils.console.common.set_cursor_position(row: int, col: int) → None¶

Set cursor to the absolute 1-based position (row, col).

Parameters

Name	Type	Description
row	int	Target one-based row.
col	int	Target one-based column.

Examples

Move to the terminal origin:

set_cursor_position(1, 1)

ddp_utils.console.common.get_cursor_position()¶

Return the current cursor position.

Returns

Tuple (row, col) when available, otherwise None.

Examples

Preserve an optional terminal position:

position = get_cursor_position()

ddp_utils.console.common.save_cursor_position() → None¶

Save the current cursor position using the shared cursor backend.

Examples

Save the current position before temporary output:

save_cursor_position()

ddp_utils.console.common.restore_cursor_position() → None¶

Restore the previously saved cursor position using the shared cursor backend.

Examples

Return after temporary output:

restore_cursor_position()

ddp_utils.console.common.hide_cursor() → None¶

Hide the terminal cursor.

Examples

Hide the cursor during live rendering:

hide_cursor()

ddp_utils.console.common.show_cursor() → None¶

Show the terminal cursor.

Examples

Restore cursor visibility after live rendering:

show_cursor()

ddp_utils.console.common.cli_progress(current: int, total: int, bar_length: int = 20) → None¶

Render a simple single-line progress bar in place.

This helper intentionally remains lightweight and does not try to replace ProgressBar from progress.py. It is kept for quick scripts and for backward compatibility with older code.

Parameters

Name	Type	Description
current	int	Current progress value.
total	int	Maximum progress value; non-positive totals produce no output.
bar_length	int	Width of the ASCII bar in characters.

Examples

Update a quick script’s in-place counter:

cli_progress(current=5, total=10, bar_length=20)

ddp_utils.console.common.printer(arg: Any, color=None, bg=None, style=None, **kwargs) → None¶

Clear the previous line and print a message.

Dispatch rules:

if arg is a valid list of color segments, use cprint();
if color / bg / style is explicitly provided, use cprint();
otherwise use plain print().

This function is the canonical public printing entrypoint for the package.

Parameters

Name	Type	Description
arg	Any	Plain object or list of styled segments.
color		Optional foreground color for scalar input.
bg		Optional background color for scalar input.
style		Optional text style for scalar input.
**kwargs		Additional arguments passed to `print` or `cprint`.

Examples

Clear the previous line and print a highlighted result:

printer("Complete", color="green")