Class attributes:
standard_option_list : [Option]
list of standard options that will be accepted by all instances
of this parser class (intended to be overridden by subclasses). Instance attributes:
usage : string
a usage string for your program. Before it is displayed
to the user, "%prog" will be expanded to the name of
your program (self.prog or os.path.basename(sys.argv[0])).
prog : string
the name of the current program (to override
os.path.basename(sys.argv[0])). option_groups : [OptionGroup]
list of option groups in this parser (option groups are
irrelevant for parsing the command-line, but very useful
for generating help)
allow_interspersed_args : bool = true
if true, positional arguments may be interspersed with options.
Assuming -a and -b each take a single argument, the command-line
-ablah foo bar -bboo baz
will be interpreted the same as
-ablah -bboo -- foo bar baz
If this flag were false, that command line would be interpreted as
-ablah -- foo bar -bboo baz
-- ie. we stop processing options as soon as we see the first
non-option argument. (This is the tradition followed by
Python's getopt module, Perl's Getopt::Std, and other argument-
parsing libraries, but it is generally annoying to users.)
process_default_values : bool = true
if true, option default values are processed similarly to option
values from the command line: that is, they are passed to the
type-checking function for the option's type (as long as the
default value is a string). (This really only matters if you
have defined custom types; see SF bug #955889.) Set it to false
to restore the behaviour of Optik 1.4.1 and earlier.
rargs : [string]
the argument list currently being parsed. Only set when
parse_args() is active, and continually trimmed down as
we consume arguments. Mainly there for the benefit of
callback options.
largs : [string]
the list of leftover arguments that we have skipped while
parsing options. If allow_interspersed_args is false, this
list is always empty.
values : Values
the set of option values currently being accumulated. Only
set when parse_args() is active. Also mainly for callbacks.
Because of the rargs , largs , and values attributes,
OptionParser is not thread-safe. If, for some perverse reason, you
need to parse command-line arguments simultaneously in different
threads, use different OptionParser instances.
Methods
|
|
|
|
__init__
|
__init__ (
self,
usage=None,
option_list=None,
option_class=Option,
version=None,
conflict_handler="error",
description=None,
formatter=None,
add_help_option=True,
prog=None,
)
|
|
_add_help_option
|
_add_help_option ( self )
|
|
_add_version_option
|
_add_version_option ( self )
|
|
_create_option_list
|
_create_option_list ( self )
|
|
_get_all_options
|
_get_all_options ( self )
|
|
_get_args
|
_get_args ( self, args )
|
|
_init_parsing_state
|
_init_parsing_state ( self )
|
|
_match_long_opt
|
_match_long_opt ( self, opt )
_match_long_opt(opt : string) -> string
Determine which long option string opt matches, ie. which one
it is an unambiguous abbrevation for. Raises BadOptionError if
opt doesn't unambiguously match any long option string.
|
|
_populate_option_list
|
_populate_option_list (
self,
option_list,
add_help=True,
)
|
|
_process_args
|
_process_args (
self,
largs,
rargs,
values,
)
_process_args(largs : [string],
rargs : [string],
values : Values) Process command-line arguments and populate values , consuming
options and arguments from rargs . If allow_interspersed_args is
false, stop at the first non-option argument. If true, accumulate any
interspersed non-option arguments in largs .
|
|
_process_long_opt
|
_process_long_opt (
self,
rargs,
values,
)
|
|
_process_short_opts
|
_process_short_opts (
self,
rargs,
values,
)
|
|
add_option_group
|
add_option_group (
self,
*args,
*kwargs,
)
Exceptions
|
|
TypeError, "invalid arguments"
TypeError, "not an OptionGroup instance: %r" % group
ValueError, "invalid OptionGroup (wrong parser)"
|
|
|
check_values
|
check_values (
self,
values,
args,
)
check_values(values : Values, args : [string])
-> (values : Values, args : [string]) Check that the supplied option values and leftover arguments are
valid. Returns the option values and leftover arguments
(possibly adjusted, possibly completely new -- whatever you
like). Default implementation just returns the passed-in
values; subclasses may override as desired.
|
|
disable_interspersed_args
|
disable_interspersed_args ( self )
|
|
enable_interspersed_args
|
enable_interspersed_args ( self )
|
|
error
|
error ( self, msg )
error(msg : string)
Print a usage message incorporating msg to stderr and exit.
If you override this in a subclass, it should not return -- it
should either exit or raise an exception.
|
|
exit
|
exit (
self,
status=0,
msg=None,
)
|
|
expand_prog_name
|
expand_prog_name ( self, s )
|
|
format_help
|
format_help ( self, formatter=None )
|
|
format_option_help
|
format_option_help ( self, formatter=None )
|
|
get_default_values
|
get_default_values ( self )
|
|
get_description
|
get_description ( self )
|
|
get_option_group
|
get_option_group ( self, opt_str )
|
|
get_prog_name
|
get_prog_name ( self )
|
|
get_usage
|
get_usage ( self )
|
|
get_version
|
get_version ( self )
|
|
parse_args
|
parse_args (
self,
args=None,
values=None,
)
parse_args(args : [string] = sys.argv[1:],
values : Values = None)
-> (values : Values, args : [string]) Parse the command-line options found in args (default:
sys.argv[1:]). Any errors result in a call to error() , which
by default prints the usage message to stderr and calls
sys.exit() with an error message. On success returns a pair
(values, args) where values is an Values instance (with all
your option values) and args is the list of arguments left
over after parsing options.
|
|
print_help
|
print_help ( self, file=None )
print_help(file : file = stdout)
Print an extended help message, listing all options and any
help text provided with them, to file (default stdout).
|
|
print_usage
|
print_usage ( self, file=None )
print_usage(file : file = stdout)
Print the usage message for the current program (self.usage) to
file (default stdout). Any occurence of the string "%prog" in
self.usage is replaced with the name of the current program
(basename of sys.argv[0]). Does nothing if self.usage is empty
or not defined.
|
|
print_version
|
print_version ( self, file=None )
print_version(file : file = stdout)
Print the version message for this program (self.version) to
file (default stdout). As with print_usage(), any occurence
of "%prog" in self.version is replaced by the current program's
name. Does nothing if self.version is empty or undefined.
|
|
set_default
|
set_default (
self,
dest,
value,
)
|
|
set_defaults
|
set_defaults ( self, **kwargs )
|
|
set_process_default_values
|
set_process_default_values ( self, process )
|
|
set_usage
|
set_usage ( self, usage )
|
|