Python标准库optparse解析器的命令行选项

创建解析器¶

The first step in using optparse is to create an OptionParser instance.

class optparse.OptionParser(...)¶

The OptionParser constructor has no required arguments, but a number of

optional keyword arguments. You should always pass them as keyword

arguments, i.e. do not rely on the order in which the arguments are declared.

usage (默认: "%prog[options]")

The usage summary to print when your program is run incorrectly or with a

help option. When optparse prints the usage string, it expands

%prog to os.path.basename(sys.argv[0]) (or to prog if you

passed that keyword argument). To suppress a usage message, pass the

special value optparse.SUPPRESS_USAGE.

option_list (默认: [])

A list of Option objects to populate the parser with. The options in

option_list are added after any options in standard_option_list (a

class attribute that may be set by OptionParser subclasses), but before

any version or help options. Deprecated; use add_option() after

creating the parser instead.

option_class (默认: optparse.Option)

Class to use when adding options to the parser in add_option().

version (默认: None)

A version string to print when the user supplies a version option. If you

supply a true value for version, optparse automatically adds a

version option with the single option string --version. The

substring %prog is expanded the same as for usage.

conflict_handler (默认: "error")

Specifies what to do when options with conflicting option strings are

added to the parser; see section

Conflicts between options.

description (默认: None)

A paragraph of text giving a brief overview of your program.

optparse reformats this paragraph to fit the current terminal width

and prints it when the user requests help (after usage, but before the

list of options).

formatter (default: a new IndentedHelpFormatter)

An instance of optparse.HelpFormatter that will be used for printing help

text. optparse provides two concrete classes for this purpose:

IndentedHelpFormatter and TitledHelpFormatter.

add_help_option (默认: True)

If true, optparse will add a help option (with option strings -h

and --help) to the parser.

prog

The string to use when expanding %prog in usage and version

instead of os.path.basename(sys.argv[0]).

epilog (默认: None)

A paragraph of help text to print after the option help.

填充解析器¶

There are several ways to populate the parser with options. The preferred way

is by using OptionParser.add_option(), as shown in section

教程. add_option() can be called in one of two ways:

• pass it an Option instance (as returned by make_option())

• pass it any combination of positional and keyword arguments that are

  acceptable to make_option() (i.e., to the Option constructor), and it

  will create the Option instance for you

The other alternative is to pass a list of pre-constructed Option instances to

the OptionParser constructor, as in:

option_list=[
make_option("-f","--filename",
action="store",type="string",dest="filename"),
make_option("-q","--quiet",
action="store_false",dest="verbose"),
]
parser=OptionParser(option_list=option_list)

(make_option() is a factory function for creating Option instances;

currently it is an alias for the Option constructor. A future version of

optparse may split Option into several classes, and make_option()

will pick the right class to instantiate. Do not instantiate Option directly.)

定义选项¶

Each Option instance represents a set of synonymous command-line option strings,

e.g. -f and --file. You can specify any number of short or

long option strings, but you must specify at least one overall option string.

The canonical way to create an Option instance is with the

add_option() method of OptionParser.

OptionParser.add_option(option)¶

OptionParser.add_option(*opt_str, attr=value, ...)

To define an option with only a short option string:

parser.add_option("-f",attr=value,...)

And to define an option with only a long option string:

parser.add_option("--foo",attr=value,...)

The keyword arguments define attributes of the new Option object. The most

important option attribute is action, and it largely

determines which other attributes are relevant or required. If you pass

irrelevant option attributes, or fail to pass required ones, optparse

raises an OptionError exception explaining your mistake.

An option's action determines what optparse does when it encounters

this option on the command-line. The standard option actions hard-coded into

optparse are:

"store"

存储此选项的参数（默认）

"store_const"

store a constant value

"store_true"

store True

"store_false"

store False

"append"

append this option's argument to a list

"append_const"

将常量值附加到列表

"count"

increment a counter by one

"callback"

调用指定函数

"help"

打印用法消息，包括所有选项和文档

(If you don't supply an action, the default is "store". For this action,

you may also supply type and dest option

attributes; see Standard option actions.)

