API Reference ¶

static success(t, **k)[source]¶

Parameters:: t (str)

static fail(t, **k)[source]¶

Parameters:: t (str)

static red(t, **k)[source]¶

Parameters:: t (str)

static green(t, **k)[source]¶

Parameters:: t (str)

static yellow(t, **k)[source]¶

Parameters:: t (str)

static blue(t, **k)[source]¶

Parameters:: t (str)

static magenta(t, **k)[source]¶

Parameters:: t (str)

static cyan(t, **k)[source]¶

Parameters:: t (str)

static white(t, **k)[source]¶

Parameters:: t (str)

static orange(t, **k)[source]¶

Parameters:: t (str)

static bold(t, **k)[source]¶

Parameters:: t (str)

static italic(t, **k)[source]¶

Parameters:: t (str)

static multicolor(texts, colors, end='\n', flush=False, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, emit=True, markup=True)[source]¶

Print multiple colored text segments with rich markup support.

Parameters:

texts (List[str]) – List of text segments
colors (List[str]) – List of colors (one per text segment)
end (str) – String to append at the end
flush (bool) – Whether to flush the output
file (Any) – Output stream
emit (bool) – Whether to actually print
markup (bool) – Whether to parse rich markup tags in each segment

Return type:

None

static highlight(text, subtext, color='\x1b[37m', highlight_color='\x1b[33m', whole_line=False, end='\n', flush=False, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, markup=False)[source]¶

Highlight substrings in text with optional rich markup support.

Parameters:

text (str) – The text to process
subtext (str | List[str]) – String or list of strings to highlight
color (str) – Default text color
highlight_color (str) – Color for highlighted portions
whole_line (bool) – Whether to highlight entire lines containing subtext
end (str) – String to append at the end
flush (bool) – Whether to flush the output
file (Any) – Output stream
markup (bool) – Whether to parse rich markup tags in the text first

Return type:

None

static execute_with_animation(pending_text, func, *args, color=None, **kwargs)[source]¶

Parameters:

pending_text (str)
func (Callable[[...], _T])
args (Any)
color (str | None)
kwargs (Any)

Return type:

static confirm(question, default_yes=None, prompt_color='\x1b[33m', file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, markup=True)[source]¶

Ask a yes/no confirmation question with optional rich markup support.

Parameters:

question (str) – The question text
default_yes (bool | None) – Default answer if user just presses Enter
prompt_color (str) – Color for the prompt
file (Any) – Output stream
markup (bool) – Whether to parse rich markup tags in the question

Return type:

bool

static prompt(text, color='\x1b[32m', style='', hide_input=False, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, markup=True)[source]¶

Prompt for user input with optional rich markup support.

Parameters:

text (str) – The prompt text
color (str) – Color for the prompt
style (str) – Style for the prompt
hide_input (bool) – Whether to hide the input (for passwords)
file (Any) – Output stream
markup (bool) – Whether to parse rich markup tags in the prompt text

Return type:

static rich_print(text, **kwargs)[source]¶

Print text with rich markup support.

Supports tags like [magenta], [bold], [success], [error], etc.

Examples

ASCIIColors.rich_print(“[magenta]Hello[/magenta] [bold]World[/bold]”) ASCIIColors.rich_print(“[success]Operation completed successfully[/success]”) ASCIIColors.rich_print(“[error]An error occurred[/error]”) ASCIIColors.rich_print(“[warning]Warning: deprecated feature[/warning]”) ASCIIColors.rich_print(“[info]Note: processing started[/info]”)

Parameters:

text (str)
kwargs (Any)

Return type:

None

static panel(content, title=None, border_style='', box='square', padding=(0, 1), width=None, color='', background='')[source]¶

Create a bordered panel around content. Returns string for printing.

New rich-style convenience method.

Parameters:

content (str | dict)
title (str | None)
border_style (str)
box (str)
padding (int | Tuple[int, ...])
width (int | None)
color (str)
background (str)

Return type:

static table(*headers, rows=None, title=None, box='square', show_lines=False, header_style='bold')[source]¶

Create a formatted table. Returns string for printing.

New rich-style convenience method.

Parameters:

headers (str)
rows (List[List[str]] | None)
title (str | None)
box (str)
show_lines (bool)
header_style (str)

Return type:

static tree(label, style='', guide_style='dim')[source]¶

Create a tree structure for display.

New rich-style convenience method. Returns a Tree object that can have children added.

Parameters:

label (str)
style (str)
guide_style (str)

Return type:

Tree

static syntax(code, language='python', line_numbers=False, theme=None)[source]¶

Syntax highlight code. Returns string for printing.

New rich-style convenience method.

Parameters:

code (str)
language (str)
line_numbers (bool)
theme (Dict[str, str] | None)

Return type:

static markdown(markup)[source]¶

Render markdown to terminal. Returns string for printing.

New rich-style convenience method.

Parameters:: markup (str)
Return type:: str

static columns(*items, equal=False, width=None)[source]¶

Arrange items in columns. Returns string for printing.

New rich-style convenience method.

Parameters:

