commandlines.library module¶

The commandlines.library module contains the Command, Arguments, Definitions, Mops, MultiDefinitions, and Switches classes. These objects are used to parse command line argument strings to command line syntax specific Python objects.

The Command class is a high level object that is intended to be the public facing portion of the library. The commandlines Command object can be imported into projects with the following import statement:

from commandlines import Command

Exceptions raised by this module are in the commandlines.exceptions module.

class commandlines.library.Arguments(argv)[source]¶

Bases: list

A class that includes all command line arguments with positional argument order maintained. Instantiated with a list of command line string tokens.

The class is derived from the Python list type.

param argv:	A list of command line arguments that maintain the argument order that was entered on command line

contains(needle)[source]¶

Returns boolean that indicates the presence (True) or absence (False) of a tuple of one or more test arguments.

Parameters:	needle – (iterable) An iterable that contains one or more test argument strings.
Returns:	boolean

get_arg_next(position)[source]¶

Returns the next argument at index position + 1 in the command sequence.

Parameters:	position – (integer) The argument index position in the Argument list
Returns:	string
Raises:	IndexOutOfRangeError if the position + 1 index falls outside of the existing index range

get_arg_position(test_arg)[source]¶

Returns the index position of the test_arg parameter candidate argument string. The argument string should include the dashes at the beginning of the argument string that would be expected with use on the command line.

Parameters:	test_arg – (string) The argument string for which the index position is requested
Returns:	string
Raises:	MissingArgumentError if the requested argument is not in the Argument list

get_argument(position)[source]¶

Returns an argument string by the argument list index position.

Parameters:	position – (integer) The command line index position
Returns:	string
Raises:	IndexOutOfRangeError if the requested index falls outside of the list index range

get_argument_for_commandobj(position)[source]¶

An argument parsing method for the instantation of the Command object. This is not intended for public use. Public calls should use the get_argument() method instead.

Parameters:	position – The command line index position
Returns:	string or empty string if the index position is out of the index range

class commandlines.library.Command[source]¶

Bases: object

An object that maintains syntax specific components of a command line string and provides methods to support the development of Python command line applications.

The class is instantiated from the list of command line arguments that are passed to a Python script in sys.argv.

Attributes:

arg0 : (string)

Argument at index position 0

arg1 : (string)

Argument at index position 1

arg2 : (string)

Argument at index position 2

arg3 : (string)

Argument at index position 3

arg4 : (string)

Argument at index position 4

argc : (int)

Length of the arguments list

arglp : (string)

Argument at last index position in the arguments list

arguments: (Arguments, list)

List of all ordered positional arguments in the command string

defaults: (dict)

Dictionary of default key : value mapped as option : argument value

defs: (Definitions, dict)

Dictionary of key=option : value=argument definition pairs

mdefs: (MultiDefinitions, Definitions, dict)

Dictionary of key=option : value=argument definition pairs for options included more than once in command

mops: (set)

Set of multi-option short syntax (i.e. single dash) switches

subcmd: (string)

The first positional argument (=arg0)

subsubcmd: (string)

The second positional argument (=arg1)

switches: (set)

Set of long and short switch syntax arguments

contains_defaults(*default_needles)[source]¶

Tests for the presence of one or more default option : argument definitions in the Command.defaults parameter

Parameters:	default_needles – (tuple) One or more test default option strings
Returns:	boolean. True = the default options are defined. False = the default options are not defined

contains_definitions(*def_needles)[source]¶

Test for the presence of one or more option-argument definitions in the command string. Returns boolean that indicates presence (True) or absence (False) of definition options. Dashes should not be used at the beginning of the strings in the def_needles parameter.

Parameters:	def_needles – (tuple) One or more expected definition option key(s).
Returns:	boolean

contains_mops(*mops_needles)[source]¶

Returns boolean that indicates presence (True) or absence (False) of one or more multi-option short syntax switch characters.

Returns:	boolean

contains_multi_definitions(*def_needles)[source]¶

Test for the presence of multiple option-argument definitions that use the same option string. An example is

$ executable -o file1 -o file2

The dashes in the argument strings should not be included in the def_needles parameter. Returns boolean that indicates presence (True) or absence (False) of one or more multi-definition options.

Parameters:	def_needles – (tuple) One or more expected definition option key(s).
Returns:	boolean

contains_switches(*switch_needles)[source]¶

Test for the presence of one or more switches in the command string. Returns boolean that indicates presence (True) or absence (False) of switches. Dashes should not be used at the beginning of the strings in the switch_needles parameter.

