CLI API

The CLI API provides decorators and classes for building command-line interfaces.

Core Components

Decorators

Decorator for defining CLI commands.

Command

Decorator for defining a command in the CLI engine.

This decorator is used to register a function as a command that can be executed from the command line interface. It supports two types of commands:

• BasicCLI: Single command with one execute() method that handles the command execution. Can have optional arguments and positional arguments.

• GenericCLI: Multi-command (group command) that can have multiple functions for different subcommands. Has one base argument (the name of the GenericCLI) and one positional argument (subcommand) that can have multiple positional arguments.

__init__

__init__(name: str | None = None, description: str = '', help: str | None = '', **kwargs)

@Command decorator's constructor

Parameters:

Name	Type	Description	Default
name	str | None	The name of the command. If None, the class name will be used.	None
description	str	A brief description of the command.	''
help	str | None	Detailed help text for the command.	''
**kwargs		Additional keyword arguments to store as metadata.	{}

Handler

__init__

__init__(*names: str, description: str | None = None, **kwargs) -> None

@Handler decorator's constructor

Parameters:

Name	Type	Description	Default
*names	str	One or more names for the handler.	()
description	str | None	A brief description of the handler. Defaults to None.	None

Proxies of CLI command types

BasicCLI

A base proxy class for defining basic CLI commands.

For more details please refer to BasicCLI Overview Documentation and BasicCLI Examples.

execute

execute() -> None

Method to be implemented by subclasses to execute the command logic.

Raises:

Type	Description
NotImplementedError	If the method is not implemented by a subclass.

GenericCLI

A base proxy class for defining generic CLI commands.

Generic CLI can have multiple subcommands defined as methods that are wrapped by @Handler(...) decorator.

For more details please refer to GenericCLI Overview Documentation and GenericCLI Examples.

Parameters & Annotation Utilities

Each CLI argument can be configured as pure basic python annotations aren't enough for customizing CLI command. So Ascender Framework provides a few Field metadata functions with which you can annotate your arguments and configure them.

Parameter

Parameter(default: T | UndefinedValue | None = ...) -> T | Any

Parameter(default: T | UndefinedValue | None = ..., *, names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None) -> T | Any