As you can see, most actions involve storing or updating a value somewhere.

optparse always creates a special object for this, conventionally called

options (it happens to be an instance of optparse.Values). Option

arguments (and various other values) are stored as attributes of this object,

according to the dest (destination) option attribute.

For example, when you call

parser.parse_args()

one of the first things optparse does is create the options object:

options=Values()

If one of the options in this parser is defined with

parser.add_option("-f","--file",action="store",type="string",dest="filename")

and the command-line being parsed includes any of the following:

-ffoo
-ffoo
--file=foo
--filefoo

then optparse, on seeing this option, will do the equivalent of

options.filename="foo"

The type and dest option attributes are almost

as important as action, but action is the only

one that makes sense for all options.

Option attributes¶

The following option attributes may be passed as keyword arguments to

OptionParser.add_option(). If you pass an option attribute that is not

relevant to a particular option, or fail to pass a required option attribute,

optparse raises OptionError.

Option.action¶

(默认: "store")

Determines optparse's behaviour when this option is seen on the

command line; the available options are documented here.

Option.type¶

(默认: "string")

The argument type expected by this option (e.g., "string" or "int");

the available option types are documented here.

Option.dest¶

(default: derived from option strings)

If the option's action implies writing or modifying a value somewhere, this

tells optparse where to write it: dest names an

attribute of the options object that optparse builds as it parses

the command line.

Option.default¶

The value to use for this option's destination if the option is not seen on

the command line. See also OptionParser.set_defaults().

Option.nargs¶

(默认: 1)

How many arguments of type type should be consumed when this

option is seen. If > 1, optparse will store a tuple of values to

dest.

Option.const¶

For actions that store a constant value, the constant value to store.

Option.choices¶

For options of type "choice", the list of strings the user may choose

from.

Option.callback¶

For options with action "callback", the callable to call when this option

is seen. See section Option Callbacks for detail on the

arguments passed to the callable.

Option.callback_args¶

Option.callback_kwargs¶

Additional positional and keyword arguments to pass to callback after the

four standard callback arguments.

Option.help¶

Help text to print for this option when listing all available options after

the user supplies a help option (such as --help). If

no help text is supplied, the option will be listed without help text. To

hide this option, use the special value optparse.SUPPRESS_HELP.

Option.metavar¶

(default: derived from option strings)

Stand-in for the option argument(s) to use when printing help text. See

section 教程 for an example.

Standard option actions¶

The various option actions all have slightly different requirements and effects.

Most actions have several relevant option attributes which you may specify to

guide optparse's behaviour; a few have required attributes, which you

must specify for any option using that action.

• "store" [relevant: type, dest,

  nargs, choices]

  The option must be followed by an argument, which is converted to a value

  according to type and stored in dest. If

  nargs > 1, multiple arguments will be consumed from the

  command line; all will be converted according to type and

  stored to dest as a tuple. See the

  Standard option types section.

  If choices is supplied (a list or tuple of strings), the type

  defaults to "choice".

  If type is not supplied, it defaults to "string".

  If dest is not supplied, optparse derives a destination

  from the first long option string (e.g., --foo-bar implies

  foo_bar). If there are no long option strings, optparse derives a

  destination from the first short option string (e.g., -f implies f).

  示例:

  parser.add_option("-f")
  parser.add_option("-p",type="float",nargs=3,dest="point")
  

  As it parses the command line

  -ffoo.txt-p1-3.54-fbar.txt
  

  optparse will set

  options.f="foo.txt"
  options.point=(1.0,-3.5,4.0)
  options.f="bar.txt"
  

• "store_const" [required: const; relevant:

  dest]

  The value const is stored in dest.

  示例:

  parser.add_option("-q","--quiet",
  action="store_const",const=0,dest="verbose")
  parser.add_option("-v","--verbose",
  action="store_const",const=1,dest="verbose")
  parser.add_option("--noisy",
  action="store_const",const=2,dest="verbose")
  

  If --noisy is seen, optparse will set

  options.verbose=2
  

• "store_true" [relevant: dest]

  A special case of "store_const" that stores True to

  dest.