items (str)
equal (bool)
width (int | None)

Return type:

static rule(title='', characters='─', style='', align='center')[source]¶

Print a horizontal rule with optional title.

New rich-style convenience method.

Parameters:

title (str)
characters (str)
style (str)
align (str)

Return type:

None

static status(message, spinner='dots', spinner_style='green')[source]¶

Show a spinner status indicator.

New rich-style convenience method. Use as context manager.

Example

with ASCIIColors.status(“Processing…”):: do_work()

Parameters:

message (str)
spinner (str)
spinner_style (str)

Return type:

Status

static live(renderable, refresh_per_second=4)[source]¶

Create a live updating display.

New rich-style convenience method. Use as context manager.

Example

with ASCIIColors.live(some_renderable) as live:

while updating:: live.update(new_renderable)

Parameters:

renderable (Any)
refresh_per_second (float)

Return type:

Live

Direct Printing Methods¶

Color Shortcuts¶

Logging Methods¶

Configuration Methods¶

Rich Integration Convenience Methods¶

Constants¶

class ascii_colors.LogLevel(value)[source]¶

Bases: IntEnum

Enumeration defining standard logging levels.

CRITICAL = 50¶

ERROR = 40¶

WARNING = 30¶

INFO = 20¶

DEBUG = 10¶

NOTSET = 0¶

Level Constants¶

ascii_colors.DEBUG = 10¶

ascii_colors.INFO = 20¶

ascii_colors.WARNING = 30¶

ascii_colors.ERROR = 40¶

ascii_colors.CRITICAL = 50¶

ascii_colors.NOTSET = 0¶

ANSI Color Constants¶

All available as class attributes on ASCIIColors:

Styles:

style_bold, style_dim, style_italic, style_underline
style_blink, style_reverse, style_hidden, style_strikethrough

Foreground Colors:

color_black, color_red, color_green, color_yellow
color_blue, color_magenta, color_cyan, color_white, color_orange
Bright variants: color_bright_*
Background colors: color_bg_* and color_bg_bright_*

Reset:

color_reset

Logging Components¶

Formatters¶

class ascii_colors.Formatter(fmt=None, datefmt=None, style='%', include_source=False, **kwargs)[source]¶

Bases: object

Base class for formatting log records into textual representations.

Parameters:

fmt (str | None)
datefmt (str | None)
style (str)
include_source (bool)
kwargs (Any)

format(level, message, timestamp, exc_info, logger_name='root', **kwargs)[source]¶

Parameters:

level (LogLevel)
message (str)
timestamp (datetime)
exc_info (Tuple | None)
logger_name (str)
kwargs (Any)

Return type:

format_exception(exc_info)[source]¶

Parameters:: exc_info (Tuple)
Return type:: str

class ascii_colors.JSONFormatter(fmt=None, datefmt=None, style='%', json_ensure_ascii=False, json_indent=None, json_separators=None, json_sort_keys=False, include_fields=None, include_source=False, **kwargs)[source]¶

Bases: Formatter

Formats log records into JSON strings.

Parameters:

fmt (Dict[str, str] | None)
datefmt (str | None)
style (str)
json_ensure_ascii (bool)
json_indent (int | None)
json_separators (Tuple | None)
json_sort_keys (bool)
include_fields (List[str] | None)
include_source (bool)
kwargs (Any)

format(level, message, timestamp, exc_info, logger_name='root', **kwargs)[source]¶

Parameters:

level (LogLevel)
message (str)
timestamp (datetime)
exc_info (Tuple | None)
logger_name (str)
kwargs (Any)

Return type:

Handlers¶

class ascii_colors.Handler(level=10, formatter=None)[source]¶

Bases: ABC

Abstract base class for all log handlers.

Parameters:

level (LogLevel | int)
formatter (Formatter | None)

setLevel(level)[source]¶

Parameters:: level (LogLevel | int)
Return type:: None

getLevel()[source]¶

Return type:: int

setFormatter(formatter)[source]¶

Parameters:: formatter (Formatter)
Return type:: None

handle(level, message, timestamp, exc_info, logger_name='root', **kwargs)[source]¶

Parameters:

level (LogLevel)
message (str)
timestamp (datetime)
exc_info (Tuple | None)
logger_name (str)
kwargs (Any)

Return type:

None

abstractmethod emit(level, formatted_message)[source]¶

Parameters:

level (LogLevel)
formatted_message (str)

Return type:

None

close()[source]¶

Return type:: None

handle_error(message)[source]¶

Parameters:: message (str)

class ascii_colors.ConsoleHandler(level=10, formatter=None, stream=None)[source]¶

Bases: Handler

Handles logging records by writing them to a stream (typically console).

Parameters:

level (LogLevel | int)
formatter (Formatter | None)
stream (IO[str] | None)

emit(level, formatted_message)[source]¶

Parameters:

level (LogLevel)
formatted_message (str)

Return type:

None

close()[source]¶

Return type:: None

ascii_colors.StreamHandler¶: alias of ConsoleHandler

class ascii_colors.FileHandler(filename, mode='a', encoding='utf-8', delay=False, level=10, formatter=None)[source]¶

