Section 3.7. Command-Line Arguments

3.7. Command-Line Arguments

The sys module is also where Python makes available the words typed on the command that is used to start a Python script. These words are usually referred to as command-line arguments and show up in sys.argv, a built-in list of strings. C programmers may notice its similarity to the C argv array (an array of C strings). It's not much to look at interactively, because no command-line arguments are passed to start up Python in this mode:

 >>> sys.argv [''] 

To really see what arguments are about, we need to run a script from the shell command line. Example 3-2 shows an unreasonably simple one that just prints the argv list for inspection.

Example 3-2. PP3E\System\testargv.py

 import sys print sys.argv 

Running this script prints the command-line arguments list; note that the first item is always the name of the executed Python script file itself, no matter how the script was started (see the sidebar titled "Executable Scripts on Unix," later in this chapter).

 C:\...\PP3E\System>python testargv.py ['testargv.py'] C:\...\PP3E\System>python testargv.py spam eggs cheese ['testargv.py', 'spam', 'eggs', 'cheese'] C:\...\PP3E\System>python testargv.py -i data.txt -o results.txt ['testargv.py', '-i', 'data.txt', '-o', 'results.txt'] 

The last command here illustrates a common convention. Much like function arguments, command-line options are sometimes passed by position and sometimes by name using a "-name value" word pair. For instance, the pair -i data.txt means the -i option's value is data.txt (e.g., an input filename). Any words can be listed, but programs usually impose some sort of structure on them.

Command-line arguments play the same role in programs that function arguments do in functions: they are simply a way to pass information to a program that can vary per program run. Because they don't have to be hardcoded, they allow scripts to be more generally useful. For example, a file-processing script can use a command-line argument as the name of the file it should process; see the more.py script we met in Example 3-1 for a prime example. Other scripts might accept processing mode flags, Internet addresses, and so on.

Once you start using command-line arguments regularly, though, you'll probably find it inconvenient to keep writing code that fishes through the list looking for words. More typically, programs translate the arguments list on startup into structures that are more conveniently processed. Here's one way to do it: the script in Example 3-3 scans the argv list looking for -optionname optionvalue word pairs and stuffs them into a dictionary by option name for easy retrieval.

Example 3-3. PP3E\System\testargv2.py

 # collect command-line options in a dictionary def getopts(argv):     opts = {}     while argv:         if argv[0][0] == '-':                  # find "-name value" pairs             opts[argv[0]] = argv[1]            # dict key is "-name" arg             argv = argv[2:]         else:             argv = argv[1:]     return opts if _ _name_ _ == '_ _main_ _':     from sys import argv                       # example client code     myargs = getopts(argv)     if myargs.has_key('-i'):         print myargs['-i']     print myargs 

You might import and use such a function in all your command-line tools. When run by itself, this file just prints the formatted argument dictionary:

 C:\...\PP3E\System>python testargv2.py {} C:\...\PP3E\System>python testargv2.py -i data.txt -o results.txt data.txt {'-o': 'results.txt', '-i': 'data.txt'} 

Naturally, we could get much more sophisticated here in terms of argument patterns, error checking, and the like. We could also use standard and more advanced command-line processing tools in the Python library to parse arguments; see the standard getopt library module and the newer optparse in the library manual for other options. In general, the more configurable your scripts, the more you must invest in command-line processing logic complexity.

Executable Scripts on Unix

Unix and Linux users: you can also make text files of Python source code directly executable by adding a special line at the top with the path to the Python interpreter and giving the file executable permission. For instance, type this code into a text file called myscript:

 #!/usr/bin/python print 'And nice red uniforms' 

The first line is normally taken as a comment by Python (it starts with a #); but when this file is run, the operating system sends lines in this file to the interpreter listed after #! on line 1. If this file is made directly executable with a shell command of the form chmod +x myscript, it can be run directly without typing python in the command, as though it were a binary executable program:

 % myscript a b c And nice red uniforms 

When run this way, sys.argv will still have the script's name as the first word in the list: ["myscript", "a", "b", "c"], exactly as if the script had been run with the more explicit and portable command form python myscript a b c. Making scripts directly executable is actually a Unix trick, not a Python feature, but it's worth pointing out that it can be made a bit less machine dependent by listing the Unix env command at the top instead of a hardcoded path to the Python executable:

 #!/usr/bin/env python print 'Wait for it...' 

When coded this way, the operating system will employ your environment variable settings to locate your Python interpreter (your PATH variable, on most platforms). If you run the same script on many machines, you need only change your environment settings on each machine (you don't need to edit Python script code). Of course, you can always run Python files with a more explicit command line:

 % python myscript a b c 

This assumes that the python interpreter program is on your system's search path setting (otherwise, you need to type its full path), but it works on any Python platform with a command line. Since this is more portable, I generally use this convention in the book's examples, but consult your Unix manpages for more details on any of the topics mentioned here. Even so, these special #! lines will show up in many examples in this book just in case readers want to run them as executables on Unix or Linux; on other platforms, they are simply ignored as Python comments.

Note that on recent flavors of Windows, you can usually also type a script's filename directly (without the word python) to make it go, and you don't have to add a #! line at the top. Python uses the Windows registry on this platform to declare itself as the program that opens files with Python extensions (.py and others). This is also why you can launch files on Windows by clicking on them.