HTML Documentation for getargs.py.
This is the official documentation for getargs.py, a command-line argument-parsing module for Python.
Generalized option handling for Python programs.
from getargs import *
arglist=( ('i',0,"An integer argument",None), ('f',0.0,"A Float argument",3.14159), ... )
if xarg.value('i')!=None: do something. ...
if xarg.value('j'): xarg.setvalue('g',0)
Arglist fields are:
Single letter options that take arguments (non-boolean) may do so in one of two ways, either immediately following the keyletter ('-i29') or following a space ('-i 29'). The choice is the user’s, not the programmer’s. Single letter options of the autoincrementing variety have a default value of 0. Each repetition of the keyletter in the option arguments increments the flag value by one. "-i" has a value of 1, while "-iiii" has a value of 4, for example.
Long options that take arguments (non-boolean) may do so in one of two ways, either separated by a space ('-integer 29') or separated by a separator character, by default the '=' sign ('-integer=29'). Again, the choice is left to the user, not the programmer. Autoincrementing long options are not supported.
Options that require list or tuple arguments need such an argument in the form of a list, which probably needs to be quoted. By default, the list has the form
'a b c d e f'
but by using the setsep() method the programmer can have it be of the form
The order of options is not significant. You cannot tell if one option has been set on the command line before another; this should not be a problem.
The case of options is significant; 'i' and 'I' are different options, and so are '-integer' and '-Integer' (and also '-inTegeR'). However, on long options, the user only needs to provide sufficient information in order to set or toggle an option. The matching algorithm searches for whatever substring the user provides; if the substring matches more than one option, then it looks first for an exact match. Failing that, it will match the longest option name it can for the substring provided. I.e., if there are two options -h and -help, and the user types '-he', then the option matched will be -help.
The type of these is determined by matching against the value 'nofile', which is defined to be the same as the value returned by 'open("/dev/null","r")'; if users are on a PC or on a Mac, they won’t have "/dev/null", so "nul" is used instead.
If the programmer provides a default value other than None, then there is no way to tell if the option appeared on the command line. However, if the default value is None, then the value() method will return non-None if and only if the user put it in the command line. This even works for boolean options, since the only way for one to be set this way is in the arglist; all other methods set the value to either 0 or 1. Autoincrementing options will have the value 0 if they did not appear on the command line.
The only variables in the getargs module are 'nofile', which is used only to find the type of file options, and VERSION, which can be found below.
Functions provided by the getargs module are:
|nofunc()||Provided to find the type of function options.|
|isnumber()||Used to determine if a string can be converted into an integer; the string can contain only digits or '-' or '+'.|
|islong()||Same as isnumber(), except the string can also contain the letter 'L'.|
|isfloat()||The string contains digits, a period, signs or the letters 'e' or 'E'.|
|manpage()||Returns the __doc__ attribute for the getargs module.|
The only class provided by getargs is class arguments.
The methods provided by the arguments class are:
-h] Helpinstead of
xarg=arguments('-',arglist) progname,sys.argv=xarg.getargs(sys.argv)After which sys.argv and all options between argv and the first non-option argument will be consumed, leaving the program responsible for any remaining command-line parameters. Values of any of the options that were consumed may be obtained through the value() method.
I first built a version of getargs in C many years ago, but I no longer support the C version; I never released it because I was never satisfied with it, and because it was much too delicate for public performance. Also, because it was written in C (not C++), it could be very complicated to use. The Python version cures all those problems, although I recognize that it’s probably more complicated than some people would like. I’m always open to simplification suggestions.
Functions referred to in arglist must be defined before the arglist. The program name (progname) must be defined (as in "progname = sys.argv[ 0 ]") before you can use it in any function referred to in the arglist. Such functions are called as soon as they are found in the command line.
There’s no way to specify complex numbers on the command line, and no complex argument type. This will eventually be remedied.
While there is no way to tell if any option has been set before any other option, the parser does proceed in a linear manner; i.e., "-out foo -help" would actually set the "-out" value "foo" before the "-help" function was called. Not that there’s much utility in that.
Report any bugs found to . Report any infelicitous grammar or language errors in this __doc__ attribute or HTML page to the same place.
Thank you for using getargs.
Copyright 1994-2007 by
Ivan Van Laningham.
All rights reserved.
License granted to anyone for non-commercial use, as long as this copyright notice and the author’s name are included in any modifications, and such modifications are reported to the author for consideration in future releases.
Version 1.3, 126.96.36.199.6 13 Kimi 14 Yax G1 11:11:01
Here’s a complete test program in Python:
#!/usr/local/bin/python # # Copyright 1999 # by Ivan Van Laningham # All Rights Reserved. # import sys import os import time import math import string from getargs import * if __name__=="__main__": progname=sys.argv def printversion(l=0): print "Version 1.%s"%(l) def man(l=0): print manpage() sys.exit(0) def helpPig(l=0): print "%s: Usage %s any old gunk"%(progname,xarg.options()) print xarg, print "I'm Porky Pig" sys.exit(0) def helpHog(l=0): print xarg, print "I'm a HAWG!" arglist=(('v',nofunc,"Function(print version)", printversion ), ('M',nofunc,"Man page",man), ('-manual',nofunc,"Man page",man), ('i',0,"Integer",None), ('f',0.0,"Float",None), ('+snorgle',"","A Fubar String",None), ('tuple',(),"Nameless tuple",None), ('q',None,"None test",None), ('list',,"Nameless list",None), ('h',nofunc,"Help",helpPig), ('hogs',nofunc,"Help",helpHog), ('qln',0L,"Funky Long",None), ('-longarg',None,"Boolean long argument"), # Adding leading - provides —longarg syntax. ... ('-output',nofile,"the output file","/tmp/dogbone"), ('-longest',None,"Boolean long argument"), # Adding leading - provides —longarg syntax. ... ('-longerlongerandlonger',0,"Integer long argument",None), # Adding leading - provides —longarg syntax. ... ) xarg=arguments('-',arglist) progname,sys.argv=xarg.getargs(sys.argv) helpHog() q=xarg.keys() for ii in q: print ii,xarg.value(ii) o=0 for n in range(len(sys.argv)): print o,sys.argv[n] o=o+1
You can download getargs.py, testarg.py and this file, getargs.html at:
Main web site: http://www.pauahtun.org