• "store_false" [relevant: dest]

  Like "store_true", but stores False.

  示例:

  parser.add_option("--clobber",action="store_true",dest="clobber")
  parser.add_option("--no-clobber",action="store_false",dest="clobber")
  

• "append" [relevant: type, dest,

  nargs, choices]

  The option must be followed by an argument, which is appended to the list in

  dest. If no default value for dest is

  supplied, an empty list is automatically created when optparse first

  encounters this option on the command-line. If nargs > 1,

  multiple arguments are consumed, and a tuple of length nargs

  is appended to dest.

  The defaults for type and dest are the same as

  for the "store" action.

  示例:

  parser.add_option("-t","--tracks",action="append",type="int")
  

  If -t3 is seen on the command-line, optparse does the equivalent

  of:

  options.tracks=[]
  options.tracks.append(int("3"))
  

  If, a little later on, --tracks=4 is seen, it does:

  options.tracks.append(int("4"))
  

  The append action calls the append method on the current value of the

  option. This means that any default value specified must have an append

  method. It also means that if the default value is non-empty, the default

  elements will be present in the parsed value for the option, with any values

  from the command line appended after those default values:

  >>> parser.add_option("--files",action="append",default=['~/.mypkg/defaults'])
  >>> opts,args=parser.parse_args(['--files','overrides.mypkg'])
  >>> opts.files
  ['~/.mypkg/defaults', 'overrides.mypkg']
  

• "append_const" [required: const; relevant:

  dest]

  Like "store_const", but the value const is appended to

  dest; as with "append", dest defaults to

  None, and an empty list is automatically created the first time the option

  is encountered.

• "count" [relevant: dest]

  Increment the integer stored at dest. If no default value is

  supplied, dest is set to zero before being incremented the

  first time.

  示例:

  parser.add_option("-v",action="count",dest="verbosity")
  

  The first time -v is seen on the command line, optparse does the

  equivalent of:

  options.verbosity=0
  options.verbosity+=1
  

  Every subsequent occurrence of -v results in

  options.verbosity+=1
  

• "callback" [required: callback; relevant:

  type, nargs, callback_args,

  callback_kwargs]

  Call the function specified by callback, which is called as

  func(option,opt_str,value,parser,*args,**kwargs)
  

  See section Option Callbacks for more detail.

• "help"

  Prints a complete help message for all the options in the current option

  parser. The help message is constructed from the usage string passed to

  OptionParser's constructor and the help string passed to every

  option.

  If no help string is supplied for an option, it will still be

  listed in the help message. To omit an option entirely, use the special value

  optparse.SUPPRESS_HELP.

  optparse automatically adds a help option to all

  OptionParsers, so you do not normally need to create one.

  示例:

  fromoptparseimportOptionParser,SUPPRESS_HELP
  # usually, a help option is added automatically, but that can
  # be suppressed using the add_help_option argument
  parser=OptionParser(add_help_option=False)
  parser.add_option("-h","--help",action="help")
  parser.add_option("-v",action="store_true",dest="verbose",
  help="Be moderately verbose")
  parser.add_option("--file",dest="filename",
  help="Input file to read data from")
  parser.add_option("--secret",help=SUPPRESS_HELP)
  

  If optparse sees either -h or --help on the command line,

  it will print something like the following help message to stdout (assuming

  sys.argv[0] is "foo.py"):

  Usage: foo.py [options]
  Options:
    -h, --help        Show this help message and exit
    -v                Be moderately verbose
    --file=FILENAME   Input file to read data from
  

  After printing the help message, optparse terminates your process with

  sys.exit(0).

• "version"

  Prints the version number supplied to the OptionParser to stdout and exits.

  The version number is actually formatted and printed by the

  print_version() method of OptionParser. Generally only relevant if the

  version argument is supplied to the OptionParser constructor. As with

  help options, you will rarely create version options,

  since optparse automatically adds them when needed.

Standard option types¶

optparse has five built-in option types: "string", "int",

"choice", "float" and "complex". If you need to add new

option types, see section Extending optparse.

Arguments to string options are not checked or converted in any way: the text on

the command line is stored in the destination (or passed to the callback) as-is.

