Parsers

Interfacy is the programmatic entry point.

Interfacy

from interfacy import Interfacy

Interfacy().run(main)
class Interfacy[source]

Build and run command-line interfaces from Python callables.

Register functions, classes, or command groups, and Interfacy turns their names, type annotations, and docstrings into commands, options, and help output. Use command() as a decorator, add_command() for explicit registration, or run() when you want to register and execute in one step.

Parameters:

  • description – Text shown before commands and options in help output.

  • epilog – Text shown after generated help output.

  • type_parser – Registry used to convert raw CLI strings into annotated types.

  • help_layout – Layout configuration for generated help output.

  • backend – Parser implementation to use. Must be "argparse" or "click".

  • help_colors – Color theme applied by the help layout.

  • run – Run backend setup immediately when supported by the selected backend.

  • print_result – Print returned command values after execution.

  • tab_completion – Install shell completion support when the backend supports it.

  • full_error_traceback – Include full tracebacks for runtime errors.

  • allow_args_from_file – Enable @file argument expansion.

  • sys_exit_enabled – Call sys.exit for parser exits instead of returning codes.

  • flag_strategy – Strategy for deriving option flags from Python names.

  • abbreviation_gen – Generator used for short option flags.

  • abbreviation_max_generated_len – Maximum generated short-flag length. Must be >= 1.

  • abbreviation_scope – Scope where generated short flags may be reused.

  • help_option_sort – Rules for ordering option help entries.

  • help_subcommand_sort – Rules for ordering subcommand help entries.

  • help_position – Absolute help-description column.

  • executable_flags – Root-level flags that run without a command.

  • pipe_targets – Default stdin routing configuration.

  • print_result_func – Callable used when print_result is enabled.

  • include_inherited_methods – Include inherited methods when registering classes.

  • include_protected_methods – Include protected methods when registering classes.

  • include_private_methods – Include private methods when registering classes.

  • include_staticmethods – Include static methods when registering classes.

  • include_classmethods – Include class methods when registering classes.

  • on_interrupt – Callback invoked for handled KeyboardInterrupt instances.

  • silent_interrupt – Suppress interrupt log output.

  • reraise_interrupt – Raise handled interrupts after logging or callbacks.

  • expand_model_params – Expand supported model parameters into nested CLI flags.

  • model_expansion_max_depth – Maximum model expansion depth. Must be >= 1.

  • bool_negative_prefix – Prefix used for generated negative boolean flags.

  • plugins – Plugins to register during initialization.

  • method_skips – Class method names to skip when registering class commands.

  • parse_recovery_max_attempts – Maximum plugin recovery attempts. Must be >= 0.

  • formatter_class – Argparse help formatter class. Only valid with backend="argparse".

Raises:

  • ConfigurationError – If backend is unsupported or formatter_class is used with backend="click".

  • ImportError – If backend="click" is requested without Click installed.

add_plugin(plugin)[source]

Register a plugin on the active backend parser.

Raises:

DuplicatePluginError – If another plugin with the same parser-local name exists.

add_type_parser(typ, parser)[source]

Register a converter for an annotation type.

The converter receives one raw CLI string and returns the value passed to the command callable.

property type_parser: strto.StrToTypeParser

Return the active type parser registry.

apply_setup(
*,
help_layout=None,
help_colors=None,
type_parser=None,
print_result=None,
tab_completion=None,
full_error_traceback=None,
allow_args_from_file=None,
flag_strategy=None,
abbreviation_gen=None,
abbreviation_max_generated_len=None,
abbreviation_scope=None,
help_option_sort=None,
help_subcommand_sort=None,
help_position=None,
include_inherited_methods=None,
include_protected_methods=None,
include_private_methods=None,
include_staticmethods=None,
include_classmethods=None,
silent_interrupt=None,
expand_model_params=None,
model_expansion_max_depth=None,
bool_negative_prefix=None,
plugins=None,
method_skips=None,
parse_recovery_max_attempts=None,
)[source]

Update parser defaults used by later registrations and parser builds.

Arguments left as None keep their current value. Plugins supplied here are registered immediately.

Raises:

ConfigurationError – If an update is invalid for the current parser state.

