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.
list of weak references to the object (if defined)
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 |
---|
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 |
---|
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: |
|
---|---|
Returns: | instance representing the newly added command |
Return type: | Command |
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: |
|
---|---|
Returns: | instance representing the newly added section |
Return type: | Section |
Syntactic sugar method that functions identical to create_section.
Return type: | Section |
---|
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 |
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 |
Syntactic sugar method that functions identical to find_section.
Prints the structure of the CLI in a tree-like structure to indicate section ownership.
Parameters: |
|
---|
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 |
---|
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 |
Syntactic sugar method that functions identical to remove_section.
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 |
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).
list of weak references to the object (if defined)
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 |
---|
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 |
---|
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: |
|
---|---|
Returns: | instance representing the newly added command |
Return type: | Command |
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: |
|
---|---|
Returns: | instance representing the newly added section |
Return type: | Section |
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 |
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 |
Prints the direct children of a single section; this call will not recurse into the children and print their hierarchy.
Parameters: |
|
---|
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 |
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 |
Integrity check to validate that the CLI has not been configured with an entity (subsection or command) with the given name.
Parameters: | name (string) – name of the subsection/command to look for |
---|---|
Raises InvalidStructure: | |
if there is an entity with the given name |
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.
list of weak references to the object (if defined)
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 |
---|
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 |
---|
Adds an option group to the command. Option groups will be rendered in the order they are added.
Parameters: | option_group (OptionGroup) – option group |
---|
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 |
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:
The default parser will strip off the leading hyphens when it makes the values available to the command’s method.
Parameters: |
|
---|---|
Returns: | instance representing the flag |
Return type: | Flag |
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:
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: |
|
---|---|
Returns: | instance representing the option |
Return type: | Option |
Executes this command, passing the remaining arguments into optparse to process.
Parameters: |
|
---|
Parses the arguments passed into this command based on the configured options.
Returns: | mapping of argument to value |
---|---|
Return type: | dict |
Prints the details of a command, including all options that can be specified to it.
Parameters: |
|
---|
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: |
|
---|
Represents an input to a command, either optional or required.
list of weak references to the object (if defined)
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 |
Specific form of an option that does not take a value; it is meant to be either included in the command or excluded.
Indicates the programmer attempted to assemble a CLI with sections/commands that would conflict with each other (likely duplicates).
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: |
|
---|