Bases: Handler

Handles logging records by writing them to a file.

Parameters:

filename (str | Path)
mode (str)
encoding (str | None)
delay (bool)
level (LogLevel | int)
formatter (Formatter | None)

emit(level, formatted_message)[source]¶

Parameters:

level (LogLevel)
formatted_message (str)

Return type:

None

close()[source]¶

Return type:: None

flush()[source]¶

Return type:: None

class ascii_colors.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding='utf-8', delay=False, level=10, formatter=None)[source]¶

Bases: FileHandler

Handles logging to a file, rotating it when it reaches a certain size.

Parameters:

filename (str | Path)
mode (str)
maxBytes (int)
backupCount (int)
encoding (str | None)
delay (bool)
level (LogLevel | int)
formatter (Formatter | None)

emit(level, formatted_message)[source]¶

Parameters:

level (LogLevel)
formatted_message (str)

Return type:

None

do_rollover()[source]¶

Return type:: None

class ascii_colors.handlers[source]¶

Bases: object

class RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding='utf-8', delay=False, level=10, formatter=None)¶

Bases: FileHandler

Handles logging to a file, rotating it when it reaches a certain size.

Parameters:

filename (str | Path)
mode (str)
maxBytes (int)
backupCount (int)
encoding (str | None)
delay (bool)
level (LogLevel | int)
formatter (Formatter | None)

do_rollover()¶

Return type:: None

emit(level, formatted_message)¶

Parameters:

level (LogLevel)
formatted_message (str)

Return type:

None

class FileHandler(filename, mode='a', encoding='utf-8', delay=False, level=10, formatter=None)¶

Bases: Handler

Handles logging records by writing them to a file.

Parameters:

filename (str | Path)
mode (str)
encoding (str | None)
delay (bool)
level (LogLevel | int)
formatter (Formatter | None)

close()¶

Return type:: None

emit(level, formatted_message)¶

Parameters:

level (LogLevel)
formatted_message (str)

Return type:

None

flush()¶

Return type:: None

StreamHandler¶: alias of ConsoleHandler

Standard Library Compatibility¶

ascii_colors.getLogger(name=None)[source]¶

Get a logger with the specified name.

This function mirrors logging.getLogger() for drop-in compatibility.

Parameters:: name (str | None)
Return type:: _AsciiLoggerAdapter

ascii_colors.basicConfig(*, filename=None, filemode='a', format=None, datefmt=None, style='%', level=None, stream=None, handlers=None, force=False)[source]¶

Configure basic logging.

Mirrors logging.basicConfig() for drop-in compatibility.

Parameters:

filename (str | None)
filemode (str)
format (str | None)
datefmt (str | None)
style (str)
level (int | None)
stream (TextIOWrapper | None)
handlers (List[Handler] | None)
force (bool)

Return type:

None

ascii_colors.shutdown()[source]¶

Shutdown the logging system.

Return type:: None

ascii_colors.trace_exception(ex, enhanced=False, max_width=None)[source]¶

Logs the traceback of a given exception.

Parameters:

ex (BaseException)
enhanced (bool)
max_width (int)

Return type:

None

ascii_colors.get_trace_exception(ex, enhanced=True, max_width=None)[source]¶

Formats an exception and its traceback into a string.

Parameters:

ex (BaseException)
enhanced (bool)
max_width (int | None)

Return type:

ascii_colors.strip_ansi(text)[source]¶

Removes ANSI escape sequences from a string.

Parameters:: text (str)
Return type:: str

Interactive Components¶

ProgressBar¶

class ascii_colors.ProgressBar(iterable=None, total=None, desc='', unit='it', ncols=None, bar_format=None, leave=True, mininterval=0.15, color='\x1b[32m', style='', background='', bar_style='fill', **kwargs)[source]¶

Bases: object

Customizable progress bar similar to tqdm.

update(n=1)[source]¶

close()[source]¶

Menu System¶

class ascii_colors.Menu(title, parent=None, mode='execute', **kwargs)[source]¶

Bases: object

Interactive styled command-line menu.

Now supports checkbox and radio modes for questionary-like behavior.

Parameters:

title (str)
parent (Menu | None)
mode (str)

MODE_EXECUTE = 'execute'¶

MODE_SELECT = 'select'¶

MODE_RETURN = 'return'¶

MODE_CHECKBOX = 'checkbox'¶

items: List[MenuItem]¶

add_action(text, action=None, **kwargs)[source]¶

Add an action item.

Parameters:

text (str)
action (Callable | None)

Return type:

add_submenu(text, submenu, **kwargs)[source]¶

Add a submenu.

Parameters:

text (str)
submenu (Menu)

Return type:

add_choice(text, value=None, **kwargs)[source]¶

Add a choice item (for select mode).

Parameters:

text (str)
value (Any)

Return type:

add_choices(choices)[source]¶

Add multiple choices at once.

Parameters:: choices (List[Tuple[str, Any]])
Return type:: Menu

add_checkbox(text, value=None, checked=False, **kwargs)[source]¶

