Params Module

Parameter usage / help text formatters

author:

Doug Skrypa

class cli_command_parser.formatting.params.ParamHelpFormatter(param: ParamOrGroup)

Bases: object

required_formatter_map: BoolFormatterMap = {False: <built-in method format of str object>}

classmethod __init_subclass__(param_cls: Type[ParamOrGroup] = None, **kwargs)

classmethod for_param_cls(param_cls: Type[ParamOrGroup])

param

maybe_wrap_usage(text: str) → str

Wraps the provided text in parentheses / brackets / etc based on whether the associated Parameter is required, if supported.

format_metavar() → str

format_basic_usage() → str

Format the Parameter for use in the usage: line

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str

Format the Parameter for use in both the usage: line and in the list of Parameters

iter_usage_parts(include_meta: Bool = False, full: Bool = False) → Iterator[str]

format_description(rst: Bool = False, description: str = None) → str

format_help(prefix: str = '', tw_offset: int = 0) → str

rst_usage() → str

rst_row() → tuple[str, str]

Returns a tuple of (usage, description)

rst_rows() → Iterator[tuple[str, str]]

class cli_command_parser.formatting.params.PositionalHelpFormatter(param: ParamOrGroup)

Bases: ParamHelpFormatter

param: BasePositional

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str

class cli_command_parser.formatting.params.OptionHelpFormatter(param: ParamOrGroup)

Bases: ParamHelpFormatter

param: BaseOption

iter_usage_parts(include_meta: Bool = False, full: Bool = False) → Iterator[str]

format_description(rst: Bool = False, description: str = None) → str

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str

rst_usage() → str

class cli_command_parser.formatting.params.TriFlagHelpFormatter(param: ParamOrGroup)

Bases: OptionHelpFormatter

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str

format_description(rst: Bool = False, alt: bool = False) → str

format_help(prefix: str = '', tw_offset: int = 0) → str

rst_rows() → Iterator[tuple[str, str]]

param: BaseOption

class cli_command_parser.formatting.params.ChoiceMapHelpFormatter(param: ParamOrGroup)

Bases: ParamHelpFormatter

param: ChoiceMap

property choice_groups: Iterable[ChoiceGroup]

format_metavar() → str

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str

format_help(prefix: str = '', tw_offset: int = 0) → str

rst_table() → RstTable

class cli_command_parser.formatting.params.ChoiceGroup(choice: Choice)

Bases: object

A group of Choice objects from a given ChoiceMap that point to the same target. The first discovered Choice for a given target is considered the canonical one. Subsequent Choices for that target are considered aliases.

Used for formatting help text based on the configured CommandConfig.cmd_alias_mode.

choices

choice_strs

classmethod group_choices(choices: Iterable[Choice]) → Iterable[ChoiceGroup]

Processes the given Choices to group them by target and configured help text. If two choices have the same target but different help text values, then they are considered different, so they are not grouped together.

Parameters:

choices – The Choice objects that may contain aliases of each other.

Returns:

The ChoiceGroup objects containing the grouped Choices.

add(choice: Choice)

format(default_mode: SubcommandAliasHelpMode | str, tw_offset: int = 0, prefix: str = '') → Iterator[str]

Parameters:

• default_mode – The default SubcommandAliasHelpMode to use if no mode was explicitly configured, or the format string to use for subcommand aliases.

• tw_offset – Terminal width offset for text width calculations.

• prefix – Prefix to add to every line (primarily intended for use with nested groups).

Returns:

Generator that yields formatted help text entries (strings) for the Choices in this group.

prepare(default_mode: CmdAliasMode) → Iterator[tuple[Choice, OptStr, OptStr]]

Prepares the choice values and descriptions to use for each Choice in this group based on the configured alias mode.

Parameters:

default_mode – The default SubcommandAliasHelpMode to use if no mode was explicitly configured, or the format string to use for subcommand aliases.

Returns:

Generator that yields 3-tuples containing the Choice object, the choice string value, and the help text / description for that choice / alias.

prepare_combined() → tuple[Choice, OptStr, OptStr]

Prepare this group’s Choices for inclusion in help text / documentation by combining all aliases into a single entry.

prepare_aliases(format_str: str = 'Alias of: {choice}') → Iterator[tuple[Choice, OptStr, OptStr]]

Prepare this group’s Choices for inclusion in help text / documentation using an alternate description for aliases.

Variables supported in the format_str:

• {choice}: The first (“canonical”) choice string for this group

• {alias}: The alias choice string

• {help}: The original help text for this Choice / group

To append a suffix to alias descriptions instead of the default prefix, a mode / format string like the following could be used:

cmd_alias_mode='{help} [Alias of: {choice}]'

Parameters:

format_str – The format string to use as the help text / description for aliases.

Returns:

Generator that yields 3-tuples containing the Choice object, the choice string value, and the help text / description for that choice / alias.

prepare_repeated() → Iterator[tuple[Choice, OptStr, OptStr]]

Prepare this group’s Choices for inclusion in help text / documentation with no modifications. Choices that are considered aliases are simply repeated as if they were not aliases.

class cli_command_parser.formatting.params.PassThruHelpFormatter(param: ParamOrGroup)

Bases: ParamHelpFormatter

required_formatter_map: BoolFormatterMap = {False: <built-in method format of str object>, True: <built-in method format of str object>}

param

class cli_command_parser.formatting.params.GroupHelpFormatter(param: ParamOrGroup)

Bases: ParamHelpFormatter

param: ParamGroup

required_formatter_map: BoolFormatterMap = {False: <built-in method format of str object>, True: <built-in method format of str object>}

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str

format_description(rst: Bool = False, description: str = None) → str

format_help(prefix: str = '', tw_offset: int = 0, clean: Bool = True) → str

Prepare the help text for this group.

Parameters:

• prefix – Prefix to add to every line (primarily intended for use with nested groups)

• tw_offset – Terminal width offset for text width calculations

• clean – If this group only contains other groups or Action or SubCommand parameters, then omit the description.

Returns:

The formatted help text.

rst_table() → RstTable