GitHub

completions

API reference for completions.

Shell completion scripts for a command tree (Effect's Completions): generate(name, shell, descriptor) with from_command(command) gives the script --completions <shell> prints.

Types

TypeDefinitionDescription
Shelltype Shell = Literal['bash', 'zsh', 'fish', 'powershell']
ArgumentTypetype ArgumentType = Literal['String', 'Int', 'Finite', 'Date'] | Choice | PathKind
FlagTypetype FlagType = ScalarTag | Choice | PathKind

Classes

Functions

generate

generate(executable, shell, descriptor) -> str
ParameterTypeDescription
executablestr
shellShell
descriptorCommandDescriptor

Returns str

def generate(executable: str, shell: Shell, descriptor: CommandDescriptor) -> str:
    return _GENERATORS[shell](executable, descriptor)

from_command

from_command(command, inherited=()) -> CommandDescriptor

The descriptor of command and its listed subcommands; local flags come first, then the shared flags of its ancestors.

ParameterTypeDescription
commandCommand[Any, Any, Any, Any]
inheritedSequence[Param[Any]] = ()

Returns CommandDescriptor

def from_command(
    command: Command[Any, Any, Any, Any], inherited: Sequence[Param[Any]] = ()
) -> CommandDescriptor:
    """The descriptor of ``command`` and its listed subcommands; local
    flags come first, then the shared flags of its ancestors."""
    state = command.state
    own = state.config.flags
    flags: list[FlagDescriptor] = []
    seen: set[str] = set()
    for index, flag in enumerate((*own, *inherited)):
        for single, repeatable in _repeatable_singles(flag):
            if single.kind != FLAG or single.hidden:
                continue
            if index >= len(own) and single.name in seen:
                continue
            seen.add(single.name)
            flags.append(
                FlagDescriptor(
                    name=single.name,
                    aliases=single.aliases,
                    description=single.description,
                    type=_value_type(single),
                    optional_value=single.optional_value is not None,
                    negation=single.negation,
                    repeatable=repeatable,
                )
            )
    arguments: list[ArgumentDescriptor] = []
    for arg in state.config.arguments:
        metadata = arg.metadata()
        for single in arg.singles():
            if single.kind != ARGUMENT:
                continue
            arguments.append(
                ArgumentDescriptor(
                    name=single.name,
                    description=single.description,
                    required=not metadata.is_optional
                    and (not metadata.is_variadic or (metadata.variadic_min or 0) > 0),
                    variadic=metadata.is_variadic,
                    type=_argument_type(single),
                )
            )
    shared = (*inherited, *state.context_config.flags)
    subcommands: list[CommandDescriptor] = []
    for group in command.subcommands:
        for sub in group.commands:
            if sub.unlisted:
                continue
            descriptor = from_command(sub, shared)
            subcommands.append(descriptor)
            if sub.alias and sub.alias != sub.name:
                subcommands.append(replace(descriptor, name=sub.alias))
    return CommandDescriptor(
        name=command.name,
        description=(
            command.description if command.short_description is None else command.short_description
        ),
        flags=tuple(flags),
        arguments=tuple(arguments),
        subcommands=tuple(subcommands),
    )

Modules