Parameters:	switch_needles – (tuple) One or more expected switch strings.
Returns:	boolean

does_not_validate_missing_args()[source]¶

Command string validation for missing arguments to the executable.

Returns:	boolean. True = does not validate. False = validates

does_not_validate_missing_defs()[source]¶

Command string validation for missing definitions to the executable

Returns:	boolean. True = does not validate. False = validates

does_not_validate_missing_mops()[source]¶

Command string validation for missing multi-option short syntax arguments to the executable

Returns:	boolean. True = does not validate. False = validates

does_not_validate_missing_switches()[source]¶

Command string validation for missing switches to the executable

Returns:	boolean. True = does not validate. False = validates

does_not_validate_n_args(number)[source]¶

Command string validation for inclusion of exactly n arguments to executable.

Parameters:	number – (integer) Defines the number of expected arguments for this test
Returns:	boolean. True = does not validate. False = validates

get_arg_after(target_arg)[source]¶

Returns the next positional argument at index position n + 1 to a command line argument at index position n.

Parameters:	target_arg – (string) Argument string for the test.
Returns:	string
Raises:	MissingArgumentError when target_arg is not found in the parsed argument list
Raises:	IndexOutOfRangeError when target_arg is the last positional argument

get_default(default_needle)[source]¶

Gets the value for an existing default option : argument definition in the Command.defaults parameter. The default_needle option string should not include dashes at the beginning of the string.

Parameters:	default_needle – (string) The existing default option for which a value is requested
Returns:	User-specified type. A value of any type that is permissible as a value in Python dictionaries
Raises:	MissingDictionaryKeyError if the key is not found in the Command.defaults dictionary

get_definition(def_needle)[source]¶

Returns the argument to an option that is part of an option-argument definition pair.

Parameters:	def_needle – (string) The option string of the option-argument pair
Returns:	string
Raises:	MissingDictionaryKeyError when the option string is not found

get_double_dash_args()[source]¶

Returns the arguments after the double dash – command line idiom as a list.

Returns:	list of strings

get_multiple_definitions(def_needle)[source]¶

Returns a list of argument strings to an option that is included multiple times using option-argument syntax on the command line (e.g. $ executable -o file1 -o file2)

Parameters:	def_needle – (string) The option string of the option-argument pair
Returns:	string
Raises:	MissingDictionaryKeyError when the option string is not found

has_args_after(argument_needle, number=1)[source]¶

Test for the presence of at least one (default) positional arguments following an existing argument (argument_needle). The number of expected arguments is modified by defining the number method parameter.

Parameters:	number – (integer) The number of expected arguments after the test argument argument_needle – (string) The test argument that is known to be present in the command
Raises:	MissingArgumentError when argument_needle is not found in the parsed argument list

has_command_sequence(*cmd_list)[source]¶

Test for a sequence of command line tokens in the command string. The test begins at index position 0 of the argument list and is case-sensitive.

Parameters:	cmd_list – (tuple) Expected commands in expected order starting at Command.argv index position 0
Returns:	boolean

has_double_dash()[source]¶

Test for the presence of the double dash – command line idiom.

Returns:	boolean. True = has double dash token. False = does not contain double dash token.

is_help_request()[source]¶

Tests for -h and –help options in command string

Returns:	boolean. True = included help option. False = did not include help option.

is_quiet_request()[source]¶

Tests for –quiet option in command string

Returns:	boolean. True = included quiet option. False = did not include quiet option.

is_usage_request()[source]¶

Tests for –usage option in command string

Returns:	boolean. True = included usage option. False = did not include usage option.

is_verbose_request()[source]¶

Tests for –verbose option in command string

Returns:	boolean. True = included verbose option. False = did not include verbose option.

is_version_request()[source]¶

Tests for -v and –version options in command string.

Returns:	boolean. True = included version option. False = did not include version option.

next_arg_is_in(start_argument, supported_at_next_position)[source]¶

Test for the presence of a supported argument in the n+1 index position for a known argument at the n position. start_argument is called as the full argument string including any expected dashes.

Parameters:	start_argument – (string) The argument string including any beginning dashes as used on the command line. supported_at_next_position – (list) list of strings that define supported arguments in the n+1 index
Raises:	MissingArgumentError when start_argument is not found in the parsed argument list

obj_string()[source]¶

Returns a string of the instance attributes of the Command object intended for standard output use. Print the returned string to view the parsed arguments in the standard output stream.

Returns:	string

set_defaults(default_dictionary)[source]¶

Sets default option : argument definitions with a dictionary parameter. The option keys should not include dashes at the beginning of the option string. One or more key:value pairs can be included in the default_dictionary parameter.