Integer arguments (type "int") are parsed as follows:

• if the number starts with 0x, it is parsed as a hexadecimal number

• if the number starts with 0, it is parsed as an octal number

• if the number starts with 0b, it is parsed as a binary number

• otherwise, the number is parsed as a decimal number

The conversion is done by calling int() with the appropriate base (2, 8,

10, or 16). If this fails, so will optparse, although with a more useful

error message.

"float" and "complex" option arguments are converted directly with

float() and complex(), with similar error-handling.

"choice" options are a subtype of "string" options. The

choices option attribute (a sequence of strings) defines the

set of allowed option arguments. optparse.check_choice() compares

user-supplied option arguments against this master list and raises

OptionValueError if an invalid string is given.

解析参数¶

The whole point of creating and populating an OptionParser is to call its

parse_args() method:

(options,args)=parser.parse_args(args=None,values=None)

输入参数的位置

args

the list of arguments to process (default: sys.argv[1:])

values

an optparse.Values object to store option arguments in (default: a

new instance of Values) -- if you give an existing object, the

option defaults will not be initialized on it

and the return values are

options

the same object that was passed in as values, or the optparse.Values

instance created by optparse

args

the leftover positional arguments after all options have been processed

The most common usage is to supply neither keyword argument. If you supply

values, it will be modified with repeated setattr() calls (roughly one

for every option argument stored to an option destination) and returned by

parse_args().

If parse_args() encounters any errors in the argument list, it calls the

OptionParser's error() method with an appropriate end-user error message.

This ultimately terminates your process with an exit status of 2 (the

traditional Unix exit status for command-line errors).

Querying and manipulating your option parser¶

The default behavior of the option parser can be customized slightly, and you

can also poke around your option parser and see what's there. OptionParser

provides several methods to help you out:

OptionParser.disable_interspersed_args()¶

Set parsing to stop on the first non-option. For example, if -a and

-b are both simple options that take no arguments, optparse

normally accepts this syntax:

prog-aarg1-barg2

and treats it as equivalent to

prog-a-barg1arg2

To disable this feature, call disable_interspersed_args(). This

restores traditional Unix syntax, where option parsing stops with the first

non-option argument.

Use this if you have a command processor which runs another command which has

options of its own and you want to make sure these options don't get

confused. For example, each command might have a different set of options.

OptionParser.enable_interspersed_args()¶

Set parsing to not stop on the first non-option, allowing interspersing

switches with command arguments. This is the default behavior.

OptionParser.get_option(opt_str)¶

Returns the Option instance with the option string opt_str, or None if

no options have that option string.

OptionParser.has_option(opt_str)¶

Return True if the OptionParser has an option with option string opt_str

(e.g., -q or --verbose).

OptionParser.remove_option(opt_str)¶

If the OptionParser has an option corresponding to opt_str, that

option is removed. If that option provided any other option strings, all of

those option strings become invalid. If opt_str does not occur in any

option belonging to this OptionParser, raises ValueError.

Conflicts between options¶

If you're not careful, it's easy to define options with conflicting option

strings:

parser.add_option("-n","--dry-run",...)
...
parser.add_option("-n","--noisy",...)

(This is particularly true if you've defined your own OptionParser subclass with

some standard options.)

Every time you add an option, optparse checks for conflicts with existing

options. If it finds any, it invokes the current conflict-handling mechanism.

You can set the conflict-handling mechanism either in the constructor:

parser=OptionParser(...,conflict_handler=handler)

or with a separate call:

parser.set_conflict_handler(handler)

The available conflict handlers are:

"error" (默认)

assume option conflicts are a programming error and raise

OptionConflictError

"resolve"

resolve option conflicts intelligently (see below)

As an example, let's define an OptionParser that resolves conflicts

intelligently and add conflicting options to it:

parser=OptionParser(conflict_handler="resolve")
parser.add_option("-n","--dry-run",...,help="do no harm")
parser.add_option("-n","--noisy",...,help="be noisy")

At this point, optparse detects that a previously-added option is already

using the -n option string. Since conflict_handler is "resolve",

it resolves the situation by removing -n from the earlier option's list of

