Command Line Interface¶

Cli Class APIs¶

class okaara.cli.Cli(prompt=None)¶

Representation of the CLI being created. Coders should create an instance of this class as the basis for the CLI. At that point, calling add_* methods will return the nodes/leaves of the CLI tree to further manipulate and create the desired CLI hierarchy.

__weakref__¶: list of weak references to the object (if defined)

add_command(command)¶

Adds a command that may be executed in this section (in other words, a leaf in this node of the CLI tree). Any arguments that were specified after the path used to identify this command will be passed to the command’s execution itself.

Parameters:	command (Command) – command object to add

add_section(section)¶

Adds a new section to the CLI. Users will be able to specify the given name when specifying this section. Doing so will recurse into the section’s subtree to continue parsing for other subsections or commands.

Parameters:	section (Section) – section instance to add

create_command(name, description, method, usage_description=None, parser=None)¶

Creates a new command in this section. The given name must be unique across all commands and subsections within this section. The command instance is returned and can be further edited except for its name.

Commands created in this fashion do not need to be added to this section through the add_command method.

Parameters:	name (str) – trigger that will cause this command to run description (str) – user-readable text describing what happens when running this command; displayed to users in the usage output method (function) – method that will be invoked when this command is run usage_description (str or None) – optional extra text that is only displayed when viewing the full usage of this command parser (OptionParser) – if specified, the remaining arguments to this command as specified by the user will be passed to this object to be handled; the results will be sent to the command’s method
Returns:	instance representing the newly added command
Return type:	Command

create_section(name, description)¶

Creates a new subsection at the root of the CLI. The given name must be unique across all commands and subsections within this section. The section instance is returned and can be further edited except for its name.

Sections created in this fashion do not need to be added through the add_section method.

Parameters:	name (str) – identifies the section description (str) – user-readable text describing the contents of this subsection
Returns:	instance representing the newly added section
Return type:	Section

create_subsection(name, description)¶

Syntactic sugar method that functions identical to create_section.

Return type:	Section

find_command(name)¶

Returns the command under this section with the given name.

Parameters:	name (string) – required; name of the command to find
Returns:	command object for the matching command if it exists; None otherwise
Return type:	Command

find_section(name)¶

Returns the subsection of this section with the given name.

Parameters:	name (string) – required; name of the subsection to find
Returns:	section object for the matching subsection if it exists; None otherwise
Return type:	Section

find_subsection(name)¶: Syntactic sugar method that functions identical to find_section.

print_cli_map(indent=-2, step=2, show_options=False, section_color=None, command_color=None)¶

Prints the structure of the CLI in a tree-like structure to indicate section ownership.

Parameters:

indent (int) – number of spaces to indent each section
step (int) – number of spaces to increment the indent on each iteration into a section
show_options (bool) – if true, command options will be displayed; defaults to false
section_color (str) – if specified, section names will be highlighted with this color
command_color (str) – if specified, command names will be highlighted with this color

remove_command(name)¶

Removes the command with the given name. If no command exists with that name, this call has no effect (no error is raised).

Parameters:	name (str) – name of the command to remove

remove_section(name)¶

Removes the section with the given name. If no section exists with that name, this call has no effect (no error is raised).

Parameters:	name (str) – name of the section when it was added
Returns:	subsection instance of one was removed; None otherwise
Return type:	Section

remove_subsection(name)¶: Syntactic sugar method that functions identical to remove_section.

run(args)¶

Driver for the CLI. The specified arguments will be parsed to determine which command to execute, as well as any arguments to that command’s execution. After assembling the CLI using the add_* calls, this method should be run to do the actual work.

Parameters:	args (list) – defines the command being invoked and any arguments to it
Returns:	exit code as indicated by the command that is executed, suitable for using as the executable exit code
Return type:	int

Section Class APIs¶

class okaara.cli.Section(name, description)¶

Represents a division of commands in the CLI. Sections may contain other sections, which creates a string of arguments used to get to a command (think namespaces).

__weakref__¶: list of weak references to the object (if defined)

add_command(command)¶

Adds a command that may be executed in this section (in other words, a leaf in this node of the CLI tree). Any arguments that were specified after the path used to identify this command will be passed to the command’s execution itself.

Parameters:	command (Command) – command object to add

add_subsection(section)¶

Adds another node to the CLI tree. Users will be able to specify the given name when specifying this section. Doing so will recurse into the subsection’s subtree to continue parsing for other subsections or commands.

