A POSIX-compliant, CLI parser library for building CLI interfaces, designed to be flexible, intelligent, and uncompromisingly simple. Clipp aims to make code more reusable and easily scalable, without compromising performance.

class Command(name='', prologue='', epilogue='', usage='', help='', version_info='')#

Bases: OptionGroup

Container for storing user-defined options and sub-commands. Uses stored options and sub-commands to generate rules which dictate how command-line arguments are to be parsed.

Parameters#

namestr, optional: The name of the command used as the key in the namespace returned after parsing command-line arguments. If no name is provided, defaults to the name of the script which calls the constructor.
prologuestr, optional: The introductory text displayed in the command’s help message.
epiloguestr, optional: The text displayed at the bottom of the command’s help message.
usagestr, optional: The usage text displayed in the command’s help message.
helpstr, optional: The help message which is displayed when user’s invoke the help function by supplying the help option string in the terminal.
version_infostr, optional: The version info message which is displayed when user’s invoke the version info function by supplying the version option string in the terminal.

add_binary_flag(*aliases, dest='', const=True, help='', usage='', is_global=False)#

Add a boolean flag to the group.

The parser does not evaluate command-line arguments for boolean flags. Instead, their values are predetermined by const which expects a boolean value and is used to determine the option’s default value which is always the opposite of const. Thus, if const is True, the default will be False.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
deststr optional: Alternative name for the option, used as the option’s key in the namespace produced after parsing command-line arguments. If two or more options have the same dest, they will clobber each other in the namespace, which may or may not be desired.
constbool,: Default value used if the option IS encountered while parsing.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.
requiredbool, default False: Whether or not the option is a required option.
is_globalbool, default False: Whether or not the option can be used in a sub-command. Sub-commands can override universal options of their parents.

Raises#

ValueError :: alias is not a valid short or long alias string.

add_fast_flag(*aliases, callback, help='', usage='')#

Add a fast flag to the group.

When a fast flag is encountered by the parser, a call to the option’s callback function is immediately triggered, followed by a call to sys.exit.

The default –help option is an example of a fast flag. When any of the aliases for the option are encountered by the parser, the help message is immediately displayed, all other options are ignored, and the system exits.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
callbackCallable: The function which is called when the option is encountered by the pre-processor.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

Raises#

ValueError :: alias is not a valid short or long alias string.

add_flag(*aliases, dest='', default=None, const, help='', usage='', is_global=False)#

Add a flag to the group.

The parser does not evaluate command-line arguments for flags. Instead, their values are predetermined by their const and default values.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
deststr optional: Alternative name for the option, used as the option’s key in the namespace produced after parsing command-line arguments. If two or more options have the same dest, they will clobber each other in the namespace, which may or may not be desired.
defaultAny, optional: Default value used if the option is NOT encountered while parsing.
constAny: Default value used if the option IS encountered while parsing.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.
requiredbool, default False: Whether or not the option is a required option.
is_globalbool, default False: Whether or not the option can be used in a sub-command. Sub-commands can override universal options of their parents.

Raises#

ValueError :: alias is not a valid short or long alias string.

add_option(*aliases, dest='', quota=1, choices=(), default=None, const=None, dtype=None, action=None, help='', usage='', required=False, is_global=False)#

Add a non-positional option to the group.

Parameters#

*aliasesstr

The various aliases which can be used to invoke the option from the command-line.

deststr optional

Alternative name for the option, used as the option’s key in the namespace produced after parsing command-line arguments. If two or more options have the same dest, they will clobber each other in the namespace, which may or may not be desired.

quota{int, ‘+’, ‘*’}, default 1

The number of arguments which the parser will attempt to consume.

int: Consume exactly quota arguments.
*: Consume zero or more arguments (greedy).
+: Consume one or more arguments (greedy).

choicesSequence

An iterable containing the set of allowed strings for the parser to consume. Duplicates will be removed. A choice can be any string which does not contain a leading dash. This argument is only supported if quota is equal to one.

defaultAny, optional

Default value used if the option is NOT encountered while parsing. Defaults are only supported by options which accept one or fewer arguments. If no default is supplied to an option with a quota of zero-or-more (*) then the value returned by the parser will be an empty list. Defaults are ignored for options which are members of mutually exclusive groups.

constAny, optional

Default value used if the option IS encountered while parsing. const is only used in the case where an option expects one or fewer arguments but no arguments are consumed. If const is supplied to an option with a quota of zero-or-more (*) then the value returned by the parser will be an empty list.

dtypeCallable, optional

Optional callable which will be used to convert each of the tokens collected by the parser. Exceptions raised by this callback are not captured by clipp.

actionCallable, optional

Optional callable for post-processing tokens collected by the parser. For options which only consume a single token, the list of tokens is indexed and the retrieved value is passed to the callable. Otherwise, action will receive the entire list. The action is always called after tokens have been converted by calling dtype. Like dtype, exceptions raised by this callback are not captured by clipp.