option strings. Now --dry-run is the only way for the user to activate

that option. If the user asks for help, the help message will reflect that:

Options:
--dry-rundonoharm
...
-n,--noisybenoisy

It's possible to whittle away the option strings for a previously-added option

until there are none left, and the user has no way of invoking that option from

the command-line. In that case, optparse removes that option completely,

so it doesn't show up in help text or anywhere else. Carrying on with our

existing OptionParser:

parser.add_option("--dry-run",...,help="new dry-run option")

At this point, the original -n/--dry-run option is no longer

accessible, so optparse removes it, leaving this help text:

Options:
...
-n,--noisybenoisy
--dry-runnewdry-runoption

parser.add_option("-c",action="callback",callback=my_callback)

defmy_callback(option,opt,value,parser):

func(option,opt_str,value,parser,*args,**kwargs)

defrecord_foo_seen(option,opt_str,value,parser):
parser.values.saw_foo=True
parser.add_option("--foo",action="callback",callback=record_foo_seen)

defcheck_order(option,opt_str,value,parser):
ifparser.values.b:
raiseOptionValueError("can't use -a after -b")
parser.values.a=1
...
parser.add_option("-a",action="callback",callback=check_order)
parser.add_option("-b",action="store_true",dest="b")

defcheck_order(option,opt_str,value,parser):
ifparser.values.b:
raiseOptionValueError("can't use %s after -b"%opt_str)
setattr(parser.values,option.dest,1)
...
parser.add_option("-a",action="callback",callback=check_order,dest='a')
parser.add_option("-b",action="store_true",dest="b")
parser.add_option("-c",action="callback",callback=check_order,dest='c')

defcheck_moon(option,opt_str,value,parser):
ifis_moon_full():
raiseOptionValueError("%s option invalid when moon is full"
%opt_str)
setattr(parser.values,option.dest,1)
...
parser.add_option("--foo",
action="callback",callback=check_moon,dest="foo")

defstore_value(option,opt_str,value,parser):
setattr(parser.values,option.dest,value)
...
parser.add_option("--foo",
action="callback",callback=store_value,
type="int",nargs=3,dest="foo")

defvararg_callback(option,opt_str,value,parser):
assertvalueisNone
value=[]
deffloatable(str):
try:
float(str)
returnTrue
exceptValueError:
returnFalse
forarginparser.rargs:
# stop on --foo like options
ifarg[:2]=="--"andlen(arg)>2:
break
# stop on -a, but not on -3 or -3.0
ifarg[:1]=="-"andlen(arg)>1andnotfloatable(arg):
break
value.append(arg)
delparser.rargs[:len(value)]
setattr(parser.values,option.dest,value)
...
parser.add_option("-c","--callback",dest="vararg_attr",
action="callback",callback=vararg_callback)

fromcopyimportcopy
fromoptparseimportOption,OptionValueError

defcheck_complex(option,opt,value):
try:
returncomplex(value)
exceptValueError:
raiseOptionValueError(
"option %s: invalid complex value: %r"%(opt,value))

classMyOption(Option):
TYPES=Option.TYPES+("complex",)
TYPE_CHECKER=copy(Option.TYPE_CHECKER)
TYPE_CHECKER["complex"]=check_complex

parser=OptionParser(option_class=MyOption)
parser.add_option("-c",type="complex")

option_list=[MyOption("-c",action="store",type="complex",dest="c")]
parser=OptionParser(option_list=option_list)

--names=foo,bar--namesblah--namesding,dong

["foo","bar","blah","ding","dong"]

classMyOption(Option):
ACTIONS=Option.ACTIONS+("extend",)
STORE_ACTIONS=Option.STORE_ACTIONS+("extend",)
TYPED_ACTIONS=Option.TYPED_ACTIONS+("extend",)
ALWAYS_TYPED_ACTIONS=Option.ALWAYS_TYPED_ACTIONS+("extend",)
deftake_action(self,action,dest,opt,value,values,parser):
ifaction=="extend":
lvalue=value.split(",")
values.ensure_value(dest,[]).extend(lvalue)
else:
Option.take_action(
self,action,dest,opt,value,values,parser)