Parameter(default: T | UndefinedValue | None = ..., *, names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None, action: Annotated[Literal['store'] | None, Doc('The action to be taken when the argument is encountered')] = None, nargs: Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')] = None) -> T | Any

Parameter(default: T | UndefinedValue | None = ..., *, names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None, action: Annotated[Literal['store_const'] | None, Doc('The action to be taken when the argument is encountered')] = None, nargs: Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')] = None, const: Annotated[str | None, Doc('The default value that will be used for valueless flags.')] = None, dest: Annotated[str | None, Doc('The name of the attribute to be used in the application.')] = None) -> T | Any

Parameter(default: T | UndefinedValue | None = ..., *, default_factory: Annotated[Callable[[], T] | None, Doc('A callable that returns the default value for the argument')] = ..., names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None, action: Annotated[Literal['store_const'] | None, Doc('The action to be taken when the argument is encountered')] = None, nargs: Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')] = None, const: Annotated[str | None, Doc('The default value that will be used for valueless flags.')] = None, dest: Annotated[str | None, Doc('The name of the attribute to be used in the application.')] = None) -> T | Any

Parameter(default: T | UndefinedValue | None = ..., *, names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None, action: Annotated[Literal['store'] | None, Doc('The action to be taken when the argument is encountered')] = None, nargs: Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')] = None, const: Annotated[str | None, Doc('The default value that will be used for valueless flags.')] = None, dest: Annotated[str | None, Doc('The name of the attribute to be used in the application.')] = None, metavar: Annotated[str | None, Doc('The name of the argument in the help message.')] = None, **kwargs: Any) -> T | Any

Parameter(default: T | UndefinedValue | None = ..., *, names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None, action: Annotated[Literal['append', 'extend'] | None, Doc('The action to be taken when the argument is encountered')] = None, nargs: Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')] = None, const: Annotated[str | None, Doc('The default value that will be used for valueless flags.')] = None, dest: Annotated[str | None, Doc('The name of the attribute to be used in the application.')] = None, metavar: Annotated[str | None, Doc('The name of the argument in the help message.')] = None, **kwargs: Any) -> T | Any

Parameter(default: Annotated[Any, Doc('The default value for the argument')] = UndefinedValue, *, default_factory: Annotated[Callable[[], T] | None, Doc('A callable that returns the default value for the argument')] = None, names: list[str] | None = None, description: Annotated[str | None, Doc('A brief description of the argument (used for help)')] = None, action: Annotated[str | None, Doc('The action to be taken when the argument is encountered')] = None, nargs: Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')] = None, const: Annotated[str | None, Doc('The default value that will be used for valueless flags.')] = None, dest: Annotated[str | None, Doc('The name of the attribute to be used in the application.')] = None, metavar: Annotated[str | None, Doc('The name of the argument in the help message.')] = None, **kwargs: Any) -> Any

A parameter annotation to define a command line parameter for an application. This decorator can be used to specify various attributes of the parameter, such as its default value, names, description, action, and more.

Parameters:

Name	Type	Description	Default
default	Annotated[Any, Doc('The default value for the argument')]	The default value for the argument.	UndefinedValue
default_factory	Annotated[Callable[[], T] | None, Doc('A callable that returns the default value for the argument')]	A callable that returns the default value for the argument.	None
names	list[str] | None	A list of names or flags for the argument.	None
description	Annotated[str | None, Doc('A brief description of the argument (used for help)')]	A brief description of the argument (used for help).	None
action	Annotated[str | None, Doc('The action to be taken when the argument is encountered')]	The action to be taken when the argument is encountered.	None
nargs	Annotated[int | str | None, Doc('Limit the amount number of the arguments to a specific amount.')]	Limit the amount number of the arguments to a specific amount.	None
const	Annotated[str | None, Doc('The default value that will be used for valueless flags.')]	The default value that will be used for valueless flags.	None
dest	Annotated[str | None, Doc('The name of the attribute to be used in the application.')]	The name of the attribute to be used in the application.	None
metavar	Annotated[str | None, Doc('The name of the argument in the help message.')]	The name of the argument in the help message.	None
**kwargs	Any	Additional keyword arguments for further customization.	{}

BooleanParameter

BooleanParameter(default: bool = False) -> bool

BooleanParameter(default: bool = False, *, description: str | None = None, flags: list[str] | None = None) -> bool

BooleanParameter(default: bool = False, *, description: str | None = None, flags: list[str] | None = None) -> Any

Create a boolean flag parameter for the CLI engine.

Parameters:

Name	Type	Description	Default
default	bool	The default value for the boolean flag. Defaults to False.	False
description	str | None	A brief description of the flag (used for help	None
flags	list[str] | None	A list of flag names (e.g., ["--verbose", "-v"]).	None

ConstantParameter

ConstantParameter(const: Any, default: T | None = UndefinedValue) -> T

ConstantParameter(const: Any, default: T | None = UndefinedValue, *, description: str | None = None, flags: list[str] | None = None, dest: str | None = None, metavar: str | None = None) -> T

ConstantParameter(const: Any, default: Any | None = UndefinedValue, *, description: str | None = None, flags: list[str] | None = None, dest: str | None = None, metavar: str | None = None) -> Any

Create a boolean flag parameter for the CLI engine. If CLI will get value as --flag it will be set to True, otherwise it will be set to False.

Parameters:

Name	Type	Description	Default
const	Any	The constant value to be used when the flag is provided.	required
default	Any | None	The default value if the flag is not provided. Defaults to UndefinedValue.	UndefinedValue
description	str | None	A brief description of the argument (used for help). Defaults to None.	None
flags	list[str] | None	One or more flag names (e.g., ["--my-flag"]). Defaults to None.	None
dest	str | None	The name of the attribute to be used in the application. Defaults to None.	None
metavar	str | None	The name to be used in usage messages. Defaults to None.	None

UndefinedValue

A class representing an undefined value in the CLI engine. This can be used to signify that a value has not been set or is not applicable.

Source code in ascender/core/cli_engine/types/undefined.py

class UndefinedValue:
    """
    A class representing an undefined value in the CLI engine.
    This can be used to signify that a value has not been set or is not applicable.
    """
    def __init__(self) -> None:
        raise TypeError("UndefinedValue is an undefined type and cannot be instantiated.")

    def __repr__(self):
        return "UndefinedValue"

    def __bool__(self):
        return False

    def __eq__(self, other):
        return issubclass(other, UndefinedValue) or isinstance(other, UndefinedValue)

    def __ne__(self, other):
        return not self.__eq__(other)

    def __copy__(self):
        raise TypeError("UndefinedValue cannot be copied.")

    def __deepcopy__(self, memo):
        raise TypeError("UndefinedValue cannot be deep copied.")

See Also

• CLI Overview - CLI system overview
• Creating Commands - Detailed command creation guide
• Command Examples - More CLI examples