helpstr, optional

The option’s help string which defines its usage.

usagestr, optional

The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

requiredbool, default False

Whether or not the option is a required option.

is_globalbool, default False

Whether or not the option can be used in a sub-command. Sub-commands can override global options of their parents.

Raises#

ValueError :

alias is not a valid short or long alias string.
quota is a string which is not equal to one of {‘*’, ‘+’}.
const or default are not supported, given the quota.
choices contains an invalid choice string.
choices is not supported, given the quota.

TypeError :

quota is not a numeric type or a string type.

add_parameter(name, dest='', quota=1, choices=(), default=None, dtype=None, action=None, help='', usage='')#

Add a positional argument to the command.

Parameters#

namestr

The namespace ID for the argument. Positional argument names may contain only letters, numbers, and dashes (-). Leading or trailing dashes are disallowed.

deststr, optional

Alternative name for the argument, used as the argument’s key in the namespace produced after parsing command-line arguments. If two or more options have the same dest, they will clobber each other in the namespace, which may or may not be desired.

quota{int, ‘+’, ‘*’}, default 1

The number of arguments which the parser will attempt to consume.

int: Consume exactly quota arguments.
*: Consume zero or more arguments (greedy).
+: Consume one or more arguments (greedy).

choicesSequence

An iterable containing the set of allowed strings for the parser to consume. There must be more than one choice. Duplicates will be removed. A choice can be any string which does not contain a leading dash. This parameter is only supported when if quota is equal to one.

defaultAny, optional

dtypeCallable, optional

Optional callable which will be used to convert each of the tokens collected by the parser. Exceptions raised by this callback are not captured by clipp.

actionCallable, optional

helpstr, optional

The argument’s help string which defines its usage.

usagestr, optional

The argument’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

Raises#

ValueError :

name is not a valid positional argument name.
quota is a string which is not equal to one of {‘*’, ‘+’}.
default is not supported, given the quota.
choices contains an invalid choice string.
choices is not supported, given the quota.

TypeError :

quota is not a numeric type or a string type.

add_subcommand(name, dest='', prologue='', epilogue='', usage='', help='', version_info='')#

Add the specified sub-command identified by name to the command.

Parameters#

namestr: The name of the sub-command. Unless overriden by dest, it is used as the key in the dictionary/namespace produced by the parser.
prologuestr, optional: The introductory text displayed in the command’s help message.
epiloguestr, optional: The text displayed at the bottom of the command’s help message.
usagestr, optional: The usage text displayed in the command’s help message.
helpstr, optional: The help message which is displayed when user’s invoke the help function by supplying the help option string in the terminal.
version_infostr, optional: The version info message which is displayed when user’s invoke the version info function by supplying the version option string in the terminal.
deststr, optional: The namespace ID used by to parser to avoid naming conflicts with other commands while generating the return namespace. If name conflicts with the name of any other command in the command hierarchy, a unique dest must be provided.

Raises#

KeyError :: name interferes with the name of a another command in the command hierarchy and a non-unique dest has been supplied.

format_help()#

Formats and returns the option’s help string.

If a help string was explicitly supplied to the command, that is the string which is formatted. Otherwise, clipp will compile and format its own help string.

format_usage()#

Formats and returns the command’s usage string.

If a usage string was explicitly provided, it is wrapped to the width of the terminal and returned.

format_version_info()#: Formats and returns the command’s version info string.

include(option_group, aliases=None)#

Include options from another option group.

Relational group membership is maintained if more than one option from either a dependent or mutually exclusive group is added. If only one option from a given relational group is added, that option loses its status as a member of the relational group. For instance, if the option group being included has a mutually exclusive group comprised of –foo and –bar, but only –bar is included, then –bar will lose its status as a mutually exclusive option. The same rule applies to dependent groups.

Parameters#

option_groupOptionGroup: The group containing the options to be added.
aliaseslist[str], optional.: Optional list of aliases referring to the options which should be added. If no list is provided, all options will be added.

Raises#

KeyError :: One or more of the options already exists in the group or has an alias which conflicts with an option which has already been added.

remove(option_name)#

Remove an option or parameter from the command.

Parameters#

option_namestr: The name of the option to be removed. If the option has multiple aliases, the name can be any one of those aliases.

Raises#

KeyError :: name is recognized by the command.

set_help_flag(*aliases, callback=None, help='', usage='')#

Set the default help flag. If a help flag has already been set, it will be overridden.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
callbackCallable: The function which is called when the option is encountered by the pre-processor.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

Raises#

ValueError :: alias is not a valid short or long alias string.

set_version_flag(*aliases, callback=None, help='', usage='')#

Set the default version info flag. If the flag has already been set, it will be overridden.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
callbackCallable: The function which is called when the option is encountered by the pre-processor.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

Raises#

ValueError :: alias is not a valid short or long alias string.

property global_options#: A dictionary-like view containing all global options.

