Params Module

Parameter usage / help text formatters

author:: Doug Skrypa

class cli_command_parser.formatting.params.ParamHelpFormatter(param: ParamOrGroup)[source]

Bases: object

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

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

classmethod for_param_cls(param_cls: Type[ParamOrGroup])[source]

param

maybe_wrap_usage(text: str) → str[source]: Wraps the provided text in parentheses / brackets / etc based on whether the associated Parameter is required, if supported.

format_metavar() → str[source]

format_basic_usage() → str[source]: Format the Parameter for use in the usage: line

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str[source]: 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][source]: Format the Parameter for use in the list of Parameters with their help='...' descriptions

format_description(rst: Bool = False, description: str = None) → str[source]

format_help(prefix: str = '') → str[source]

rst_usage() → str[source]

rst_row() → tuple[str, str][source]: Returns a tuple of (usage, description)

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

class cli_command_parser.formatting.params.PositionalHelpFormatter(param: ParamOrGroup)[source]

Bases: ParamHelpFormatter

param: BasePositional

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str[source]

class cli_command_parser.formatting.params.OptionHelpFormatter(param: ParamOrGroup)[source]

Bases: ParamHelpFormatter

param: BaseOption

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

format_description(rst: Bool = False, description: str = None) → str[source]

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str[source]

rst_usage() → str[source]

class cli_command_parser.formatting.params.TriFlagHelpFormatter(param: ParamOrGroup)[source]

Bases: OptionHelpFormatter

format_usage(include_meta: Bool = False, full: Bool = False, delim: str = ', ') → str[source]

format_description(rst: Bool = False, alt: bool = False) → str[source]

format_help(prefix: str = '') → str[source]

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

param: BaseOption

class cli_command_parser.formatting.params.ChoiceMapHelpFormatter(param: ParamOrGroup)[source]

Bases: ParamHelpFormatter

Formatter for SubCommand and Action parameters (and any other params that extend ChoiceMap)

param: ChoiceMap

property choice_groups: Iterable[ChoiceGroup][source]

format_metavar() → str[source]

format_help(prefix: str = '') → str[source]

rst_table() → RstTable[source]

class cli_command_parser.formatting.params.ChoiceGroup(choice: Choice)[source]

Bases: object

A group of Choice objects from a given ChoiceMap, representing the positional argument values that may be provided, 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][source]

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)[source]

format(default_mode: SubcommandAliasHelpMode | str, prefix: str = '') → Iterator[str][source]

Parameters:

default_mode¶ – The default SubcommandAliasHelpMode to use if no mode was explicitly configured, or the format string to use for subcommand aliases.
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]][source]

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][source]: 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]][source]

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]][source]: 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)[source]

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)[source]

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[source]

format_description(rst: Bool = False, description: str = None) → str[source]

format_help(prefix: str = '', clean: Bool = True) → str[source]

Prepare the help text for this group.

Parameters:

prefix¶ – Prefix to add to every line (primarily intended for use with nested groups)
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[source]