dsargparse module

dsargparse: docstring based argparse.

dsargparse is a wrapper of argparse library which prepares helps and descriptions from docstrings. It also sets up functions to be run for each sub command, and provides a helper function which parses args and run a selected command.

class dsargparse.ArgumentParser(main=None, argmap=None, *args, **kwargs)

Bases: argparse.ArgumentParser

Customized ArgumentParser.

This customized ArgumentParser will add help and description automatically based on docstrings of main module and functions implements processes of each command. It also provides parse_and_run() method which helps parsing arguments and executing functions.

This class takes same arguments as argparse.ArgumentParser to construct a new instance. Additionally, it has a positional argument main, which takes the main function of the script dsargparse library called. From the main function, it extracts doctstings to set command descriptions.

add_argument(*args, **kwargs)

Add an argument.

This method adds a new argument to the current parser. The function is same as argparse.ArgumentParser.add_argument. However, this method tries to determine help messages for the adding argument from some docstrings.

If the new arguments belong to some sub commands, the docstring of a function implements behavior of the sub command has Args: section, and defines same name variable, this function sets such definition to the help message.

Positional Args:

same positional arguments as argparse.ArgumentParser.add_argument.

Keyword Args:

same keywards arguments as argparse.ArgumentParser.add_argument.

add_subparsers(**kwargs)

Add subparsers.

Keyword Args:

same keywords arguments as argparse.ArgumentParser.add_subparsers.

Returns:

an instance of action class which is used to add sub parsers.

parse_and_run(**kwargs)

Parse arguments and run the selected command.

Keyword Args:

same keywords arguments as argparse.ArgumentParser.parse_args.

Returns:

any value the selected command returns. It could be None.

exception dsargparse.ArgumentError(argument, message)

Bases: exceptions.Exception

An error from creating or using an argument (optional or positional).

The string value of this exception is the message, augmented with information about the argument that caused it.

exception dsargparse.ArgumentTypeError

Bases: exceptions.Exception

An error from trying to convert a command line string to a type.

class dsargparse.FileType(mode='r', bufsize=-1)

Bases: object

Factory for creating file object types

Instances of FileType are typically passed as type= arguments to the ArgumentParser add_argument() method.

Keyword Arguments:

• mode – A string indicating how the file is to be opened. Accepts the

  same values as the builtin open() function.

• bufsize – The file’s desired buffer size. Accepts the same values as

  the builtin open() function.

class dsargparse.HelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: object

Formatter for generating usage messages and argument help strings.

Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.

add_argument(action)

add_arguments(actions)

add_text(text)

add_usage(usage, actions, groups, prefix=None)

end_section()

format_help()

start_section(heading)

class dsargparse.ArgumentDefaultsHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.HelpFormatter

Help message formatter which adds default values to argument help.

Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.

class dsargparse.RawDescriptionHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.HelpFormatter

Help message formatter which retains any formatting in descriptions.

Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.

class dsargparse.RawTextHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.RawDescriptionHelpFormatter

Help message formatter which retains formatting of all help text.

Only the name of this class is considered a public API. All the methods provided by the class are considered an implementation detail.

class dsargparse.Namespace(**kwargs)

Bases: argparse._AttributeHolder

Simple object for storing attributes.

Implements equality by attribute names and values, and provides a simple string representation.

class dsargparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: argparse._AttributeHolder

Information about how to convert command line strings to Python objects.

Action objects are used by an ArgumentParser to represent the information needed to parse a single argument from one or more strings from the command line. The keyword arguments to the Action constructor are also all attributes of Action instances.

Keyword Arguments:

• option_strings – A list of command-line option strings which

  should be associated with this action.

• dest – The name of the attribute to hold the created object(s)

• nargs – The number of command-line arguments that should be

  consumed. By default, one argument will be consumed and a single value will be produced. Other values include:

  • N (an integer) consumes N arguments (and produces a list)
  • ‘?’ consumes zero or one arguments
  • ‘*’ consumes zero or more arguments (and produces a list)
  • ‘+’ consumes one or more arguments (and produces a list)

  Note that the difference between the default and nargs=1 is that with the default, a single value will be produced, while with nargs=1, a list containing a single value will be produced.

• const – The value to be produced if the option is specified and the

  option uses an action that takes no values.

• default – The value to be produced if the option is not specified.

• type – A callable that accepts a single string argument, and

  returns the converted value. The standard Python types str, int, float, and complex are useful examples of such callables. If None, str is used.

• choices – A container of values that should be allowed. If not None,

  after a command-line argument has been converted to the appropriate type, an exception will be raised if it is not a member of this collection.

• required – True if the action must always be specified at the

  command line. This is only meaningful for optional command-line arguments.

• help – The help string describing the argument.

• metavar – The name to be used for the option’s argument with the

  help string. If None, the ‘dest’ value will be used as the name.