argparse-tui

Classes

TuiAction

TuiAction(
    option_strings: list[str],
    dest: str = argparse.SUPPRESS,
    default: Any = argparse.SUPPRESS,
    help: str | None = "Open Textual UI.",
    const: str | None = None,
    metavar: str | None = None,
    parent_parser: ArgumentParser | None = None,
    **_kwargs: Any
)

argparse Action that will analyze the parser and display a TUI.

When this action is triggered during argument parsing, it will launch a Textual UI for the parser. This allows adding a '--tui' flag to any argparse-based CLI to provide an interactive interface.

PARAMETER	DESCRIPTION
option_strings	The command-line flags that trigger this action TYPE: list[str]
dest	The attribute name to store the result in TYPE: str DEFAULT: SUPPRESS
default	The default value if the argument is not present TYPE: Any DEFAULT: SUPPRESS
help	The help text for this argument TYPE: str | None DEFAULT: 'Open Textual UI.'
const	The constant value for this action TYPE: str | None DEFAULT: None
metavar	The name to use in usage messages TYPE: str | None DEFAULT: None
parent_parser	The parent parser if this is in a subparser TYPE: ArgumentParser | None DEFAULT: None

Examples:

import argparse
from argparse_tui import TuiAction

parser = argparse.ArgumentParser()
parser.add_argument("--tui", action=TuiAction)
parser.print_usage()

Source code in src/argparse_tui/argparse.py

def __init__(
    self,
    option_strings: list[str],
    dest: str = argparse.SUPPRESS,
    default: Any = argparse.SUPPRESS,
    help: str | None = "Open Textual UI.",  # pylint: disable=redefined-builtin # noqa: A002
    const: str | None = None,
    metavar: str | None = None,
    parent_parser: argparse.ArgumentParser | None = None,
    **_kwargs: Any,
):
    super().__init__(
        option_strings=option_strings,
        dest=dest,
        default=default,
        nargs=0,
        help=help,
        const=const,
        metavar=metavar,
    )
    self._parent_parser = parent_parser

Functions

add_tui_argument

add_tui_argument(
    parser: ArgumentParser,
    parent_parser: ArgumentParser | None = None,
    option_strings: str | list[str] | None = None,
    help: str = "Open Textual UI.",
    default=argparse.SUPPRESS,
    **kwargs
) -> None

Add a TUI argument to an existing argparse parser.

This function adds a flag (like --tui) to the parser that, when specified, will launch a Textual UI for configuring the command arguments.

PARAMETER	DESCRIPTION
parser	The argparse parser to add the argument to TYPE: ArgumentParser
parent_parser	The parent of the given parser, if this is a subparser TYPE: ArgumentParser | None DEFAULT: None
option_strings	List of CLI flags that will invoke the TUI (default: --tui) TYPE: str | list[str] | None DEFAULT: None
help	Help text for the TUI argument TYPE: str DEFAULT: 'Open Textual UI.'
default	Default value for the argument DEFAULT: SUPPRESS
**kwargs	Additional keyword arguments passed to parser.add_argument(...) DEFAULT: {}

Examples:

import argparse
from argparse_tui import add_tui_argument

parser = argparse.ArgumentParser()
add_tui_argument(parser)
parser.print_usage()

Source code in src/argparse_tui/argparse.py

def add_tui_argument(
    parser: argparse.ArgumentParser,
    parent_parser: argparse.ArgumentParser | None = None,
    option_strings: str | list[str] | None = None,
    help: str = "Open Textual UI.",  # pylint: disable=redefined-builtin # noqa: A002
    default=argparse.SUPPRESS,
    **kwargs,
) -> None:
    """Add a TUI argument to an existing argparse parser.

    This function adds a flag (like --tui) to the parser that, when specified,
    will launch a Textual UI for configuring the command arguments.

    Args:
        parser: The argparse parser to add the argument to
        parent_parser: The parent of the given parser, if this is a subparser
        option_strings: List of CLI flags that will invoke the TUI (default: --tui)
        help: Help text for the TUI argument
        default: Default value for the argument
        **kwargs: Additional keyword arguments passed to `parser.add_argument(...)`

    Examples:
    ```python
    import argparse
    from argparse_tui import add_tui_argument

    parser = argparse.ArgumentParser()
    add_tui_argument(parser)
    parser.print_usage()
    ```
    """
    if not option_strings:
        option_strings = [f"--{DEFAULT_COMMAND_NAME.replace('_', '-').lstrip('-')}"]
    elif isinstance(option_strings, str):
        option_strings = [option_strings]

    parser.add_argument(
        *option_strings,
        action=TuiAction,
        default=default,
        help=help,
        parent_parser=parent_parser,
        **kwargs,
    )