Add a checkbox item (for checkbox mode).

Parameters:

text (str)
value (Any)
checked (bool)

Return type:

add_input(text, **kwargs)[source]¶

Add an input field item.

Parameters:: text (str)
Return type:: Menu

run()[source]¶

Run the menu and return result based on mode.

Return type:: Any

get_selected_values()[source]¶

Get all checked values (for checkbox mode).

Return type:: List[Any]

get_selected_value()[source]¶

Get single selected value (for select mode).

Return type:: Any

class ascii_colors.MenuItem(text, item_type='action', target=None, value=None, disabled=False, selected=False, exit_on_success=False, is_input=False, initial_input='', help_text=None, custom_color=None, checked=False)[source]¶

Bases: object

Represents an item within a Menu.

Parameters:

text (str)
item_type (str)
target (Any)
value (Any)
disabled (bool)
selected (bool)
exit_on_success (bool)
is_input (bool)
initial_input (str)
help_text (str | None)
custom_color (str | None)
checked (bool)

Rich Integration Module¶

The ascii_colors.rich module provides Rich-compatible components.

Rich Module Instance¶

ascii_colors.rich: RichModule¶

Module-like object providing Rich-compatible functionality.

Example:

from ascii_colors import rich
rich.print("[bold red]Hello[/bold red]")
rich.rule("Section")

Console¶

class ascii_colors.rich.Console(width=None, height=None, file=None, force_terminal=None, force_jupyter=None, force_width=None, force_height=None, no_color=False, tab_size=4, record=False, markup=True, emoji=True, emoji_variant=None, highlight=True, log_time=True, log_path=True, log_time_format='[%X]', highlighter=None, legacy_windows=None, safe_box=True, get_environ=<function Console.<lambda>>, get_time=None, get_terminal_size=None)[source]¶

Bases: object

Console for rich text output.

Parameters:

width (int | None)
height (int | None)
file (TextIO | None)
force_terminal (bool | None)
force_jupyter (bool | None)
force_width (int | None)
force_height (int | None)
no_color (bool)
tab_size (int)
record (bool)
markup (bool)
emoji (bool)
emoji_variant (str | None)
highlight (bool)
log_time (bool)
log_path (bool)
log_time_format (str)
highlighter (Any | None)
legacy_windows (bool | None)
safe_box (bool)
get_environ (Callable[[str], Any])
get_time (Callable[[], float] | None)
get_terminal_size (Callable[[], Tuple[int, int]] | None)

property is_terminal: bool¶

property is_jupyter: bool¶

property color_system: str | None¶

property width: int¶

property height: int¶

property size: Tuple[int, int]¶

render(renderable, options=None)[source]¶

Render a renderable to lines.

Parameters:

renderable (Renderable | str)
options (ConsoleOptions | None)

Return type:

List[str]

print(*objects, sep=' ', end='\n', style=None, justify=None, overflow=None, no_wrap=None, emoji=None, markup=None, highlight=None, width=None, crop=True, soft_wrap=False, flush=False)[source]¶: Print objects to the console.

log(*objects, sep=' ', end='\n', style=None, justify=None, emoji=None, markup=None, highlight=None)[source]¶: Log to console with timestamp.

rule(title='', characters='─', style=None, align='center')[source]¶: Print a horizontal rule.

input(prompt='', *, markup=True, emoji=True, password=False, stream=None)[source]¶: Get input from user with styled prompt.

export_text(clear=True, styles=False)[source]¶

Export recorded output as text.

Return type:: str

capture()[source]¶: Capture console output.

clear(home=False)[source]¶: Clear the console.

save_screen()[source]¶: Save current screen.

restore_screen()[source]¶: Restore saved screen.

Style and Color¶

class ascii_colors.rich.Style(color=None, background=None, bold=None, dim=None, italic=None, underline=None, blink=None, reverse=None, strike=None)[source]¶

Bases: object

Represents text styling (color, bold, italic, etc.).

Parameters:

color (str | Color | None)
background (str | Color | None)
bold (bool | None)
dim (bool | None)
italic (bool | None)
underline (bool | None)
blink (bool | None)
reverse (bool | None)
strike (bool | None)

classmethod parse(style_str)[source]¶

Parse a style string like ‘bold red on blue’.

Parameters:: style_str (str | None)
Return type:: Style | None

class ascii_colors.rich.Color(name=None, rgb=None)[source]¶

Bases: object

Represents a color for terminal output.

Parameters:

name (str | None)
rgb (Tuple[int, int, int] | None)

classmethod parse(color_str)[source]¶

Parse a color string into a Color object.

Parameters:: color_str (str | None)
Return type:: Color | None

class ascii_colors.rich.BoxStyle(value)[source]¶

Bases: Enum

Box drawing styles.

SQUARE = 'square'¶

ROUND = 'round'¶

MINIMAL = 'minimal'¶

MINIMAL_HEAVY_HEAD = 'minimal_heavy_head'¶

SIMPLE = 'simple'¶

SIMPLE_HEAD = 'simple_head'¶

DOUBLE = 'double'¶

