B.3 Environment Configuration

This section introduces Python environment setup details and describes settings that impact Python programs.

B.3.1 Shell Variables

The following shell environment variables (among others) are usually important when using Python:

PYTHONPATH

Python's module file search path. If set, it is used to locate modules at run- time when they're imported by a Python program -- Python looks for an imported module file or package directory in each directory listed on PYTHONPATH, from left to right. Python generally searches the home directory of a script as well as the Python standard source code library directory automatically, so you don't need to add these. Hint: check sys.path interactively to see how the path is truly set up.

PYTHONSTARTUP

An optional Python initialization file. If used, set this variable to the full path-name of a file of Python code (a module) that you want to be run each time the Python interactive command-line interpreter starts up. This is a convenient way to import modules you use frequently when working interactively.

PATH

The operating system's executable search path variable. It is used to locate program files when you type their names at a command line without their full directory paths. Add the directory containing the python interpreter executable file (or else you must retype its directory path each time).

In addition, users on platforms other than Windows may need to set variables to use Tkinter if Tcl/Tk installations cannot be found normally. Set TK_LIBRARY and TCL_LIBRARY variables to point to the local Tk and Tcl library file directories.

B.3.2 Configuration Settings

The Examples\PP2E\Config directory on the CD (see http://examples.oreilly.com/python2) contains example configuration files with comments for Python variable settings. On Windows NT, you can set these variables in the system settings GUI (more on this in a minute); on Windows 98, you can set them from DOS batch files, which can be run from your C:\autoexec.bat file to make sure they are set every time you start your compute. For example, my autoexec file includes this line:

C:\PP2ndEd\examples\PP2E\Config\setup-pp.bat

which in turn invokes a file that contains these lines to add Python to the system PATH, and the book examples package root to PYTHONPATH:

REM PATH %PATH%;c:\Python20
PATH %PATH%;c:\"program files"\python

set PP2EHOME=C:\PP2ndEd\examples
set PYTHONPATH=%PP2EHOME%;%PYTHONPATH%

Pick (i.e., remove the REM from) one of the first two lines, depending upon your Python install -- the first line assumes a Python 2.0 default install, and the second assumes Python 1.5.2. Also change the PP2EHOME setting here to the directory that contains the PP2E examples root on your machine (the one shown works on my computer). On Linux, my ~/.cshrc startup file sources a setup-pp.csh file that looks similar:

setenv PATH $PATH:/usr/bin
setenv PP2EHOME /home/mark/PP2ndEd/examples
setenv PYTHONPATH $PP2EHOME:$PYTHONPATH

But the syntax used to set variables varies per shell (see the PP2E\Config CD directory for more details). Setting the PYTHONPATH shell variable to a list of directories like this works on most platforms, and is the typical way to configure your module search path. On some platforms, there are other ways to set the search path. Here are a few platform-specific hints:

Windows port

The Windows port allows the Windows registry to be used in addition to setting PYTHONPATH in DOS. On some versions of Windows, rather than changing C:\autoexec.bat and rebooting, you can also set your path by selecting the Control Panel, picking the System icon, clicking in the Environment Settings tab, and typing PYTHONPATH and the path you want (e.g., C:\mydir ) in the resulting dialog box. Such settings are permanent, just like adding them to autoexec.bat.

JPython

Under JPython, the Java implementation of Python, the path may take the form of -Dpath command-line arguments on the Java command used to launch a program, or python.path assignments in Java registry files.

B.3.3 Configuring from a Program

In all cases, sys.path represents the search path to Python scripts and is initialized from path settings in your environment plus standard defaults. This is a normal Python list of strings that may be changed by Python programs to configure the search path dynamically. To extend your search path within Python, do this:

import sys
sys.path.append('mydirpath')

Because shell variable settings are available to Python programs in the built-in os.environ dictionary, a Python script may also say something like sys.path.append(os.environ['MYDIR'])) to add the directory named by the MYDIR shell variable to the Python module search path at runtime. Because os.pathsep gives the character used to separate directory paths on your platform, and string.split knows how to split up strings around delimiters, this sequence:

import sys, os, string
path = os.environ['MYPYTHONPATH']
dirs = string.split(path, os.pathsep)
sys.path = sys.path + dirs

adds all names in the MYPYTHONPATH list setting to the module search path in the same way that Python usually does for PYTHONPATH. Such sys.path changes can be used to dynamically configure the module search path from within a script. They last only as long as the Python program or session that made them, though, so you are usually better off setting PYTHONPATH in most cases.