ArgumentParserValidator.py

A subclass of argparse.ArgumentParser that provides a collection of useful semantic validations such as existing of a file named in a argument, etc.

The goal is to provide as much information about command-line errors as possible before terminating, so as to reduce the user’s repeated invocation of a command to get the syntax right.

Typical usage would be:

>>> from labtools.ArgumentParserValidator import ArgumentParserValidator
>>> parser = ArgumentParserValidator()
>>> parser.add_argument('--foo', dest='foo')
>>> parser.add_argument('--numbers', dest='numbers')
>>> ...
>>> args = parser.parse_args('--foo /dev/null --numbers 1,2,3'.split())
>>> if parser.help_desired(args, program_version, sys.stderr):
>>>    sys.exit(0)
>>> args.is_valid_file('foo', test_writeable=True)
>>> args.is_valie_range('numbers', number=3, bottom=0, top=5, exclusive=False)
>>> 0 == len(args.validation_errors())

class ArgumentParserValidator.ArgumentParserValidator(*args, **kwargs)

Add a little semantic checking on top of the parser.

All the routines append to an error list and also return the outcome of the given test, so that conditional validations can be performed with reduced dependency on order of the tests.

error(message, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>)

Adds the message to the error list

help_desired(version, stream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>)

Standard test to see if license, version, or help is requested, print messages to the stream if so, and return whether or not requested.

Sets versionstring

parse_args(input=None, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>, namespace=None)

Run the standard argparse.ArgumentParser and return an object containing the parsed arguments plus a collection of methods to perform further semantic validation of the arguments.

Some of the semantic validations are duplicates of existing ones, but (I claim) this encapsulates them in an easy-to-use way.

Hack around problem in argparse: argparse.ArgumentParser explicitly looks for sys.argv[0] if args is none and then parse_args() looks for sys.argv[1:]

What should really happen is a patch suggested to argparse that curries sys out of the code.

static valid_range(name, value, number=1, exclusive=True, bottom=0.0, top=1.0, is_float=True)

Return whether value is within the given closed interval [bottom, top]

If bottom or top is None, perform a one-sided comparison.

If exclusive, test the open interval [bottom, top) (exclude upper bound). value to be equal to the top bound.

The test is implemented as a call to eval(). is_float allows the correct formatting of floating point numbers.

Also raise an error if value does not contain number comma-separated values (1 by default).

class ArgumentParserValidator._Arguments

Return a namespace wrapped with a collection of special methods for semantic validation.

add_error(error)

Accrue the error to the error list. If error is a list, extend the existing list rather than appending the list as an object.

arglist(subset=[])

return name=value for the defined arguments

is_valid_dir(parameter, test_writable=False)

Returns whether the string parameter is in the namespace, and if so, whether the pathname specified by parameter exists and is a readable directory. Optionally checks whether it is writable.

If test_writable is True, also test for writability.

is_valid_exclusive(*args)

Return True if exactly one of a list of exclusive arguments is provided.

is_valid_file(parameter, test_writable=False, accept_directory=False)

Returns whether the string parameter is in the namespace, and if so, whether the file specified by parameter exists, and optionally whether it is writable or is a path that could be created and written to.

test_writable=True implies accept a non-existent file in a writable directory.

accept_directory=True implies check to see if it’s a valid directory.

is_valid_filelist(parameter, required_length=0)

Returns whether the string parameter is in the namespace, and if so, whether each file in the list specified by parameter exists. Optionally test whether the list contains at least required_length

is_valid_range(parameter, number=1, exclusive=True, bottom=0.0, top=1.0, is_float=True)

Return True is parameter is in the given range from bottom to top, else False.

See ArgumentParserValidator.valid_range() for details.

Append an error message to validation_errors() if a violation is detected.

print_errors(stream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>)

Print the accumulated errors to the named stream, sys.stderr by default

validation_errors()

Return the list of accumulated validation errors (often used as a boolean test for errors)