Schema¶

Parser Schema¶

CommandType¶: alias of Literal[‘function’, ‘method’, ‘class’, ‘group’, ‘instance’]

class ArgumentKind[source]¶

Classification of how a CLI argument is provided.

__new__(value)¶

class ValueShape[source]¶

Shape of a parameter’s parsed value.

__new__(value)¶

class BooleanBehavior[source]¶

Metadata for boolean flags and their defaults.

supports_negative¶

Whether a negative form is generated.

Type:: bool

negative_form¶

Negative flag form (e.g., “–no-flag”) if any.

Type:: str | None

default¶

Effective default value for the flag. Can be argparse.SUPPRESS (a str sentinel) to suppress the default.

Type:: bool | str | None

class ExecutableFlag[source]¶: Zero-argument executable CLI flag that short-circuits normal command execution.

class Argument[source]¶

Schema entry describing a single CLI argument.

name¶

Canonical parameter name.

Type:: str

display_name¶

CLI-facing name or path.

Type:: str

kind¶

Whether the argument is positional or optional.

Type:: ArgumentKind

value_shape¶

Expected value shape for parsing.

Type:: ValueShape

flags¶

CLI flags or positional name display.

Type:: tuple[str, …]

required¶

Whether the argument must be provided.

Type:: bool

default¶

Default value or argparse sentinel.

Type:: Any

help¶

Help text for display.

Type:: str | None

type¶

Parsed element type when applicable.

Type:: type[Any] | None

parser¶

Parser for converting raw strings.

Type:: Callable[[str], Any] | None

metavar¶

Custom metavar for help display.

Type:: str | None

nargs¶

Argparse nargs specifier.

Type:: str | int | None

boolean_behavior¶

Boolean flag behavior details.

Type:: BooleanBehavior | None

choices¶

Allowed values, if any.

Type:: Sequence[Any] | None

accepts_stdin¶

Whether stdin can supply this value.

Type:: bool

pipe_required¶

Whether stdin is required for this value.

Type:: bool

tuple_element_parsers¶

Per-element parsers.

Type:: tuple[Callable[[str], Any], …] | None

is_expanded_from¶

Root model field name if expanded.

Type:: str | None

expansion_path¶

Nested path for expanded model fields.

Type:: tuple[str, …]

original_model_type¶

Model type expanded into flags.

Type:: type | None

parent_is_optional¶

Whether an ancestor model is optional.

Type:: bool

model_default¶

Default model instance or sentinel.

Type:: Any

is_help_action¶

Whether this argument is the parser’s built-in help action.

Type:: bool

value_plan¶

Internal conversion plan for nested values.

Type:: ArgumentValue | None

class Command[source]¶

Schema entry describing a CLI command and its parameters.

obj¶

Inspected callable backing the command.

Type:: Class | Function | Method | None

canonical_name¶

Canonical command name.

Type:: str

cli_name¶

CLI-facing command name.

Type:: str

aliases¶

Alternative CLI names.

Type:: tuple[str, …]

raw_description¶

Raw docstring description.

Type:: str | None

help_group¶

Optional help-only grouping label for command listings.

Type:: str | None

help_layout¶

Help layout used for formatting.

Type:: HelpLayout | None

pipe_targets¶

Pipe target configuration for stdin.

Type:: PipeTargets | None

parameters¶

Argument specs for command parameters.

Type:: list[Argument]

initializer¶

Argument specs for class initialization.

Type:: list[Argument]

subcommands¶

Nested subcommands, if any.

Type:: dict[str, Command] | None

executable_flags¶

Zero-argument executable flags.

Type:: list[ExecutableFlag]

raw_epilog¶

Raw epilog text for help output.

Type:: str | None

command_type¶

Command category.

Type:: CommandType

is_leaf¶

Whether this command has no subcommands.

Type:: bool

is_instance¶

Whether the command comes from a stored instance.

Type:: bool

parent_path¶

Command path for nested groups.

Type:: tuple[str, …]

stored_instance¶

Stored instance for instance commands.

Type:: object | None

property description: str | None¶: Return the formatted description for help output.

property epilog: str | None¶: Return the formatted epilog for help output.

class ParserSchema[source]¶

Schema container for a complete CLI parser.

raw_description¶

Raw description string.

Type:: str | None

raw_epilog¶

Raw epilog string.

Type:: str | None

commands¶

Command definitions keyed by canonical name.

Type:: dict[str, Command]

command_key¶

Key used for command selection in parsed args.

Type:: str | None

allow_args_from_file¶

Whether args can be read from files.

Type:: bool

pipe_targets¶

Default pipe target configuration.

Type:: PipeTargets | None

theme¶

Help layout for formatting.

Type:: HelpLayout

commands_help¶

Pre-rendered command listing help.

Type:: str | None

metadata¶

Additional parser metadata.

Type:: dict[str, Any]

executable_flags¶

Parser-root executable flags.

Type:: list[ExecutableFlag]

help_option_sort_effective¶

Effective root option sort.

Type:: list[HelpOptionSortRule] | None

property description: str | None¶: Return the formatted parser description.

property epilog: str | None¶: Return the formatted parser epilog.

property is_multi_command: bool¶: Whether the schema contains multiple top-level commands.

get_command(canonical_name)[source]¶

Return the command definition for a canonical name.

Parameters:: canonical_name (str) – Canonical command name.

property canonical_names: Sequence[str]¶: Return the canonical command names in schema order.

Pipe Input¶

PipePriority¶: alias of Literal[‘cli’, ‘pipe’]

class PipeTargets[source]¶

Configuration for routing stdin content to parameters.

targets¶

Ordered parameter names that receive piped chunks. The order defines how chunks map to parameters.

Type:: tuple[str, …]

delimiter¶

Chunk delimiter. If None, chunking uses line breaks. If more than one target is set and the delimiter is not explicitly provided, a newline is assumed by default.

Type:: str | None

priority¶

Conflict resolution policy. - "cli" keeps explicit CLI arguments and only fills missing ones from the pipe. - "pipe" overwrites CLI values with piped data.

Type:: PipePriority

allow_partial¶

If True, fewer chunks than targets are allowed. Missing chunks become None and are ignored unless the parameter is required.

Type:: bool

targeted_parameters()[source]¶

Return the set of configured target parameter names.

TargetsInput = interfacy.pipe.PipeTargets | str | collections.abc.Sequence[str] | dict[str, typing.Any]¶

Represent a PEP 604 union type

E.g. for int | str

build_pipe_targets_config( targets, *, delimiter=DELIMITER_UNSET, allow_partial=None, priority=None, )[source]¶

Build a normalized PipeTargetsConfig from user input.

This function accepts multiple declaration styles:

Existing PipeTargetsConfig to optionally override fields.
A string or sequence of parameter names.
A dict with keys:
- parameters or bindings: the target names.
- delimiter: optional chunk delimiter.
- allow_partial: optional boolean.
- priority: ‘cli’ or ‘pipe’

If more than one target is provided and no delimiter is explicitly set, a newline is used by default.