CLI

Utilitary module to interact with the CLI. This holds the basic implementation that is reused across commands and other interactions.

Example

>>> from command_line_assistant.commands.cli import CommandContext, argument, command

>>> @command("hello", help="A simple command that prints 'Hello, friend')
>>> @argument("-n", "--name", nargs="?", help="Your name goes in here.")
>>> ...
>>> def hello_friend(args: Namespace, context: CommandContext) -> int:
>>>     if args.name:
>>>         print(f"Hello, {args.name}")
>>>     else:
>>>         print("Hello, friend")

```

class Command(name, func, help=None, description=None)

Represents a single CLI command.

Initialize a new command.

Parameters:

• name (str) – Command name

• func (CommandFunc) – Command function

• help (Optional[str], optional) – Short help message. Defaults to None.

• description (Optional[str], optional) – Longer description. Defaults to None.

_create_wrapper()

Create a wrapper function for the command.

Return type:

Callable[[Namespace], Any]

Returns:

Wrapper function

register(parser)

Register this command with the argument parser.

Return type:

None

Parameters:

parser (_SubParsersAction) – Subparser to register with

class CommandContext(username='docs', effective_user_id=1005, os_release=<factory>)

A context for all commands with useful information.

Note

This is meant to be initialized exclusively by the client.

username

The username of the current user.

Type:

str

effective_user_id

The effective user id.

Type:

int

os_release

A dictionary with the OS release information.

Type:

dict[str, str]

effective_user_id: int = 1005

os_release: dict[str, str]

username: str = 'docs'

_subcommand_used(args)

Return what subcommand has been used by the user. Return None if no subcommand has been used.

Return type:

Optional[str]

Parameters:

args (list[str]) – The arguments from the command line

Returns:

If we find a match for the argument, we return it, otherwise we return None.

Return type:

Optional[str]

add_default_command(stdin, argv)

Add the default command when none is given

Return type:

list[str]

Parameters:

• stdin (str) – The input string coming from stdin

• argv (list[str]) – List of arguments from CLI

Returns:

return list of commands (or default command).

Return type:

list[str]

argument(*args, **kwargs)

Decorator to add arguments to a command.

Return type:

Callable[[Callable[[Namespace, CommandContext], int]], Callable[[Namespace, CommandContext], int]]

Parameters:

• *args – Positional argument names

• **kwargs – Argument options

Returns:

Decorator function

command(name, help=None, description=None)

Decorator to register a command function.

Return type:

Callable[[Callable[[Namespace, CommandContext], int]], Command]

Parameters:

• name (str) – Command name

• help (Optional[str], optional) – Short help text

• description (Optional[str], optional) – Longer description

Returns:

Decorator function

Return type:

Callable[[CommandFunc], CommandFunc]

create_argument_parser()

Create the argument parser for command line assistant.

Return type:

tuple[ArgumentParser, _SubParsersAction]

Returns:

The parent and subparser created

Return type:

tuple[ArgumentParser, SubParsersAction]

create_subparser(parser, name, help)

Create a subparser with some default options

Return type:

ArgumentParser

Parameters:

• parser (SubParsersAction) – The parent subparser to be used

• name (str) – The name of the new custom subparser

• help (str) – The help message to be displayed with the subparser

Returns:

A new instance of a ArgumentParser to be used as a command.

Return type:

ArgumentParser

read_stdin()

Parse the std input when a user give us.

Return type:

str

For example, consider the following scenario:

>>> echo "how to run podman?" | c

Or a more complex one

>>> cat error-log | c "How to fix this?"

Returns:

Return the stdin that was read or if there is nothing, return an empty string.

Return type:

str

register_all_commands(parser, commands)

Register all commands with the parser.

Return type:

None

Parameters:

parser (_SubParsersAction) – Subparser to register commands with