add_tui_command

add_tui_command(
    parser: ArgumentParser,
    command: str = DEFAULT_COMMAND_NAME,
    help: str = "Open Textual UI.",
    **kwargs: Any
) -> argparse._SubParsersAction

Add a TUI subcommand to an existing argparse parser.

This function adds a subcommand (like 'tui') to the parser that, when invoked, will launch a Textual UI for configuring the command arguments. This is useful for CLI applications that want to offer both command-line and TUI interfaces.

PARAMETER	DESCRIPTION
parser	The argparse parser to add the subcommand to TYPE: ArgumentParser
command	Name of the CLI command that will invoke the TUI (default=tui) TYPE: str DEFAULT: DEFAULT_COMMAND_NAME
help	Help message for the subcommand TYPE: str DEFAULT: 'Open Textual UI.'
**kwargs	If subparsers do not already exist, create with these kwargs TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
_SubParsersAction	The Argparse subparsers action that was discovered or created

Examples:

import argparse
from argparse_tui import add_tui_command

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers()
add_tui_command(parser)
parser.print_usage()

Source code in src/argparse_tui/argparse.py

def add_tui_command(
    parser: argparse.ArgumentParser,
    command: str = DEFAULT_COMMAND_NAME,
    help: str = "Open Textual UI.",  # pylint: disable=redefined-builtin # noqa: A002
    **kwargs: Any,
) -> argparse._SubParsersAction:
    """Add a TUI subcommand to an existing argparse parser.

    This function adds a subcommand (like 'tui') to the parser that, when invoked,
    will launch a Textual UI for configuring the command arguments. This is useful
    for CLI applications that want to offer both command-line and TUI interfaces.

    Args:
        parser: The argparse parser to add the subcommand to
        command: Name of the CLI command that will invoke the TUI (default=`tui`)
        help: Help message for the subcommand
        **kwargs: If subparsers do not already exist, create with these kwargs

    Returns:
        The Argparse subparsers action that was discovered or created

    Examples:
    ```python
    import argparse
    from argparse_tui import add_tui_command

    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers()
    add_tui_command(parser)
    parser.print_usage()
    ```
    """

    subparsers: argparse._SubParsersAction
    if parser._subparsers is None:
        subparsers = parser.add_subparsers(**kwargs)
    else:
        for action in parser._actions:
            if isinstance(action, argparse._SubParsersAction):
                subparsers = action
                break

    tui_parser = subparsers.add_parser(
        command,
        description=argparse.SUPPRESS,
        help=help,
    )

    add_tui_argument(
        tui_parser,
        parent_parser=parser,
        option_strings=[command],
    )

    return subparsers

build_tui

build_tui(
    parser: ArgumentParser,
    cli_args: Sequence[str] | None = None,
    subparser_ignorelist: (
        list[ArgumentParser] | None
    ) = None,
) -> App

Build a Textual UI (TUI) given an argparse parser.

Creates a Textual App that presents a form-based interface for the given argparse parser. The TUI allows users to interactively set argument values through a user-friendly interface instead of command line flags.

PARAMETER	DESCRIPTION
parser	The argparse parser to build a TUI for TYPE: ArgumentParser
cli_args	Arguments parsed for pre-populating the TUI form fields TYPE: Sequence[str] | None DEFAULT: None
subparser_ignorelist	List of subparsers to exclude from the TUI TYPE: list[ArgumentParser] | None DEFAULT: None

RETURNS	DESCRIPTION
App	A Textual App instance

Examples:

from argparse_tui import build_tui

import argparse
import textual

parser = argparse.ArgumentParser(prog="awesome-app")

parser.add_argument("--value")

app = build_tui(parser)

assert isinstance(app, textual.app.App)

Source code in src/argparse_tui/argparse.py