get_chars()[source]¶

Get characters for this box style.

Return type:: Dict[str, str]

Text and Renderables¶

class ascii_colors.rich.Text(text=None, style=None, justify=None, overflow='fold', no_wrap=False, end='')[source]¶

Bases: Renderable

A renderable text object with styling.

Parameters:

text (str | Text | None)
style (str | Style | None)
justify (str | None)
overflow (str)
no_wrap (bool)
end (str)

append(text, style=None)[source]¶

Append text to this Text object.

Parameters:

text (str | Text)
style (str | Style | None)

Return type:

Text

truncate(max_width, overflow=None)[source]¶

Truncate text to max_width.

Parameters:

max_width (int)
overflow (str | None)

Return type:

pad(width, align='left', char=' ')[source]¶

Pad text to width with alignment.

Parameters:

width (int)
align (str)
char (str)

Return type:

wrap(width)[source]¶

Wrap text into multiple lines.

Parameters:: width (int)
Return type:: List[Text]

render(width=None)[source]¶

Render text with ANSI codes.

Parameters:: width (int | None)
Return type:: str

class ascii_colors.rich.Renderable[source]¶

Bases: ABC

Abstract base class for renderable objects.

Layout Components¶

class ascii_colors.rich.Panel(renderable, title=None, title_align='center', style=None, border_style=None, box=BoxStyle.SQUARE, padding=(0, 1), width=None, height=None, expand=True)[source]¶

Bases: object

A bordered panel around content.

This class properly handles: - Emoji and wide characters (counted as 2 terminal columns) - Rich markup tags like [bold], [red], etc. - ANSI escape codes for colors and styles - Multi-line content with proper wrapping

Parameters:

renderable (Renderable | str)
title (str | None)
title_align (str)
style (str | Style | None)
border_style (str | Style | None)
box (BoxStyle | str)
padding (int | Tuple[int, ...])
width (int | None)
height (int | None)
expand (bool)

classmethod fit(renderable, title=None, title_align='center', style=None, border_style=None, box=BoxStyle.SQUARE, padding=(0, 1), width=None, height=None)[source]¶

Create a panel that is just wide enough to fit its content.

Parameters:

renderable (Renderable | str)
title (str | None)
title_align (str)
style (str | Style | None)
border_style (str | Style | None)
box (BoxStyle | str)
padding (int | Tuple[int, ...])
width (int | None)
height (int | None)

Return type:

Panel

class ascii_colors.rich.Padding(renderable, pad=None, style=None)[source]¶

Bases: object

Padding around content.

Parameters:

renderable (Renderable)
pad (int | Tuple[int, ...] | None)
style (str | Style | None)

class ascii_colors.rich.Columns(renderables, padding=1, width=None, equal=False, column_first=False)[source]¶

Bases: object

Arrange renderables in columns.

Parameters:

renderables (Iterable[Renderable | str])
padding (int)
width (int | None)
equal (bool)
column_first (bool)

Data Display¶

class ascii_colors.rich.Table(*headers, title=None, caption=None, width=None, min_width=None, box=BoxStyle.SQUARE, padding=(0, 1), collapse_padding=False, pad_edge=True, expand=False, show_header=True, show_edge=True, show_lines=False, safe_box=None, padding_style=None, header_style=None, row_styles=None, border_style=None)[source]¶

Bases: Renderable

A table with rows and columns.

Parameters:

headers (str)
title (str | None)
caption (str | None)
width (int | None)
min_width (int | None)
box (BoxStyle | str | None)
padding (Tuple[int, int])
collapse_padding (bool)
pad_edge (bool)
expand (bool)
show_header (bool)
show_edge (bool)
show_lines (bool)
safe_box (bool | None)
padding_style (str | Style | None)
header_style (str | Style | None)
row_styles (List[str | Style] | None)
border_style (str | Style | None)

add_column(header='', style=None, no_wrap=False, width=None, justify='left')[source]¶

Add a column to the table.

Parameters:

header (str)
style (str | Style | None)
no_wrap (bool)
width (int | None)
justify (str)

Return type:

None

add_row(*cells, style=None)[source]¶

Add a row to the table.

Parameters:

cells (str)
style (str | Style | None)

Return type:

None

class ascii_colors.rich.Tree(label, *, style=None, guide_style=None, expanded=True, highlight=False)[source]¶

Bases: Renderable

A tree structure for display.

Parameters:

label (str | Text | Renderable)
style (str | Style | None)
guide_style (str | Style | None)
expanded (bool)
highlight (bool)

add(label, *, style=None)[source]¶

Add a child node.

Parameters:

label (str | Text | Tree)
style (str | Style | None)

Return type:

Tree

add_node(label)[source]¶

Add a child node and return it for chaining.

Parameters:: label (str | Text)
Return type:: Tree

Content Components¶

class ascii_colors.rich.Syntax(code, lexer='python', line_numbers=False, line_number_start=1, highlight_lines=None, code_width=None, tab_size=4, theme=None, word_wrap=False, indent_guides=False, padding=0)[source]¶

Bases: Renderable

