Support Types

Parser Base

class InterfacyParser[source]

Base parser interface for building CLI commands from callables.

Parameters:

  • description (str | None) – CLI description shown in help output.

  • epilog (str | None) – Epilog text shown after help output.

  • help_layout (HelpLayout | None) – Help layout implementation.

  • type_parser (StrToTypeParser | None) – Parser registry for typed arguments.

  • help_colors (InterfacyColors | None) – Override help color theme.

  • run (bool) – Whether to auto-run after command registration.

  • print_result (bool) – Whether to print returned results.

  • tab_completion (bool) – Whether to enable tab completion.

  • full_error_traceback (bool) – Whether to print full tracebacks.

  • allow_args_from_file (bool) – Allow @file argument expansion.

  • sys_exit_enabled (bool) – Whether to call sys.exit on completion.

  • flag_strategy (FlagStrategy | None) – Flag naming and style strategy.

  • abbreviation_gen (AbbreviationGenerator | None) – Abbreviation generator.

  • abbreviation_max_generated_len (int) – Max generated short-flag length.

  • abbreviation_scope (AbbreviationScope) – Which option groups receive generated short flags.

  • help_option_sort (list[HelpOptionSortRule] | None) – Rules for option row ordering in help output. When unset, layout defaults are used, then global defaults.

  • help_subcommand_sort (list[HelpSubcommandSortRule] | None) – Rules for command/subcommand row ordering in help output. When unset, layout defaults are used, then global defaults.

  • help_position (int | None) – Absolute column where help descriptions begin.

  • executable_flags (Sequence[ExecutableFlag] | None) – Parser-root executable flags.

  • pipe_targets (PipeTargets | dict[str, Any] | Sequence[Any] | str | None) – Pipe config.

  • print_result_func (Callable) – Function used to print results.

  • include_inherited_methods (bool) – Include inherited methods for class commands.

  • include_protected_methods (bool) – Include protected methods for class commands.

  • include_private_methods (bool) – Include private methods for class commands.

  • include_staticmethods (bool) – Include static methods for class commands.

  • include_classmethods (bool) – Include classmethods as commands.

  • on_interrupt (Callable[[KeyboardInterrupt], None] | None) – Interrupt callback.

  • silent_interrupt (bool) – Suppress interrupt message output.

  • reraise_interrupt (bool) – Re-raise KeyboardInterrupt after handling.

  • expand_model_params (bool) – Expand model parameters into nested flags.

  • model_expansion_max_depth (int) – Max depth for model expansion.

  • bool_negative_prefix (str | None) – Prefix for generated negative boolean flags.

  • method_skips (Sequence[str] | None) – Method names to exclude from class commands.

  • parse_recovery_max_attempts (int) – Max plugin parse-recovery attempts.

Naming

class AbbreviationGenerator[source]

Interface for generating short flag abbreviations.

abstract generate(value, taken)[source]

Return a unique abbreviation for a value or None if unavailable.

Parameters:

  • value (str) – Source value to abbreviate.

  • taken (list[str]) – Already-reserved abbreviations. Modified in-place.

class DefaultAbbreviationGenerator[source]

Simple abbreviation generator that tries to return a short name for a command. Returns None if it cannot find a short name.

Parameters:

max_generated_len (int, optional) – Maximum generated abbreviation length.

Example

>>> AbbreviationGenerator(taken=[]).generate("hello_word")
"h"
>>> AbbreviationGenerator(taken=["h"]).generate("hello_word")
"hw"
>>> AbbreviationGenerator(taken=["hw", "h"]).generate("hello_word")
"he"
>>> AbbreviationGenerator(taken=["hw", "h", "he"]).generate("hello_word")
None
class NoAbbreviations[source]

Abbreviation generator that disables short flags.

FlagStyle

alias of Literal[‘keyword_only’, ‘required_positional’]

TranslationMode

alias of Literal[‘none’, ‘kebab’, ‘snake’]

class FlagStrategy[source]
class DefaultFlagStrategy[source]

Default flag strategy for generating CLI flag names.

Parameters:

  • style (FlagStyle) – Flag style for required/optional parameters.

  • translation_mode (TranslationMode) – Name translation mode.

  • nested_separator (str) – Separator for nested model paths.

class CommandNameRegistry[source]

Tracks canonical command names—the primary CLI labels—and their aliases.

Group Metadata

AbbreviationScope

alias of Literal[‘top_level_options’, ‘all_options’]

class CommandEntry[source]

Internal representation of a command added to a group.

class SubgroupEntry[source]

Internal representation of a subgroup added to a group.

Backend Types

The low-level ArgumentParser also accepts help_position so manual argparse setups can use the same help-description column control as Interfacy.

class ArgumentParser[source]

ArgumentParser with nested destinations and custom help formatting.

Parameters:

  • prog (str | None) – Program name used in help output.

  • usage (str | None) – Custom usage string.

  • description (str | None) – Description text shown in help.

  • epilog (str | None) – Epilog text shown after help.

  • parents (list[ArgumentParser] | None) – Parent parsers to inherit args.

  • formatter_class (type[argparse.HelpFormatter]) – Help formatter class.

  • prefix_chars (str) – Prefix characters for options.

  • fromfile_prefix_chars (str | None) – Prefix for args-from-file.

  • argument_default (Any) – Default value for all arguments.

  • conflict_handler (str) – Conflict resolution strategy.

  • add_help (bool) – Whether to add a help option.

  • allow_abbrev (bool) – Whether to allow abbreviations of long options.

  • nest_dir (str | None) – Base nesting directory label.

  • nest_separator (str) – Separator for nested destinations.

  • nest_path (list[str] | None) – Explicit nesting path components.

  • exit_on_error (bool) – Whether to exit on parse errors.

  • help_layout (Any | None) – Layout configuration for help rendering.

  • help_position (int | None) – Absolute column where help descriptions begin.

  • color (bool | None) – Force colorized help output when supported.

class InterfacyClickCommand[source]

Render command help with Interfacy schema-aware formatting.

class InterfacyClickGroup[source]

Resolve group aliases and render group help with schema metadata.