def build_tui(
    parser: argparse.ArgumentParser,
    cli_args: Sequence[str] | None = None,
    subparser_ignorelist: list[argparse.ArgumentParser] | None = None,
) -> App:
    """Build a Textual UI (TUI) given an argparse parser.

    Creates a Textual App that presents a form-based interface for the given
    argparse parser. The TUI allows users to interactively set argument values
    through a user-friendly interface instead of command line flags.

    Args:
        parser: The argparse parser to build a TUI for
        cli_args: Arguments parsed for pre-populating the TUI form fields
        subparser_ignorelist: List of subparsers to exclude from the TUI

    Returns:
        A Textual App instance

    Examples:
    ```python
    from argparse_tui import build_tui

    import argparse
    import textual

    parser = argparse.ArgumentParser(prog="awesome-app")

    parser.add_argument("--value")

    app = build_tui(parser)

    assert isinstance(app, textual.app.App)
    ```
    """

    subcmd_args: list[str] = []
    parsed_args: dict[str, str] = {}

    if cli_args:
        # Make all args optional
        def _set_actions_optional(
            parser,
            cli_args: list[str] | None = None,
            subcmd_args: list[str] | None = None,
        ) -> list[str]:
            # Update arguments
            for action in parser._actions:
                action.required = False

            # Update subparsers
            sp_actions = parser._subparsers._actions if parser._subparsers else []
            for sp_action in sp_actions:
                sp_action.required = False
                if isinstance(sp_action, argparse._SubParsersAction):
                    found_subcmd: bool = False
                    for subcmd, subparser in sp_action.choices.items():
                        if found_subcmd:
                            _set_actions_optional(subparser)
                            continue

                        try:
                            if not cli_args:
                                raise ValueError
                            subcmd_index: int = cli_args.index(subcmd)
                        except ValueError:
                            _set_actions_optional(subparser)
                        else:
                            found_subcmd = True
                            subcmd_args.append(subcmd)
                            _set_actions_optional(
                                subparser,
                                cli_args=cli_args[(subcmd_index + 1) :],
                                subcmd_args=subcmd_args,
                            )

            return subcmd_args

        parser_copy: argparse.ArgumentParser = deepcopy(parser)
        subcmd_args = _set_actions_optional(
            parser_copy,
            cli_args=cli_args,
            subcmd_args=[],
        )

        with suppress(SystemExit):
            namespace, unknown_args = parser_copy.parse_known_args(cli_args)
            parsed_args: dict[str, str | list[str]] = vars(namespace)
            parsed_args["__unknown_args__"] = unknown_args

    schemas = introspect_argparse_parser(
        parser,
        subparser_ignorelist=subparser_ignorelist,
        value_overrides=parsed_args,
    )

    return Tui(schemas, app_name=parser.prog, subcommand_filter=subcmd_args)

invoke_tui

invoke_tui(
    parser: ArgumentParser,
    cli_args: Sequence[str] | None = None,
    subparser_ignorelist: (
        list[ArgumentParser] | None
    ) = None,
) -> None

Invoke a Textual UI (TUI) given an argparse parser.

Builds and runs a TUI for the given argparse parser. This is a convenience function that combines build_tui() and app.run() in one call.

PARAMETER	DESCRIPTION
parser	The argparse parser to create a TUI for TYPE: ArgumentParser
cli_args	Arguments parsed for pre-populating the TUI form fields TYPE: Sequence[str] | None DEFAULT: None
subparser_ignorelist	List of subparsers to exclude from the TUI TYPE: list[ArgumentParser] | None DEFAULT: None

Examples:

import argparse
from argparse_tui import invoke_tui

parser = argparse.ArgumentParser(prog="awesome-app")

parser.add_argument("--value")

# invoke_tui(parser)

Source code in src/argparse_tui/argparse.py

def invoke_tui(
    parser: argparse.ArgumentParser,
    cli_args: Sequence[str] | None = None,
    subparser_ignorelist: list[argparse.ArgumentParser] | None = None,
) -> None:
    """Invoke a Textual UI (TUI) given an argparse parser.

    Builds and runs a TUI for the given argparse parser. This is a convenience
    function that combines build_tui() and app.run() in one call.

    Args:
        parser: The argparse parser to create a TUI for
        cli_args: Arguments parsed for pre-populating the TUI form fields
        subparser_ignorelist: List of subparsers to exclude from the TUI

    Examples:
    ```python
    import argparse
    from argparse_tui import invoke_tui

    parser = argparse.ArgumentParser(prog="awesome-app")

    parser.add_argument("--value")

    # invoke_tui(parser)
    ```
    """
    app: App = build_tui(
        parser=parser,
        cli_args=cli_args,
        subparser_ignorelist=subparser_ignorelist,
    )
    app.run()