Why does the getopt method have getopt(args, options[, long_options]) not getopt(args, options,[ long_options]) as its signature?

Question 1

The function has 2 required arguments (args and options) and one option that is not required (long_options). The exact meaning of args, options and long_options can all be found in the documentation

Basically, if you want the commandline to be parsed as:

myprogram --foo=bar

Then you need to have a long_options list which looks something like ['--foo='], but if you want to parse it as:

myprogram -f bar

then you would have options set to 'f:'. Of course, you can mix and match as much as you want.

For what its worth, I would never recommend anyone use getopt in favor of optparse or (even better) argparse. These later two modules make working with getopt feel like trying to use a hammer to build yourself a new computer ...

Question 2

The arguments args and options are mandatory arguments, and long_options is optional argument to the function i.e. it may or may not be provided. You will provide it in your command line utility if you intend to support long options like --format along with -f .

Example of Linux ls utility, showing both options and long options, which start with --

LS(1)                                       User Commands                                       LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information about the FILEs (the current directory by default).  Sort entries alphabeti‐
       cally if none of -cftuvSUX nor --sort is specified.

       Mandatory arguments to long options are mandatory for short options too.

       -a, --all
              do not ignore entries starting with .

       -A, --almost-all
              do not list implied . and ..

       --author   <--- LONG OPTIONS OF COMMAND LINE
              with -l, print the author of each file

Question 3

you should be using argparse instead of getopt which is now deprecated. About explanations, the documentation is really accessible:

and about your specific question, I think you'd have your answer there:

http://docs.python.org/dev/library/argparse.html#option-value-syntax

(read about this and that to know why you should be using argparse ; even getopt documentation states (sic) "Users who are unfamiliar with the C getopt() function or who would like to write less code and get better help and error messages should consider using the argparse module instead.")

AFTER LAST EDIT: when in a documentation you see a part of the prototype surrounded by square brackets, by convention, that means that part is optional, whereas the part that's before is mandatory. When you want to call getopt.getopt() you shall valuate args and options`.

Now, it is not getopt.getopt(args, options, [long_options]) because it would mean the last comma would be mandatory too, though if you call getopt.getopt(args, options,) it is not a valid python expression.

AFTER LAST COMMENT: well, that syntax is a convention used across almost every tool existing on unix platform... I don't know if it has been defined somewhere, but I wouldn't be surprised if it was older than the POSIX specification itself! The only piece of "documentation" I could find is the following wikipedia page, but it lacks references:

http://en.wikipedia.org/wiki/Usage_message

I found a course at caltech (lookup section "Optional arguments in usage statements") that tells to use square brackets for optional arguments:

http://courses.cms.caltech.edu/cs11/material/general/usage.html

And finally you're not the first asking this here on stack overflow, there are at least two other questions on the same subject:

If you look at manpages on your system, you'll see all of them using that syntax, all parameters in square brackets being optional, e.g.: ls manpage, cat manpage, even macos' open manpage uses that convention!

I hope this time I did answer your question!