Parameters:	default_dictionary – (dict) Defines the default key=option : value=argument mapping
Returns:	None

validates_includes_args()[source]¶

Command string validation for inclusion of at least one argument to the executable

Returns:	boolean. True = validates. False = does not validate.

validates_includes_definitions()[source]¶

Command string validation for inclusion of at least one definition (option-argument) to the executable

Returns:	boolean. True = validates. False = does not validate.

validates_includes_mops()[source]¶

Command string validation for inclusion of at least one multi-option short syntax argument to the executable.

Returns:	boolean. True = validates. False = does not validate.

validates_includes_n_args(number)[source]¶

Command string validation for inclusion of exactly number arguments to the executable.

Parameters:	number – (integer) Defines the number of expected arguments for this test
Returns:	boolean. True = validates. False = does not validate.

validates_includes_switches()[source]¶

Command string validation for inclusion of at least one switch argument to the executable.

Returns:	boolean. True = validates. False = does not validate.

class commandlines.library.Definitions(argv)[source]¶

Bases: dict

A class that is instantiated with all command line definition options as defined by the syntax -s <defintion argument>, –longoption <defintion argument>, –longoption=<definition argument>, or -longoption <definition argument>.

To parse as a definition option, the argument to the option must not contain any dashes at the beginning of the argument string. For example, -o –long is not considered a definition option-arg pair, whereas -o long is.

This class is derived from the Python dictionary type. The mapping is:

key = option string with all dash ‘-‘ character(s) at the beginning of the string removed. Internal dashes are maintained.

value = definition argument string.

Parameters:	argv – (list) A list of command line arguments that maintain the argument order that was entered on command line

contains(needle)[source]¶

Returns boolean that indicates the presence (True) or absence (False) of a tuple of option-argument definitions by option match attempt.

The definition option string should be used without any initial dash characters in the definition argument name in contrast to how they were used on the command line.

Parameters:	needle – (tuple) A tuple of one or more option strings from expected definition option-argument string pairs
Returns:	boolean

get_def_argument(needle)[source]¶

Returns the definition argument string for a definition option test. The needle parameter should not include dash characters at the beginning of the option string (i.e. use ‘test’ rather than ‘–test’ and ‘t’ rather than ‘-t’).

Parameters:	needle – (string) The requested option string from the definition option-argument pair.
Returns:	string
Raises:	MissingDictionaryKeyError if the option needle is not a key defined in the Definitions object

class commandlines.library.Mops(argv)[source]¶

Bases: set

A class that is instantiated with unique switches from multi-option command line options that use short, single dash syntax.

Examples: -rnj -tlx

Each alphabetic character in the option token is parsed to a separate option token.

The class is derived from the Python set type and the single character option switches are stored as set items.

Parameters:	argv – (list) A list of command line arguments that maintain the argument order that was entered on command line

contains(needle)[source]¶

Returns boolean that indicates the presence (True) or absence (False) of a tuple of test Mops syntax option switches. The test strings should each be a single character without the dash that is used at the beginning of the entire token.

Parameters:	needle – (iterable) An iterable that contains one or more test argument characters as strings.
Returns:	boolean

class commandlines.library.MultiDefinitions(argv)[source]¶

Bases: commandlines.library.Definitions

A class that is used to parse option-argument definitions from a command line argument list where command line use includes multiple same option strings with different argument definitions. An example is:

$ executable -o file1 -o file2

The class is derived from the commandlines.Definitions class (which is derived from Python dict). The commandlines.Definitions.contains and commandlines.Definitions.get_def_arguments methods are inherited from the Definitions class.

The dictionary mapping is:

key = option string with all dash ‘-‘ character(s) at the beginning of the string removed. Internal dashes are maintained.

value = list of all argument strings associated with the option string on the command line

Parameters:	argv – (list) A list of command line arguments that maintain the argument order that was entered on command line

class commandlines.library.Switches(argv)[source]¶

Bases: set

A class that is instantiated with all command line switches that have the syntax -s, –longswitch, or -onedashlong.

The class is derived from the Python set type and arguments with this syntax are saved as set items.

Parameters:	argv – (list) A list of command line arguments that maintain the argument order that was entered on command line

contains(needle)[source]¶

Returns boolean that indicates the presence (True) or absence (False) of a tuple of test switches. Switch parameters in needle tuple should be passed without initial dash character(s) in the test switch argument name.

Parameters:	needle – (iterable) An iterable that contains one or more test argument strings.
Returns:	boolean