property local_options#: A dictionary-like view containing all local options.

property options#: A context-dependent, dictionary-like view containing all global and local options.

property parameters#: A dictionary-like view containing all positional arguments.

class OptionGroup#

Bases: object

An option group is a simple container class for storing options. Option groups can be used to group options that share similar characterstics or which are always expected to be added together to a command object. Options stored in a group can be added to a command by adding the entire group. Option groups help reduce code repetition and facilitate code re-use.

add_binary_flag(*aliases, dest='', const=True, help='', usage='', is_global=False)#

Add a boolean flag to the group.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
deststr optional: Alternative name for the option, used as the option’s key in the namespace produced after parsing command-line arguments. If two or more options have the same dest, they will clobber each other in the namespace, which may or may not be desired.
constbool,: Default value used if the option IS encountered while parsing.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.
requiredbool, default False: Whether or not the option is a required option.
is_globalbool, default False: Whether or not the option can be used in a sub-command. Sub-commands can override universal options of their parents.

Raises#

ValueError :: alias is not a valid short or long alias string.

add_fast_flag(*aliases, callback, help='', usage='')#

Add a fast flag to the group.

When a fast flag is encountered by the parser, a call to the option’s callback function is immediately triggered, followed by a call to sys.exit.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
callbackCallable: The function which is called when the option is encountered by the pre-processor.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

Raises#

ValueError :: alias is not a valid short or long alias string.

add_flag(*aliases, dest='', default=None, const, help='', usage='', is_global=False)#

Add a flag to the group.

The parser does not evaluate command-line arguments for flags. Instead, their values are predetermined by their const and default values.

Parameters#

*aliasesstr: The various aliases which can be used to invoke the option from the command-line.
deststr optional: Alternative name for the option, used as the option’s key in the namespace produced after parsing command-line arguments. If two or more options have the same dest, they will clobber each other in the namespace, which may or may not be desired.
defaultAny, optional: Default value used if the option is NOT encountered while parsing.
constAny: Default value used if the option IS encountered while parsing.
helpstr, optional: The option’s help string which defines its usage.
usagestr, optional: The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.
requiredbool, default False: Whether or not the option is a required option.
is_globalbool, default False: Whether or not the option can be used in a sub-command. Sub-commands can override universal options of their parents.

Raises#

ValueError :: alias is not a valid short or long alias string.

add_option(*aliases, dest='', quota=1, choices=(), default=None, const=None, dtype=None, action=None, help='', usage='', required=False, is_global=False)#

Add a non-positional option to the group.

Parameters#

*aliasesstr

The various aliases which can be used to invoke the option from the command-line.

deststr optional

quota{int, ‘+’, ‘*’}, default 1

The number of arguments which the parser will attempt to consume.

int: Consume exactly quota arguments.
*: Consume zero or more arguments (greedy).
+: Consume one or more arguments (greedy).

choicesSequence

defaultAny, optional

constAny, optional

dtypeCallable, optional

Optional callable which will be used to convert each of the tokens collected by the parser. Exceptions raised by this callback are not captured by clipp.

actionCallable, optional

helpstr, optional

The option’s help string which defines its usage.

usagestr, optional

The option’s usage string which defines its syntax. If no string is provided, clipp will attempt to infer the syntax.

requiredbool, default False

Whether or not the option is a required option.

is_globalbool, default False

Whether or not the option can be used in a sub-command. Sub-commands can override global options of their parents.

Raises#

ValueError :

alias is not a valid short or long alias string.
quota is a string which is not equal to one of {‘*’, ‘+’}.
const or default are not supported, given the quota.
choices contains an invalid choice string.
choices is not supported, given the quota.

TypeError :

quota is not a numeric type or a string type.

include(option_group, aliases=None)#

Include options from another option group.

Parameters#

option_groupOptionGroup: The group containing the options to be added.
aliaseslist[str], optional.: Optional list of aliases referring to the options which should be added. If no list is provided, all options will be added.

Raises#

KeyError :: One or more of the options already exists in the group or has an alias which conflicts with an option which has already been added.

remove(option_name)#

Remove an option from the command.

Parameters#

option_namestr: The name of the option to be removed. If the option has multiple aliases, the name can be any one of those aliases.

Raises#

KeyError :: name is recognized by the command.

property global_options#: A dictionary-like view containing all global options.

property local_options#: A dictionary-like view containing all local options.

property options#: A context-dependent, dictionary-like view containing all global and local options.

fill_paragraph(text, width=70, initial_indent='', subsequent_indent='')#

Multi-line text fill which retains leading indentation for each line.

Parameters#

textstr: The text to be filled (wrapped).
widthint: The maximum width for each line. If the width is longer than the terminal width, the terminal width will be used instead.
initial_indentstr: The indent for the first line of the string.
subsequent_indentstr: The indent for all lines following the first. This includes new lines generated by wrapping the text.

Returns#

The filled/wrapped text.