Skip to content

PythonAPI

Jump to bottom Edit New page
Renaud Guillard edited this page Jul 3, 2013 · 9 revisions

Python command line parser API

Overview

There is 3 major kinds of objects in the Python API.

  • The *Info classes represent the Python counterparts of the elements defined in a program interface definition XML file.
  • The *Result classes store the state of the program elements after a command line argument processing
  • The Parser class parses command line arguments according to *Info rules and output corresponding *Results

Info objects

In a basic usage of the Python API. You shouldn't have to take care of the *Info classes since the build-python.sh will automatically generate a derivated ProgramInfo class populated with all options, subcommands and positional arguments descriptions. The only thing to do is to instanciate this class and give it to a Parser instance.

#!python
info = miniappProgramInfo()
parser = Parser(info)

Program usage

ProgramInfo provides a usage() method which prints the program usage. The UsageFormat class can be used to tweak usage output

Member Type / Return type Description
lineLength integer Maximum line length (default: 80)
indentString string Indentation character(s)
wrap() string Wrap text according `UsageFormat` settings
SHORT_TEXT flag Display short usage
ABSTRACT_TEXT flag Display short usage and option abstract description
DETAILED_TEXT flag Display full usage 
#!python
usage = UsageFormat()
print info.usage(usage)
# display program usage

print info.usage(usage, "sc")
# display sc program sub command usage

Result objects

OptionResult

All options result share a common ancestor OptionResult with the following properties

Member / Method Type / Return type Description
`isSet` `boolean` `True` if the option is present in the command line arguments and if its presence and value is valid
`value(...)` `mixed` Value of the option. The returned type depends on the option type
##__call__ `mixed` A shortcut to call the `value(...)` method

SwithOptionResult

Result of a switch option. The value() method returns the value of the isSet member

ArgumentOptionResult

Result of a single-argument option. The value() method returns the value of the option argument if the option is present. Otherwise None

MultiArgumentOptionResult

Result of a multi-argument option. The value(...) method returns an array containing the option arguments. Thus, value(...) (and ##call accept arguments

#!python
optionRes.value(2, 3)
// or 
optionRes.value( (2, 3) )

will return arguments at index 2 and 3 only

SubcommandResult

Contains an array of OptionResult where the array keys are the option's bound variable name defined by the <prg:variable> node of the XML definition file. Option values can be accessed by the operator []

#!python
subcommand["optionVarName"].value()

As a pseudo member (thanks to the magic method ##getattr

#!python
subcommand.optionVarName.value()

Or as a pseudo method (thanks to the magic method ##call

#!python
subcommand.optionVarName()

ProgramResult

The main object returned by the Parser

Parser

Member / Method Type / Return type Description
`subcommandName` `string` Main name of the selected subcommand if set. Otherwise `None`
`subcommand` `SubcommandResult` Reference to the selected subcommand result if set. Otherwise `None`
##__call__ `boolean` `True` if the command line argument parsing completes successfully (no error raised)
`valueCount()` `integer` Number of positional arguments
operator [*key*] mixed If *key* is a number. value of the *key*th positional argument. Otherwise, value of the global option bound to variable *key*
`getMessages(min, max)` array Get a list of messages generated during command line argument parsing. The *min* and *max* arguments allow to filter messages by importance (debug, warnings, errors and fatal error)

Options can also be accsssed as in SubcommandResult (by pseudo variable/method)

See also

The program interface definition framework

Add a custom footer
Add a custom sidebar

Clone this wiki locally