3.2 System Command Lines and Files

Although the interactive prompt is great for experimenting and testing, it has one big disadvantage: programs you type there go away as soon as the Python interpreter executes them. The code you type interactively is never stored in a file, so you can't run it again without retyping it from scratch. Cut-and-paste and command recall can help some here, but not much, especially when you start writing larger programs. To cut and paste code from an interactive session, you have to edit out Python prompts, program outputs, and so on.

To save programs permanently, you need to write your code in files, usually known as modules. Modules are simply text files containing Python statements. Once coded, you can ask the Python interpreter to execute the statements in such a file any number of times, and in a variety of ways—by system command lines, by file icon clicks, by options in the IDLE user interface, and more. However they are run, Python executes all the code in a module file from top to bottom, each time you run the file. Such files are often referred to as programs in Python—a series of precoded statements.

The next few sections explore ways to run code typed into module files. In this section we run files in the most basic way: by listing their names in a python command line entered at a system prompt. As a first example, suppose we start our favorite text editor (e.g., vi, notepad, or the IDLE editor) and type three Python statements into a text file named spam.py:

print 2 ** 8                              # Raise to a power.
print 'the bright side ' + 'of life'      # + means concatenation.

This file contains two Python print statements and Python comments to the right. Text after a # is simply ignored as a human-readable comment, and is not part of the statement's syntax. Again, ignore the syntax of code in this file for now. The point to notice is that we've typed code into a file, rather than at the interactive prompt. In the process, we've coded a fully-functional Python script.

Once we've saved this text file, we can ask Python to run it by listing its full filename as a first argument on a python command, typed at the system shell's prompt:

% python spam.py
256
the bright side of life

Here again, you will type such a system shell command in whatever your system provides for command-line entry—a DOS console window, an xterm, or similar. Remember to replace "python" with a full directory path if your PATH setting is not configured. The output of this little script shows up after the command is typed—it's the result of the two print statements in the text file.

Notice that the module file is called spam.py. As for all top-level files, it could also be called simply spam, but files of code we want to import into a client have to end with a .py suffix. We'll study imports later in this chapter. Because you may want to import a file in the future, it's a good idea to use .py suffixes for most Python files that you code. Some text editors also detect Python files by their .py suffix; if the suffix is not present, you may not get things like syntax colorization and automatic indentation.

Because this scheme uses shell command lines to start Python programs, all the usual shell syntax applies. For instance, we can route the output of a Python script to a file in order to save it, by using special shell syntax:

% python spam.py > saveit.txt

In this case, the two output lines shown in the prior run show up in file saveit.txt, instead of being printed. This is generally known as stream redirection; it works for both input and output text, and works on both Windows and Unix-like systems. It also has little to do with Python (Python simply supports it), so we will skip further details on redirection here.

If you are working on a Windows or MS-DOS platform, this example works the same, but the system prompt is normally different:

C:\Python22>python spam.py
256
the bright side of life

As usual, be sure to type the full path to Python if you haven't set your PATH environment variable:

D:\temp>C:\python22\python spam.py
256
the bright side of life

(On some versions of Windows, you can also type just the name of your script, regardless of the directory you work in. Because newer Windows systems use the Windows registry to find a program with which to run a file, you don't need to list it on the command line explicitly.)

Finally, remember to give the full path to your script file if it lives a different directory than the one you are working in. For example, the following system command line, run from D:\other, assumes Python is on your system path, but runs a file located elsewhere:

D:\other>python c:\code\myscript.py

3.2.1 Using Command Lines and Files

Running program files from system command lines is also a fairly straightforward launch option, especially if you are familiar with command lines in general from prior Unix or DOS work. Here are a few pointers about common beginner traps before moving on:

• Beware of automatic extensions on Windows. If you use the Notepad program to code program files on Windows, be careful to pick type All Files when it comes time to save your file, and give your file a .py suffix explicitly. Otherwise, Notepad saves your file with a ".txt" extension (e.g., as spam.py.txt), making it difficult to run in some launching schemes.

  Worse, Windows hides file extensions by default unless you have changed your view options, so you may not even notice that you've coded a text file, not a Python file. The file's icon may give this away—if it's not a snake, you may have trouble. Un-colored code in IDLE and files that open to edit instead of run when clicked are other symptoms of this problem.

  MS Word similarly adds a .doc extension by default; much worse, it adds formatting characters that are not legal Python syntax. As a rule of thumb, always pick All Files when saving under Windows, or use more programmer-friendly text editors such as IDLE. IDLE does not even add a .py suffix automatically—a feature programmers like, and users do not.

• Use file extensions at system prompts, but not imports. Don't forget to type the full name of your file in system command lines, that is, use python spam.py. This differs from Python import statements we'll meet later in this chapter, which omit both the .py file suffix, and directory path: import spam. This may seem simple, but it's a common mistake.

  At the system prompt, you are in a system shell, not Python, so Python's module file search rules do not apply. Because of that, you must give the .py extension, and can optionally include a full directory path leading to the file you wish to run. For instance, to run a file that resides in a different directory than the one you are working in, you will typically list its full path name (C:\python22>python d:\tests\spam.py). Within Python code, you say just import spam, and rely on the Python module search path to locate your file.

• Use print statements in files. Yes, this was already mentioned in the prior section, but it is so important that it should be said again here. Unlike interactive coding, you generally must use print statements to see output from program files.

3.2.2 Unix Executable Scripts (#!)

If you are going to use Python on a Unix, Linux, or Unix-like system, you can also turn files of Python code into executable programs, much as you would for programs coded in a shell language such as csh or ksh. Such files are usually called executable scripts; in simple terms, Unix-style executable scripts are just normal text files containing Python statements, but with two special properties:

• Their first line is special. Scripts usually start with a first line that begins with the characters #! (often called "hash bang") followed by the path to the Python interpreter on your machine.

• They usually have executable privileges. Script files are usually marked as executable, to tell the operating system that they may be run as top-level programs. On Unix systems, a command such as chmod +x file.py usually does the trick.

Let's look at an example. Suppose we use a text editor again, to create a file of Python code called brian:

#!/usr/local/bin/python
print 'The Bright Side of Life...'         # Another comment here

The special line at the top of the file tells the system where the Python interpreter lives. Technically, the first line is a Python comment. As mentioned earlier, all comments in Python programs start with a # and span to the end of the line; they are a place to insert extra information for human readers of your code. But when a comment such as the first line in this file appears, it's special, since the operating system uses it to find an interpreter for running the program code in the rest of the file.

Also, this file is called simply brian, without the .py suffix used for the module file earlier. Adding a .py to the name wouldn't hurt (and might help us remember that this is a Python program file); but since we don't plan on letting other modules import the code in this file, the name of the file is irrelevant. If we give the file executable privileges with a chmod +x brian shell command, we can run it from the operating system shell as though it were a binary program:

% brian
The Bright Side of Life...

A note for Windows users: the method described here is a Unix trick, and may not work on your platform. Not to worry; just use the basic command-line technique explored earlier. List the file's name on an explicit python command line:^[1]

^[1] As seen when exploring command lines, modern Windows versions also let you type just the name of a .py file at the system command line—they use the registry to know to open the file with Python (e.g., typing brian.py is equivalent to typing python brian.py). This command-line mode is similar in spirit to the Unix #!. Note that some programs may actually interpret and use a first #! line on Windows much like Unix, but the DOS system shell and Windows itself ignores it completely.

C:\book\tests> python brian
The Bright Side of Life...

In this case, you don't need the special #! comment at the top (although Python just ignores it if it's present), and the file doesn't need to be given executable privileges. In fact, if you want to run files portably between Unix and MS Windows, your life will probably be simpler if you always use the basic command-line approach, not Unix-style scripts, to launch programs.

The Unix env Lookup Trick On some Unix systems, you can avoid hardcoding the path to the Python interpreter by writing the special first-line comment like this: #!/usr/bin/env python ... script goes here ... When coded this way, the env program locates the python interpreter according to your system search-path settings (i.e., in most Unix shells, by looking in all directories listed in the PATH environment variable). This scheme can be more portable, since you don't need to hardcode a Python install path in the first line of all your scripts. Provided you have access to env everywhere, your scripts will run no matter where python lives on your system—you need only change the PATH environment variable settings across platforms, not the first line in all your scripts. Of course, this assumes that env lives in the same place everywhere (on some machines, it may also be in /sbin, /bin, or other); if not, all portability bets are off.