CLI helpers

Most applications only need @proto.cli. These lower-level functions support custom command-line parsing and help rendering.

python

from params_proto.cli import parse_cli_args, colorize_help, get_terminal_width

parse_cli_args consumes a decorated wrapper; it is not a general argument-list parser. For everyday usage, follow CLI applications.

API index

Name	Kind	Defined in
`Colors`	class	`params_proto.cli.ansi_help`
`get_terminal_width`	function	`params_proto.cli.ansi_help`
`strip_ansi`	function	`params_proto.cli.ansi_help`
`wrap_text_with_ansi`	function	`params_proto.cli.ansi_help`
`colorize_help`	function	`params_proto.cli.ansi_help`
`get_ansi_help`	function	`params_proto.cli.ansi_help`
`parse_cli_args`	function	`params_proto.cli.cli_parse`

params_proto.cli

CLI argument parsing and help generation for params-proto.

This module handles:

Command-line argument parsing
Help text generation
ANSI colorization for terminal output

Public imports

These symbols are available from this module. Their definitions are documented in the linked modules.

parse_cli_args — params_proto.cli.cli_parse.parse_cli_args
colorize_help — params_proto.cli.ansi_help.colorize_help
get_terminal_width — params_proto.cli.ansi_help.get_terminal_width

params_proto.cli.ansi_help

ANSI-formatted help text generation for terminal display.

Provides colorized, terminal-width-aware formatting of help text. Keeps help_str as plain text for testing, adds ansi_str for display.

Terminal Detection Notes:

Width Detection:

Uses shutil.get_terminal_size() which queries terminal dimensions
Checks COLUMNS env var first, then terminal ioctl
Width can change during a session (user resizes window)
For params-proto: No caching needed since help is printed once and exits
For long-running CLIs: Would need SIGWINCH handler or query-per-print
Current approach (query on each colorize_help() call) is correct and cheap

Color Detection:

Currently NOT implemented - colors always applied
Should check:
- sys.stdout.isatty() - False for pipes/redirects
- NO_COLOR env var - https://no-color.org/
- TERM env var - 'dumb' or missing means no color support
TODO: Add should_use_color() function

Performance:

shutil.get_terminal_size() is fast (just reads terminal attributes)
No need to cache width since help is only printed once per execution
For high-frequency printing, would consider caching with SIGWINCH handler

`Colors`

classparams_proto.cli.ansi_help.ColorsSource ↗

class Colors

ANSI color codes for terminal formatting.

Attributes

Name	Type / value	Description
`RESET`	`'\x1b[0m'`	—
`BOLD`	`'\x1b[1m'`	—
`DIM`	`'\x1b[2m'`	—
`RED`	`'\x1b[31m'`	—
`GREEN`	`'\x1b[32m'`	—
`YELLOW`	`'\x1b[33m'`	—
`BLUE`	`'\x1b[34m'`	—
`MAGENTA`	`'\x1b[35m'`	—
`CYAN`	`'\x1b[36m'`	—
`WHITE`	`'\x1b[37m'`	—
`BRIGHT_BLACK`	`'\x1b[90m'`	—
`BRIGHT_RED`	`'\x1b[91m'`	—
`BRIGHT_GREEN`	`'\x1b[92m'`	—
`BRIGHT_YELLOW`	`'\x1b[93m'`	—
`BRIGHT_BLUE`	`'\x1b[94m'`	—
`BRIGHT_MAGENTA`	`'\x1b[95m'`	—
`BRIGHT_CYAN`	`'\x1b[96m'`	—

`get_terminal_width`

functionparams_proto.cli.ansi_help.get_terminal_widthSource ↗

get_terminal_width(default: int = 80, max_width: int = 120) → int

Get the current terminal width.

Parameters

Parameter	Type / default	Description
`default`	`int` = 80	Default width if terminal size cannot be detected
`max_width`	`int` = 120	Maximum width to use even if terminal is wider

Returns

int — Terminal width in characters

`strip_ansi`

functionparams_proto.cli.ansi_help.strip_ansiSource ↗

strip_ansi(text: str) → str

Remove ANSI escape codes from text.

Parameters

Parameter	Type / default	Description
`text`	`str` required	Text potentially containing ANSI codes

Returns

str — Plain text with ANSI codes removed

`wrap_text_with_ansi`

functionparams_proto.cli.ansi_help.wrap_text_with_ansiSource ↗

wrap_text_with_ansi(text: str, width: int, indent: str = '') → list

Wrap text while preserving ANSI codes.

Parameters

Parameter	Type / default	Description
`text`	`str` required	Text to wrap (may contain ANSI codes)
`width`	`int` required	Target width for wrapping
`indent`	`str` = ''	Indentation string for wrapped lines

Returns

list — List of wrapped lines

`colorize_help`

functionparams_proto.cli.ansi_help.colorize_helpSource ↗

colorize_help(help_str: str, width: Optional[int] = None) → str

Add ANSI colors and line wrapping to help text.

Colorization:

Type names (INT, STR, FLOAT, etc.) -> bold bright blue ([1m[94m)
(required) -> bold red ([1m[31m)
(default: value) -> cyan parentheses with bold cyan value Example: [36m(default:[0m [1m[36m128[0m[36m)[0m
Option names (--foo) -> plain text (no formatting)

Parameters

Parameter	Type / default	Description
`help_str`	`str` required	Plain text help string
`width`	`Optional[int]` = None	Terminal width (auto-detected if None)

Returns

str — ANSI-formatted help text with proper line wrapping

`get_ansi_help`

functionparams_proto.cli.ansi_help.get_ansi_helpSource ↗

get_ansi_help(wrapper) → str

Get ANSI-formatted help string from a proto wrapper.

Parameters

Parameter	Type / default	Description
`wrapper`	`—` required	ProtoWrapper instance with __help_str__

Returns

str — ANSI-formatted help text

params_proto.cli.cli_parse

CLI argument parsing for params-proto v3.

Converts sys.argv into kwargs for proto-decorated functions. Simple custom parser - no argparse dependency.

`parse_cli_args`

functionparams_proto.cli.cli_parse.parse_cli_argsSource ↗

parse_cli_args(wrapper) → Dict[str, Any]

Parse CLI arguments for a ProtoWrapper.

Parameters

Parameter	Type / default	Description
`wrapper`	`—` required	ProtoWrapper instance

Returns

Dict[str, Any] — Dictionary of parsed arguments