Appearance

The appearance package contains the layout, color, and help-formatting objects used to control how Interfacy renders CLI help.

Base Types

The base appearance classes are configuration-heavy. For these objects, the constructor signature is the useful part of the API; the inherited rendering methods are documented once on HelpLayout instead of repeated on every preset.

HelpLayout

Base layout configuration object used by the appearance system. Its constructor parameters define the available formatting knobs.

Grouped command listings can be tuned with command_indent for the global command-row indentation and command_group_spacing for the number of blank lines inserted between help-group sections.

HelpLayout.format_argument(arg, indent=2)

Format one argument schema as a rendered help line.

Parameters:

• arg (Argument) – Argument schema to render.

• indent (int) – Leading indent width in spaces.

HelpLayout.format_description(description)

Format a description string for help output.

Parameters:

description (str) – Raw description text.

HelpLayout.format_parameter(param, flags)

Format a parameter using the active layout template.

Parameters:

• param (Parameter) – Parameter metadata.

• flags (tuple[str, ...]) – CLI flags for the parameter.

HelpLayout.format_usage_metavar(name, *, is_varargs=False)

Format a metavar token for usage output.

Parameters:

• name (str) – Base metavar text.

• is_varargs (bool) – Whether the metavar represents varargs.

HelpLayout.get_command_description(

command,

ljust,

name=None,

aliases=(),

)

Format a command description line for listings.

Parameters:

• command (Class | Function | Method) – Command to describe.

• ljust (int) – Column width for the name.

• name (str | None) – Override display name.

• aliases (tuple[str, ...]) – Alternate CLI names.

HelpLayout.get_commands_ljust(max_display_len)

Compute the left-justify width for command listings.

Parameters:

max_display_len (int) – Maximum display name length.

HelpLayout.get_help_for_class(command, *, rules=None)

Build help text for class subcommands.

Parameters:

• command (Class) – Inspected class command.

• rules (list[HelpSubcommandSortRule] | None) – Optional explicit ordering rules.

HelpLayout.get_help_for_multiple_commands(commands, *, rules=None)

Build a command listing for multiple top-level commands.

Parameters:

• commands (dict[str, Command]) – Command map keyed by name.

• rules (list[HelpSubcommandSortRule] | None) – Optional explicit ordering rules.

HelpLayout.get_help_for_parameter(param, flags=None)

Return help text for a parameter.

Parameters:

• param (Parameter) – Parameter metadata.

• flags (tuple[str, ...] | None) – CLI flags for display, if any.

HelpLayout.get_parser_command_usage_suffix()

HelpLayout.get_primary_boolean_flag_for_argument(arg)

Return the canonical flag token used to display a boolean option.

Parameters:

arg (Argument) – Argument schema describing a boolean flag.

HelpLayout.get_subcommand_usage_token()

Return the subcommand placeholder token used in usage lines.

HelpLayout.is_argument_boolean(arg)

Return whether an argument schema represents a boolean flag.

Parameters:

arg (Argument) – Argument schema to inspect.

HelpLayout.keep_help_default_slot_for_arguments(_arguments)

Decide whether to preserve the empty default column for help rows.

Parameters:

_arguments (list[Argument]) – Argument rows being rendered.

HelpLayout.order_class_methods_for_help(methods, *, rules=None)

Return class methods sorted by the active help-subcommand ordering rules.

Parameters:

• methods (list[Method]) – Public methods eligible for subcommand display.

• rules (list[HelpSubcommandSortRule] | None) – Optional explicit ordering rules.

HelpLayout.order_commands_for_help(commands, *, rules=None)

Return commands sorted by the active help-subcommand ordering rules.

Parameters:

• commands (dict[str, Command]) – Command map keyed by canonical name.

• rules (list[HelpSubcommandSortRule] | None) – Optional explicit ordering rules.

HelpLayout.order_option_arguments_for_help(options, *, rules=None)

Return options sorted by the active help-option ordering rules.

Parameters:

• options (list[Argument]) – Option arguments to sort.

• rules (list[HelpOptionSortRule] | None) – Optional explicit ordering rules.

HelpLayout.prepare_default_field_width_for_arguments(arguments)

Compute default-column widths for a batch of rendered arguments.

Parameters:

arguments (list[Argument]) – Argument schemas rendered in one help section.

HelpLayout.prepare_default_field_width_for_params(params)