Syntax highlighted code.

Parameters:

code (str)
lexer (str)
line_numbers (bool)
line_number_start (int)
highlight_lines (List[int] | None)
code_width (int | None)
tab_size (int)
theme (Dict[str, str] | None)
word_wrap (bool)
indent_guides (bool)
padding (int)

class ascii_colors.rich.Markdown(markup, code_theme=None, justify=None, style=None, hyperlinks=True)[source]¶

Bases: Renderable

Markdown rendering for terminal.

Parameters:

markup (str)
code_theme (str | None)
justify (str | None)
style (str | Style | None)
hyperlinks (bool)

Live Display¶

class ascii_colors.rich.Live(renderable=None, console=None, screen=False, auto_refresh=True, refresh_per_second=4, vertical_overflow='ellipsis', get_renderable=None)[source]¶

Bases: object

Live updating display.

Parameters:

renderable (Renderable | None)
console (Console | None)
screen (bool)
auto_refresh (bool)
refresh_per_second (float)
vertical_overflow (str)
get_renderable (Callable[[], Renderable] | None)

start()[source]¶

Start the live display.

Return type:: None

stop()[source]¶

Stop the live display.

Return type:: None

update(renderable, *, refresh=False)[source]¶

Update the renderable.

Parameters:

renderable (Renderable)
refresh (bool)

Return type:

None

refresh()[source]¶

Force a refresh.

Return type:: None

class ascii_colors.rich.Status(status, *, console=None, spinner='dots', spinner_style=None, speed=1.0)[source]¶

Bases: object

Status spinner display.

Parameters:

status (str)
console (Console | None)
spinner (str)
spinner_style (str | Style | None)
speed (float)

SPINNERS = {'arrow': '←↖↑↗→↘↓↙', 'dots': '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏', 'line': '⎺⎻⎼⎽⎼⎻', 'moon': '🌑🌒🌓🌔🌕🌖🌗🌘', 'pulse': '◐◓◑◒', 'star': '✶✸✹✺✹✷'}¶

start()[source]¶

Start the status display.

Return type:: None

stop()[source]¶

Stop the status display.

Return type:: None

update(status, *, spinner=None, speed=None)[source]¶

Update status text.

Parameters:

status (str)
spinner (str | None)
speed (float | None)

Return type:

None

Questionary Compatibility¶

Drop-in replacement for the questionary library.

Base Classes¶

class ascii_colors.questionary.Question(message, default=None, validate=None, style=None, **kwargs)[source]¶

Bases: object

Base class for all question types.

Parameters:

message (str)
default (Any)
validate (Callable[[str], bool] | Validator | None)
style (Dict[str, str] | Style | Any | None)

