getopt — C-style parser for command line options¶

Source code:Lib/getopt.py

This module helps scripts to parse the command line arguments insys.argv.It supports the same conventions as the Unixgetopt() function (includingthe special meanings of arguments of the form ‘-’ and ‘--‘). Longoptions similar to those supported by GNU software may be used as well via anoptional third argument.

This module provides two functions and anexception:

getopt.getopt(args,shortopts,longopts=[])¶

Parses command line options and parameter list.args is the argument list tobe parsed, without the leading reference to the running program. Typically, thismeanssys.argv[1:].shortopts is the string of option letters that thescript wants to recognize, with options that require an argument followed by acolon (':'; i.e., the same format that Unixgetopt() uses).

Note

Unlike GNUgetopt(), after a non-option argument, all furtherarguments are considered also non-options. This is similar to the waynon-GNU Unix systems work.

longopts, if specified, must be a list of strings with the names of thelong options which should be supported. The leading'--' charactersshould not be included in the option name. Long options which require anargument should be followed by an equal sign ('='). Optional argumentsare not supported. To accept only long options,shortopts should be anempty string. Long options on the command line can be recognized so long asthey provide a prefix of the option name that matches exactly one of theaccepted options. For example, iflongopts is['foo','frob'], theoption--fo will match as--foo, but--f willnot match uniquely, soGetoptError will be raised.

The return value consists of two elements: the first is a list of(option,value) pairs; the second is the list of program arguments left after theoption list was stripped (this is a trailing slice ofargs). Eachoption-and-value pair returned has the option as its first element, prefixedwith a hyphen for short options (e.g.,'-x') or two hyphens for longoptions (e.g.,'--long-option'), and the option argument as itssecond element, or an empty string if the option has no argument. Theoptions occur in the list in the same order in which they were found, thusallowing multiple occurrences. Long and short options may be mixed.

getopt.gnu_getopt(args,shortopts,longopts=[])¶

This function works likegetopt(), except that GNU style scanning mode isused by default. This means that option and non-option arguments may beintermixed. Thegetopt() function stops processing options as soon as anon-option argument is encountered.

If the first character of the option string is'+', or if the environmentvariablePOSIXLY_CORRECT is set, then option processing stops assoon as a non-option argument is encountered.

exceptiongetopt.GetoptError¶

This is raised when an unrecognized option is found in the argument list or whenan option requiring an argument is given none. The argument to the exception isa string indicating the cause of the error. For long options, an argument givento an option which does not require one will also cause this exception to beraised. The attributesmsg andopt give the error message andrelated option; if there is no specific option to which the exception relates,opt is an empty string.

exceptiongetopt.error¶

Alias forGetoptError; for backward compatibility.

An example using only Unix style options:

>>>importgetopt>>>args='-a -b -cfoo -d bar a1 a2'.split()>>>args['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']>>>optlist,args=getopt.getopt(args,'abc:d:')>>>optlist[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]>>>args['a1', 'a2']

Using long option names is equally easy:

>>>s='--condition=foo --testing --output-file abc.def -x a1 a2'>>>args=s.split()>>>args['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']>>>optlist,args=getopt.getopt(args,'x',[...'condition=','output-file=','testing'])>>>optlist[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]>>>args['a1', 'a2']

In a script, typical usage is something like this:

importgetopt,sysdefmain():try:opts,args=getopt.getopt(sys.argv[1:],"ho:v",["help","output="])exceptgetopt.GetoptErroraserr:# print help information and exit:print(err)# will print something like "option -a not recognized"usage()sys.exit(2)output=Noneverbose=Falseforo,ainopts:ifo=="-v":verbose=Trueelifoin("-h","--help"):usage()sys.exit()elifoin("-o","--output"):output=aelse:assertFalse,"unhandled option"# ...if__name__=="__main__":main()

Note that an equivalent command line interface could be produced with less codeand more informative help and error messages by using theargparse module:

importargparseif__name__=='__main__':parser=argparse.ArgumentParser()parser.add_argument('-o','--output')parser.add_argument('-v',dest='verbose',action='store_true')args=parser.parse_args()# ... do something with args.output ...# ... do something with args.verbose ..