Parameters:	section (Section) – section instance to add

create_command(name, description, method, usage_description=None, parser=None)¶

Creates a new command in this section. The given name must be unique across all commands and subsections within this section. The command instance is returned and can be further edited except for its name.

Commands created in this fashion do not need to be added to this section through the add_command method.

Parameters:	name (str) – trigger that will cause this command to run description (str) – user-readable text describing what happens when running this command; displayed to users in the usage output method (function) – method that will be invoked when this command is run usage_description (str or None) – optional extra text that is only displayed when viewing the full usage of this command parser (OptionParser) – if specified, the remaining arguments to this command as specified by the user will be passed to this object to be handled; the results will be sent to the command’s method
Returns:	instance representing the newly added command
Return type:	Command

create_subsection(name, description)¶

Creates a new subsection in this section. The given name must be unique across all commands and subsections within this section. The section instance is returned and can be further edited except for its name.

Sections created in this fashion do not need to be added to this section through the add_section method.

Parameters:	name (str) – identifies the section description (str) – user-readable text describing the contents of this subsection
Returns:	instance representing the newly added section
Return type:	Section

find_command(name)¶

Returns the command under this section with the given name.

Parameters:	name (string) – required; name of the command to find
Returns:	command object for the matching command if it exists; None otherwise
Return type:	Command

find_subsection(name)¶

Returns the subsection of this section with the given name.

Parameters:	name (string) – required; name of the subsection to find
Returns:	section object for the matching subsection if it exists; None otherwise
Return type:	Section

print_section(prompt, indent=0, step=2)¶

Prints the direct children of a single section; this call will not recurse into the children and print their hierarchy.

Parameters:	prompt (Prompt) – required; prompt instance to print to indent (int) – number of spaces to indent each section step (int) – number of spaces to increment the indent on each iteration into a section

remove_command(name)¶

Removes the command with the given name. If there is no command with the given name, this call does nothing (no error is raised).

Parameters:	name (str) – name of the command when it was added
Returns:	command instance if one was removed; None if it didn’t exist
Return type:	Command

remove_subsection(name)¶

Removes the subsection with the given name. If there is no subsection with the given name, this call does nothing (no error is raised).

Parameters:	name (str) – name of the section when it was added
Returns:	subsection instance if one was removed; None if it didn’t exist
Return type:	Section

verify_new_structure(name)¶

Integrity check to validate that the CLI has not been configured with an entity (subsection or command) with the given name.

Raises InvalidStructure:
Parameters:	name (string) – name of the subsection/command to look for
	if there is an entity with the given name

Command Class APIs¶

class okaara.cli.Command(name, description, method, usage_description=None, parser=None)¶

Represents something that should be executed by the CLI. These nodes will be leaves in the CLI tree. Each command is tied to a single python method and will invoke that method with whatever arguments follow it.

__weakref__¶: list of weak references to the object (if defined)

add_flag(flag)¶

Adds a flag that can be specified when executing this command. As Flag is a subclass of Option, this call has the same effect as add_option and is simply included as syntactic sugar for completeness.

Parameters:	flag (Flag) – flag to add to the command

add_option(option)¶

Adds an option that can be specified when executing this command. When executing the command, the user specified arguments to the command are parsed according to options specified in this fashion.

Parameters:	option (Option) – option (or flag) to add to the command

add_option_group(option_group)¶

Adds an option group to the command. Option groups will be rendered in the order they are added.

Parameters:	option_group (OptionGroup) – option group

all_options()¶

Returns a single list of all options in the command, both directly added and in a group.

Returns:	list of all Option instances in the command
Return type:	list

create_flag(name, description, aliases=None)¶

Creates a new flag for this command. A flag is an argument that accepts no value from the user. If specified, the value will be True when it is passed to the command’s underlying method. Flags are, by their nature, always optional.

The given name must be unique across all options within this command. The option instance is returned and can be further edited except for its name.

If the default parser is used by the command, the name must match the typical command line argument format, either:

-s - where s is a single character
–detail - where the argument is longer than one character

The default parser will strip off the leading hyphens when it makes the values available to the command’s method.

Parameters:	name (str) – trigger to set the flag description (str) – user-readable text describing what the option does aliases (list) – list of other argument names that may be used to set the value for this flag
Returns:	instance representing the flag
Return type:	Flag