Compute default column width from parameter defaults.

Parameters:

params (list[Parameter]) – Parameters to inspect.

HelpLayout.should_render_description_before_usage()

Object	Purpose
InterfacyColors	Base color-theme container for help rendering styles.
InterfacyLayout	Interfacy-branded layout preset built on HelpLayout.

Layouts

These classes are layout presets built on top of HelpLayout.

Object	Purpose
StandardLayout	Default layout that follows standard argparse-style help output.
SimpleLayout	Alias of StandardLayout.
ArgparseLayout	Layout tuned to closely mirror argparse help formatting.
Aligned	Compact aligned layout with a dedicated default-value column.
AlignedTyped	Aligned variant that gives more emphasis to type information.
Modern	More spacious modern layout with stronger visual separation.
ClapLayout	Layout inspired by Rust clap output.

Color Themes

Color presets expose configuration through their constructor fields and do not add a separate callable API.

Object	Purpose
NoColor	Monochrome theme with no accent colors.
Aurora	Theme inspired by aurora palettes.
ClapColors	Theme that mimics clap default styled output.

Help Sorting

HelpOptionSortRule

alias of Literal[‘required_first’, ‘short_first’, ‘value_first’, ‘bool_last’, ‘no_default_first’, ‘choices_first’, ‘name_length’, ‘alias_count’, ‘alphabetical’]

HELP_OPTION_SORT_RULE_VALUES: tuple[HelpOptionSortRule, ...] = ('required_first', 'short_first', 'value_first', 'bool_last', 'no_default_first', 'choices_first', 'name_length', 'alias_count', 'alphabetical')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

DEFAULT_HELP_OPTION_SORT_RULES: tuple[HelpOptionSortRule, ...] = ('required_first', 'short_first', 'bool_last', 'alphabetical')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

normalize_sort_rule_name(value)

Normalize a sort-rule token for case/format-insensitive matching.

resolve_sort_rules(

value,

*,

value_name,

allowed_values,

allow_none=True,

empty_means_none=True,

)

Validate and normalize a list of named sort rules.

resolve_help_option_sort_rules(

value,

*,

value_name='help_option_sort',

allow_none=True,

empty_means_none=True,

)

Validate and normalize help option sort rules.

default_help_option_sort_rules()

Return a mutable copy of the global default help option sort rules.

HelpSubcommandSortRule

alias of Literal[‘insert_order’, ‘alphabetical’, ‘name_length_asc’, ‘name_length_desc’]

HELP_SUBCOMMAND_SORT_RULE_VALUES: tuple[HelpSubcommandSortRule, ...] = ('insert_order', 'alphabetical', 'name_length_asc', 'name_length_desc')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

DEFAULT_HELP_SUBCOMMAND_SORT_RULES: tuple[HelpSubcommandSortRule, ...] = ('insert_order',)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

resolve_help_subcommand_sort_rules(

value,

*,

value_name='help_subcommand_sort',

allow_none=True,

empty_means_none=True,

)

Validate and normalize help subcommand sort rules.

default_help_subcommand_sort_rules()

Return a mutable copy of the global default help subcommand sort rules.

Type Formatting

TypeStyleTheme is the protocol consumed by TypeHelpFormatter when styling type tokens.

class TypeHelpFormatter

Bases: object

format_type_for_help(annotation, style, theme=None)

Rendering

SchemaHelpRenderer

Turns schema objects into final help text using a selected layout.

SchemaHelpRenderer.render_parser_help(schema, prog)

Render help text for a parser schema and program name.

Parameters:

• schema (ParserSchema) – Parser schema to render.

• prog (str) – Program name or invocation prefix.

SchemaHelpRenderer.render_command_help(

command,

prog,

*,

parser_description=None,

parser_epilog=None,

parser_executable_flags=None,

)

Render help text for one command schema.

Parameters:

• command (Command) – Command schema to render.

• prog (str) – Program name or invocation prefix.

• parser_description (str | None) – Optional parser-level description override.

• parser_epilog (str | None) – Optional parser-level epilog text.

• parser_executable_flags (list[ExecutableFlag] | None) – Parser-level executable flags to merge into single-command help output.

has_grouped_commands(commands)

Return whether any command in a mapping has a help-group label.

command_has_grouped_subcommands(command)

Return whether a command has subcommands with help-group labels.