add_command(
command,
name=None,
description=None,
aliases=None,
pipe_targets=None,
include_inherited_methods=None,
include_protected_methods=None,
include_private_methods=None,
include_staticmethods=None,
include_classmethods=None,
expand_model_params=None,
model_expansion_max_depth=None,
abbreviation_scope=None,
executable_flags=None,
help_option_sort=None,
help_subcommand_sort=None,
help_group=None,
method_skips=None,
)[source]

Register a function, class, instance, or command group.

Per-command options override parser defaults for this command only. If name is omitted, the CLI name is derived from the command target. description, aliases, pipe_targets, and help_group customize the public CLI surface without changing the underlying callable.

Raises:

  • DuplicateCommandError – If the command name or alias already exists.

  • InvalidCommandError – If command cannot be converted to a CLI command.

  • ConfigurationError – If an override is invalid.

command(
name=None,
description=None,
aliases=None,
pipe_targets=None,
include_inherited_methods=None,
include_protected_methods=None,
include_private_methods=None,
include_staticmethods=None,
include_classmethods=None,
expand_model_params=None,
model_expansion_max_depth=None,
abbreviation_scope=None,
executable_flags=None,
help_option_sort=None,
help_subcommand_sort=None,
help_group=None,
method_skips=None,
)[source]

Return a decorator that registers a function or class as a command.

Options passed to the decorator override parser defaults for the decorated target only. The decorated object is returned unchanged.

add_group(
group,
name=None,
description=None,
aliases=None,
include_inherited_methods=None,
include_protected_methods=None,
include_private_methods=None,
include_staticmethods=None,
include_classmethods=None,
expand_model_params=None,
model_expansion_max_depth=None,
abbreviation_scope=None,
executable_flags=None,
help_option_sort=None,
help_subcommand_sort=None,
help_group=None,
method_skips=None,
)[source]

Register an explicit command group.

Group options override parser defaults for commands created from this group. If name is omitted, the CLI name is derived from the group. description, aliases, and help_group customize how the group is presented in generated help and command resolution.

Raises:

  • DuplicateCommandError – If the group name or alias already exists.

  • ConfigurationError – If an override is invalid.

get_commands()[source]

Return registered command schemas in insertion order.

get_command_by_cli_name(cli_name)[source]

Resolve a registered command by CLI name or alias.

Raises:

InvalidCommandError – If cli_name does not resolve to a registered command.

get_args()[source]

Read the current process arguments excluding the executable name.

exit(code)[source]

Exit the process or return code, depending on parser settings.

pipe_to(
targets,
*,
command=None,
subcommand=None,
**normalization_kwargs,
)[source]

Configure stdin pipe routing for the parser or a command.

Without command, the targets become parser defaults. With command and optionally subcommand, they apply only to that command path. normalization_kwargs are passed through to pipe-target normalization.

Raises:

ConfigurationError – If the pipe target declaration is invalid.

read_piped_input()[source]

Read stdin data when available.

reset_piped_input()[source]

Clear cached stdin data.

parser_from_command(command, main=False)[source]

Build a backend parser from an inspected command.

main tells the backend to build the command as the root parser rather than as a nested command parser.

Raises:

InvalidCommandError – If command is not a supported inspected object.

parse_args(args=None)[source]

Parse CLI arguments into a command argument mapping.

If Beyond sys.argv is omitted, the current process arguments are used.

run(*commands, args=None)[source]

Register any command targets, parse arguments, and execute the selection.

Returns the command result unless execution exits through the configured backend. If Beyond sys.argv is omitted, the current process arguments are used.

parser_from_function(
function,
parser=None,
taken_flags=None,
)[source]

Build a backend parser for an inspected function.

Existing parser and flag reservations are used by backends that build nested or shared argparse parsers.

parser_from_class(cls, parser=None, subparser=None)[source]

Build a backend parser for an inspected class.

Existing parser objects are used by backends that populate nested argparse parser trees.

parser_from_multiple_commands(*commands)[source]

Build a backend parser from multiple command targets.

install_tab_completion(parser)[source]

Install tab completion for a backend parser when supported.

build_parser()[source]

Build the backend parser for registered commands.

build_parser_schema()[source]

Build the parser schema for registered commands.

get_last_schema()[source]

Return the most recently built parser schema, if any.

log(message)[source]

Write an informational parser log message.

log_error(message)[source]

Write an error parser log message.

log_exception(e)[source]

Write an exception parser log message.

log_interrupt()[source]

Write the configured interrupt log message.