create_option(name, description, aliases=None, required=True, allow_multiple=False, default=None, validate_func=None, parse_func=None)¶

Creates a new option for this command. An option is an argument to the command line call that accepts a value.

The given name must be unique across all options within this command. The option instance is returned and can be further edited except for its name.

If the default parser is used by the command, the name must match the typical command line argument format, either:

-s - where s is a single character
–detail - where the argument is longer than one character

The default parser will strip off the leading hyphens when it makes the values available to the command’s method.

The validate_func is run against the user-specified value to verify it. If the value is valid, this method should do nothing. In the event the value is invalid, a ValueError or TypeError should be raised.

The signature of this method takes a single argument that is the user-specified value. This function will only be called if the option is specified by the user.

The parse_func functions in a similar manner. If specified, it will be run against the user-specified value. The return from this call will replace the user-specified value and be passed to the command’s execution. The arguments are the same as for validate_func. This function will only be called if the option is specified by the user.

The parse_func may raise ValueError or TypeError as well. The behavior will be the same as for validate_func, allowing the parse_func, if applicable, to function as both the validation and parsing logic.

Parameters:	name (str) – trigger to set the option description (str) – user-readable text describing what the option does aliases (list) – list of other argument names that may be used to set the value for this option required (bool) – if true, the default parser will enforce the the user specifies this option and display a usage warning otherwise allow_multiple (bool) – if true, the value of this option when parsed will be a list of values in the order in which the user entered them default (None) – the default value for optional options validate_func (callable) – if specified, this function will be applied to the user-specified value parse_func (callable) – if specified, this function will be applied to the user-specified value and its return will replace that value
Returns:	instance representing the option
Return type:	Option

execute(prompt, args)¶

Executes this command, passing the remaining arguments into optparse to process.

Parameters:	prompt (Prompt) – for any output the framework needs to display args (list of strings) – any arguments that remained after parsing the command line to determine the command to execute; these are considered arguments to the command’s execution itself

parse_arguments(prompt, input_args)¶

Parses the arguments passed into this command based on the configured options.

Returns:	mapping of argument to value
Return type:	dict

print_command_usage(prompt, missing_required=None, unexpected=None, indent=0, step=2)¶

Prints the details of a command, including all options that can be specified to it.

Parameters:

prompt (Prompt) – prompt instance to print the usage to
missing_required (list of Option) – list of required options that were not specified on an invocation of the CLI
unexpected (list of str) – list of specified option names that do not exist on the command
indent (int) – number of spaces to indent the command
step (int) – number of spaces to increment the indent the command’s options

print_validation_error(prompt, option, exception)¶

Called when an option’s validation function raises a validation error. This call should display a message describing the option that failed and any explanation as to why it did.

Parameters:	option (Option) – option instance that failed validation exception (Exception) – exception that was raised from the validation function

Option Class APIs¶

class okaara.cli.Option(name, description, required=True, allow_multiple=False, aliases=None, default=None, validate_func=None, parse_func=None)¶

Represents an input to a command, either optional or required.

__weakref__¶: list of weak references to the object (if defined)

keyword¶

Returns the keyword the option will be stored under when parsed.

Returns:	keyword to look up in the method handling the command
Return type:	str

Flag Class APIs¶

class okaara.cli.Flag(name, description, aliases=None)¶: Specific form of an option that does not take a value; it is meant to be either included in the command or excluded.

Exceptions¶

class okaara.cli.InvalidStructure¶: Indicates the programmer attempted to assemble a CLI with sections/commands that would conflict with each other (likely duplicates).

class okaara.cli.CommandUsage(missing_options=None, unexpected_options=None)¶

Indicates the command parameters were incorrect. If the usage error was the lack of required parameters, all required parameters that were missing can be specified.

Parameters:	missing_options (list of Option) – optional list of missing required options unexpected_options (list of str) – list of option names that are not defined on the command but were specified

Command Line Interface¶

Cli Class APIs¶

Section Class APIs¶

Command Class APIs¶

Option Class APIs¶

Flag Class APIs¶

Exceptions¶

Project Versions

Table Of Contents

Previous topic

This Page

Navigation

Command Line Interface¶

Cli Class APIs¶

Section Class APIs¶

Command Class APIs¶

Option Class APIs¶

Flag Class APIs¶

Exceptions¶

Project Versions

RTD Search

Table Of Contents

Previous topic

This Page

Quick search

Navigation