ask(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask the question and return the answer.

Parameters:

patch_stdout (bool)
kbi_msg (str)

Return type:

Any

unsafe_ask(patch_stdout=False)[source]¶

Ask without catching KeyboardInterrupt.

Parameters:: patch_stdout (bool)
Return type:: Any

skip_if(condition, default=None)[source]¶

Skip this question if condition is true.

Parameters:

condition (bool)
default (Any)

Return type:

Question

class ascii_colors.questionary.Validator(message='invalid input')[source]¶

Bases: object

Base class for input validators.

Parameters:: message (str)

classmethod from_callable(func, message='invalid input')[source]¶

Parameters:

func (Callable[[str], bool])
message (str)

validate(document)[source]¶

Validate the input. Raise ValidationError if invalid.

Parameters:: document (str)
Return type:: None

class ascii_colors.questionary.ValidationError(message='invalid input')[source]¶

Bases: Exception

Exception raised when validation fails.

Parameters:: message (str)

Question Types¶

ascii_colors.questionary.Text¶: alias of PromptText

class ascii_colors.questionary.Password(message, default='', validate=None, style=None, **kwargs)[source]¶

Bases: PromptText

Password input (hidden).

Parameters:

message (str)
default (str)
validate (Callable[[str], bool] | Validator | None)
style (Dict[str, str] | None)

class ascii_colors.questionary.Confirm(message, default=True, style=None, **kwargs)[source]¶

Bases: Question

Yes/No confirmation question.

Parameters:

message (str)
default (bool)
style (Dict[str, str] | None)

class ascii_colors.questionary.Select(message, choices, default=None, style=None, **kwargs)[source]¶

Bases: Question

Single selection from list.

Parameters:

message (str)
choices (List[str | Dict[str, Any]])
default (str | int | None)
style (Dict[str, str] | None)

class ascii_colors.questionary.Checkbox(message, choices, default=None, style=None, **kwargs)[source]¶

Bases: Question

Multiple selection from list.

Parameters:

message (str)
choices (List[str | Dict[str, Any]])
default (List[str | int] | None)
style (Dict[str, str] | None)

ask(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask the question and return the answer.

Parameters:

patch_stdout (bool)
kbi_msg (str)

Return type:

Any

skip_if(condition, default=None)[source]¶

Skip this question if condition is true.

Parameters:

condition (bool)
default (Any)

Return type:

Checkbox

unsafe_ask(patch_stdout=False)[source]¶

Ask without catching KeyboardInterrupt.

Parameters:: patch_stdout (bool)
Return type:: List[Any]

class ascii_colors.questionary.Autocomplete(message, choices, default='', validate=None, style=None, **kwargs)[source]¶

Bases: PromptText

Text input with autocomplete suggestions.

Parameters:

message (str)
choices (List[str])
default (str)
validate (Callable[[str], bool] | Validator | None)
style (Dict[str, str] | None)

class ascii_colors.questionary.Form(questions)[source]¶

Bases: object

Group of questions to ask in sequence.

Parameters:: questions (List[Question])

ask(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask all questions and return answers dict.

Parameters:

patch_stdout (bool)
kbi_msg (str)

Return type:

Dict[str, Any]

Convenience Functions¶

ascii_colors.questionary.text(message, default='', validate=None, style=None, **kwargs)[source]¶

Create a text input question.

Parameters:

message (str)
default (str)
validate (Callable[[str], bool] | Validator | None)
style (Dict[str, str] | None)

Return type:

PromptText

ascii_colors.questionary.password(message, default='', validate=None, style=None, **kwargs)[source]¶

Create a password input question.

Parameters:

message (str)
default (str)
validate (Callable[[str], bool] | Validator | None)
style (Dict[str, str] | None)

Return type:

Password

ascii_colors.questionary.confirm(message, default=True, style=None, **kwargs)[source]¶

Create a yes/no confirmation question.

Parameters:

message (str)
default (bool)
style (Dict[str, str] | None)

Return type:

Confirm

ascii_colors.questionary.select(message, choices, default=None, style=None, **kwargs)[source]¶

Create a single-select question.

Parameters:

message (str)
choices (List[str | Dict[str, Any]])
default (str | int | None)
style (Dict[str, str] | None)

Return type:

Select

ascii_colors.questionary.checkbox(message, choices, default=None, style=None, **kwargs)[source]¶

Create a multi-select checkbox question.

Parameters:

message (str)
choices (List[str | Dict[str, Any]])
default (List[str | int] | None)
style (Dict[str, str] | None)

Return type:

Checkbox

ascii_colors.questionary.autocomplete(message, choices, default='', validate=None, style=None, **kwargs)[source]¶

Create an autocomplete text input question.

Parameters:

message (str)
choices (List[str])
default (str)
validate (Callable[[str], bool] | Validator | None)
style (Dict[str, str] | None)

Return type:

Autocomplete

ascii_colors.questionary.form(*questions)[source]¶

Create a form from multiple questions.

Parameters:: questions (Question)
Return type:: Form

ascii_colors.questionary.ask(questions)¶

Group of questions to ask in sequence.

Parameters:: questions (List[Question])

Module-Level Access¶

For drop-in replacement of questionary:

ascii_colors.questionary: _QuestionaryModule¶

Module-like object with all questionary functions and classes.

Example:

from ascii_colors import questionary
name = questionary.text("Your name?").ask()

Utility Functions¶

ascii_colors.get_trace_exception(ex, enhanced=True, max_width=None)[source]¶

Formats an exception and its traceback into a string.

Parameters:

ex (BaseException)
enhanced (bool)
max_width (int | None)

Return type:

ascii_colors.strip_ansi(text)[source]¶

Removes ANSI escape sequences from a string.

Parameters:: text (str)
Return type:: str

Internal Classes¶

class ascii_colors._AsciiLoggerAdapter(name)[source]¶

Bases: object

Adapter that provides standard logging.Logger interface using ASCIIColors backend.

Parameters:: name (str)

isEnabledFor(level)[source]¶

Check if this logger is enabled for the specified level.

This is a standard logging.Logger method that checks whether a message at the given level would actually be logged.

Parameters:: level (int) – The log level to check (e.g., DEBUG, INFO, WARNING)
Returns:: True if the logger is enabled for the given level, False otherwise
Return type:: bool

setLevel(level)[source]¶

Set the logging level.

Parameters:: level (int | LogLevel)
Return type:: None

getEffectiveLevel()[source]¶

Get the effective level for this logger.

Return type:: int

debug(msg, *args, **kwargs)[source]¶

Log a debug message.

Parameters:: msg (str)
Return type:: None

info(msg, *args, **kwargs)[source]¶

Log an info message.

Parameters:: msg (str)
Return type:: None

warning(msg, *args, **kwargs)[source]¶

Log a warning message.

Parameters:: msg (str)
Return type:: None

warn(msg, *args, **kwargs)[source]¶

Deprecated alias for warning.

Parameters:: msg (str)
Return type:: None

error(msg, *args, **kwargs)[source]¶

Log an error message.

Parameters:: msg (str)
Return type:: None

critical(msg, *args, **kwargs)[source]¶

Log a critical message.

Parameters:: msg (str)
Return type:: None

fatal(msg, *args, **kwargs)[source]¶

Log a fatal message (alias for critical).

Parameters:: msg (str)
Return type:: None

exception(msg, *args, **kwargs)[source]¶

Log an exception message with traceback.

Parameters:: msg (str)
Return type:: None

log(level, msg, *args, **kwargs)[source]¶

Log a message at the specified level.

Parameters:

level (int)
msg (str)

Return type:

None

addHandler(hdlr)[source]¶

Add a handler to this logger.

Parameters:: hdlr (Handler)
Return type:: None

removeHandler(hdlr)[source]¶

Remove a handler from this logger.

Parameters:: hdlr (Handler)
Return type:: None

hasHandlers()[source]¶

Check if this logger has any handlers.

Return type:: bool

filter(record)[source]¶

Filter method (stub for compatibility).

Parameters:: record (Any)
Return type:: bool

handle(record)[source]¶

Handle a log record.

Parameters:: record (Any)
Return type:: None

findCaller(stack_info=False, stacklevel=1)[source]¶

Find the caller (stub for compatibility).

Parameters:

stack_info (bool)
stacklevel (int)

Return type:

Tuple

getChild(suffix)[source]¶

Get a child logger.

Parameters:: suffix (str)
Return type:: _AsciiLoggerAdapter

property root: bool¶: Check if this is the root logger.

class ascii_colors._QuestionaryModule[source]¶

Bases: object

Module-like object for drop-in questionary compatibility.

class ascii_colors.rich.RichModule[source]¶

Bases: object

Module-like interface for rich compatibility.

property console: Console¶: Get the default console.

print(*objects, sep=' ', end='\n', style=None, justify=None, overflow=None, no_wrap=None, emoji=None, markup=None, highlight=None)[source]¶: Print to the default console.

log(*objects, sep=' ', end='\n', style=None)[source]¶: Log to the default console.

rule(title='', characters='─', style=None, align='center')[source]¶: Print a rule to the default console.

prompt(prompt='', *, markup=True, emoji=True, password=False)[source]¶: Get input from the user with a rich prompt.

status(status, *, spinner='dots', spinner_style=None, speed=1.0)[source]¶: Create a status spinner.

live(renderable=None, *, refresh_per_second=4, screen=False)[source]¶: Create a live display.

class Console(width=None, height=None, file=None, force_terminal=None, force_jupyter=None, force_width=None, force_height=None, no_color=False, tab_size=4, record=False, markup=True, emoji=True, emoji_variant=None, highlight=True, log_time=True, log_path=True, log_time_format='[%X]', highlighter=None, legacy_windows=None, safe_box=True, get_environ=<function Console.<lambda>>, get_time=None, get_terminal_size=None)¶

Bases: object

Console for rich text output.

Parameters:

width (int | None)
height (int | None)
file (TextIO | None)
force_terminal (bool | None)
force_jupyter (bool | None)
force_width (int | None)
force_height (int | None)
no_color (bool)
tab_size (int)
record (bool)
markup (bool)
emoji (bool)
emoji_variant (str | None)
highlight (bool)
log_time (bool)
log_path (bool)
log_time_format (str)
highlighter (Any | None)
legacy_windows (bool | None)
safe_box (bool)
get_environ (Callable[[str], Any])
get_time (Callable[[], float] | None)
get_terminal_size (Callable[[], Tuple[int, int]] | None)

capture()¶: Capture console output.

clear(home=False)¶: Clear the console.

property color_system: str | None¶

export_text(clear=True, styles=False)¶

Export recorded output as text.

Return type:: str

property height: int¶

input(prompt='', *, markup=True, emoji=True, password=False, stream=None)¶: Get input from user with styled prompt.

property is_jupyter: bool¶

property is_terminal: bool¶

log(*objects, sep=' ', end='\n', style=None, justify=None, emoji=None, markup=None, highlight=None)¶: Log to console with timestamp.

print(*objects, sep=' ', end='\n', style=None, justify=None, overflow=None, no_wrap=None, emoji=None, markup=None, highlight=None, width=None, crop=True, soft_wrap=False, flush=False)¶: Print objects to the console.

render(renderable, options=None)¶

Render a renderable to lines.

Parameters:

renderable (Renderable | str)
options (ConsoleOptions | None)

Return type:

List[str]

restore_screen()¶: Restore saved screen.

rule(title='', characters='─', style=None, align='center')¶: Print a horizontal rule.

save_screen()¶: Save current screen.

property size: Tuple[int, int]¶

property width: int¶

class Text(text=None, style=None, justify=None, overflow='fold', no_wrap=False, end='')¶

Bases: Renderable

A renderable text object with styling.

Parameters:

text (str | Text | None)
style (str | Style | None)
justify (str | None)
overflow (str)
no_wrap (bool)
end (str)

append(text, style=None)¶

Append text to this Text object.

Parameters:

text (str | Text)
style (str | Style | None)

Return type:

Text

pad(width, align='left', char=' ')¶

Pad text to width with alignment.

Parameters:

width (int)
align (str)
char (str)

Return type:

render(width=None)¶

Render text with ANSI codes.

Parameters:: width (int | None)
Return type:: str

truncate(max_width, overflow=None)¶

Truncate text to max_width.

Parameters:

max_width (int)
overflow (str | None)

Return type: