Learning Python

Python Configuration Details

So far, we’ve seen how to make the Python interpreter execute programs we’ve typed. But besides the interpreter, a Python installation also comes with a collection of utility programs, stored in the Python source library. Moreover, the Python interpreter recognizes settings in the system shell’s environment, which let us tailor the interpreter’s behavior (where it finds the source-code files, for example). This section talks about the environment settings commonly used by Python programmers, peeks at Python installation details, and presents an example script that illustrates most of the configuration steps you’ll probably need to know about. If you have access to a ready-to-run Python, you can probably skip much of this section, or postpone it for a later time.

Environment Variables

The Python interpreter recognizes a handful of environment variable settings, but only a few are used often enough to warrant explanation here. Table 1.1 summarizes the main Python variable settings.

Table 1-1. Important Environment Variables

Role	Variable
System shell search path (for finding “python”)	PATH (or path)
Python module search path (for imports)	PYTHONPATH
Path to Python interactive startup file	PYTHONSTARTUP
GUI extension variables (Tkinter)	TCL_LIBRARY, TK_LIBRARY

These variables are straightforward to use, but here are a few pointers:

• The PATH setting lists a set of directories that the operating system searches for executable programs. It should normally include the directory where your Python interpreter lives (the python program on Unix, or the python.exe file on Windows). You don’t need to set this on the Macintosh (the install handles path details).

• The PYTHONPATH setting serves a role similar to PATH: the Python interpreter consults the PYTHONPATH variable to locate module files when you import them in a program. This variable is set to a list of directories that Python searches to find an imported module at runtime. You’ll usually want to include your own source-code directories and the Python source library’s directory (unless it’s been preset in your Python installation).

• If PYTHONSTARTUP is set to the pathname of a file of Python code, Python executes the file’s code automatically whenever you start the interactive interpreter, as though you had typed it at the interactive command line. This is a handy way to make sure you always load utilities whenever you’re working interactively.

• Provided you wish to use the Tkinter GUI extension (see Chapter 10), the two GUI variables in Table 1.1 should be set to the name of the source library directories of the Tcl and Tk systems (much like PYTHONPATH).

Unfortunately, the way to set these variables and what to set them to depends on your system’s configuration. For instance, on Unix systems the way to set variables depends on the shell; under the csh shell, you might set this to the Python module search path:

setenv PYTHONPATH .:/usr/local/lib/python:/usr/local/lib/python/tkinter

which tells Python to look for imported modules in three directories: the current directory (.), the directory where the Python source library is installed on your machine (here, /usr/local/lib/python), and the tkinter source library subdirectory, where the Python GUI extension support code resides. But if you’re using the ksh shell, the setting might instead look like this:

export PYTHONPATH=".:/usr/local/lib/python:/usr/local/lib/python/tkinter"

And if you’re using MS-DOS, an environment configuration could be something very different still:

set PYTHONPATH=.;c:\python\lib;c:\python\lib\tkinter

Since this isn’t a book on operating system shells, we’re going to defer to other sources for more details. Consult your system shell’s manpages or other documentation for details. And if you have trouble figuring out what your settings must be, ask your system administrator (or other local guru) for help.

An Example Startup Script

The code below, call it runpy, pulls some of these details together in a simple Python startup script. It sets the necessary environment variables to reasonable values (on Mark’s machine, at least) and starts the Python interactive interpreter. To use it, type runpy at your system shell’s prompt.

#!/bin/csh
# Give this file executable privileges (chmod +x runpy).
# Put this info in your .cshrc file to make it permanent.

# 1) Add path to command-line interpreter
set path = (/usr/local/bin $path)

# 2) Set python library search paths (unless predefined)
# add your module file directories to the list as desired
setenv PYTHONPATH \
     .:/usr/local/lib/python:/usr/local/lib/python/tkinter

# 3) Set tk library search paths for GUIs (unless predefined)
setenv TCL_LIBRARY /usr/local/lib/tcl8.0
setenv TK_LIBRARY  /usr/local/lib/tk8.0

# 4) Start up the interactive command-line
python

runpy illustrates a typical Python configuration, but it has a few drawbacks:

• It’s written to only work under the csh shell, a command-line processor common on Unix and Linux platforms; you’ll need to interpolate if you’re not a csh user.

• The settings it illustrates are usually made once in your shell’s startup file (~/.cshrc for csh users), instead of each time you run Python.

• Depending on how your Python was built, you may not need to list the paths to standard source libraries, since they might be hardwired into your installation.

A note for MS-Windows users: a similar configuration can be created in a MS-DOS batch file, which might look something like this, depending on which Windows port of Python you’ve installed:

PATH c:\python;%PATH%
set PYTHONPATH=.;c:\python\lib;c:\python\lib\tkinter
set TCL_LIBRARY=c:\Program Files\Tcl\lib\tcl8.0
set TK_LIBRARY=c:\Program Files\Tcl\lib\tk8.0
python

A GUI Test Session

If you or your administrator have installed Python with the Tkinter GUI extension, the following interactive session shows one way to test your Python/GUI configuration. (You can skip this section if you won’t be using Tkinter.)

% runpy
                  Version/copyright information...

>>> from Tkinter import *
>>> w = Button(text="Hello", command='exit')
>>> w.pack()
>>> w.mainloop()

Type runpy at the system shell and then all the Python code shown after the Python >>> prompts. Ignore the details in the example’s code for now; we study Tkinter in Chapter 10. If everything is set up properly, you should get a window on your screen that looks something like Figure 1.1 (shown running on a MS-Windows machine; it looks slightly different on the X Window System or a Macintosh, since Tkinter provides for native look and feel).

Figure 1-1. Tkinter GUI test screen

If this test doesn’t work, start checking your environment variable path settings, and/or the Python install. Tkinter is an optional extension that must be explicitly enabled, so make sure it’s in your version of Python. Also make sure you have access to the Tcl/Tk source libraries; they’re required by the current Python Tkinter implementation. See the README files in the Python source distribution and the Python web site for more details.

Installation Overview

In the interest of completeness, this section provides a few pointers on the Python installation process. When you’re just getting started with Python, you normally shouldn’t need to care about Python installation procedures. Hopefully, someone else—perhaps your system administrator—has already installed Python on your platform, and you can skip most of the information here.

But this isn’t always the case, and even if Python is already installed on your machine, installation details may become more important as your knowledge of Python grows. In some scenarios, it’s important to know how to build Python from its source code, so you can bind in extensions of your own statically. But again, this isn’t a book on Python/C integration, so if Python has already been installed for you, you may want to file this section away for future reference.

Python comes in binary or C source-code forms

You can get Python as either a prebuilt binary executable (which runs “out of the box”) or in its C source-code form (which you must compile on your machine before it can run). Both forms can be found in a variety of media—the Python web/FTP sites (see Appendix A), CDs accompanying Python books, independent CD distributors, Linux distributions, and so on. Naturally, if you go for the binary format, you must get one that’s compatible with your machine; if you use the C source-code distribution, you’ll need a C compiler/build system on your machine. Both forms are usually distributed as compressed archive files, which means you usually need utilities such as gzip and tar to unpack the file on your computer (though some Windows ports install themselves).

C source code configures/builds automatically

Although getting Python in binary form means you don’t need to compile it yourself, it also means you have little control over what extensions are enabled; you’ll get the extensions that the person who built the binary happened to think were important. Moreover, besides the Python binary itself, you need to get and install the Python source library, which may or may not be included in a Python binary package. For more control, fetch the full Python C source-code distribution and compile it on your machine. We won’t list the compile commands here, but the source-code build procedure is largely automatic; Python configures its own makefiles according to your platform, and Python compiles without a glitch on just about any platform you might mention.

Don’t build from source unless you’ve used a C compiler before

Having said that, we should note that even automated C compiles of a large system like Python are not to be taken lightly. If you’ve never used a C compiler before, we suggest you try to obtain a Python binary package for your platform first, before falling back on building Python from its source-code on your machine. And as usual, you can always ask a local C guru for assistance with the build or install.

Prebuilt Python binaries exist for most platforms now, including MS-Windows, the Macintosh, and most flavors of Unix; see Python’s web site for links. We should also note that the full C source-code distribution contains the entire Python system, and is true freeware; there are no copyright constraints preventing you from using it in your products. Although hacking an interpreter’s source code isn’t everybody’s cup of tea, it’s comforting to know that you have control over all the source code in your Python system.

For more details on installing and building Python, see the README files in the C source-code distribution, the Python web site, and other Python texts such as Programming Python. And for pointers to various Python distributions, see the URLs listed in Appendix A.