How to Configure Python

Environment variables—known to some as shell variables, or DOS variables—are system-wide settings that live outside Python and thus can be used to customize the interpreter’s behavior each time it is run on a given computer. Python recognizes a handful of environment variable settings, but only a few are used often enough to warrant explanation here. Table A.1 summarizes the main Python-related environment variable settings.

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

Note that because these environment settings are external to Python itself, when you set them is usually irrelevant: this can be done before or after Python is installed, as long as they are set the way you require before Python is actually run.

The way to set Python-related environment variables, and what to set them to, depends on the type of computer you’re working on. And again, remember that you won’t necessarily have to set these at all right away; especially if you’re working in IDLE (described in Chapter 3, How You Run Programs), configuration is not required up front.

But suppose, for illustration, that you have generally useful module files in directories called utilities and package1 somewhere on your machine, and you want to be able to import these modules from files located in other directories. That is, to load a file called spam.py from the utilities directory, you want to be able to say:

import spam

from another file located anywhere on your computer. To make this work, you’ll have to configure your module search path one way or another to include the directory containing spam.py. Here are a few tips on this process.

setenv PYTHONPATH /usr/home/pycode/utilities:/usr/lib/pycode/package1

export PYTHONPATH="/usr/home/pycode/utilities:/usr/lib/pycode/package1"

set PYTHONPATH=c:\pycode\utilities;d:\pycode\package1

c:\pycode\utilities

d:\pycode\package1

When you start Python from a system command line (a.k.a. a shell prompt), you can pass in a variety of option flags to control how Python runs. Unlike system-wide environment variables, command-line options can be different each time you run a script. The complete form of a Python command-line invocation in 3.0 looks like this (2.6 is roughly the same, with a few option differences):

python [-bBdEhiOsSuvVWx?] [-c command | -m module-name | script | - ] [args]

Most command lines only make use of the script and args parts of this format, to run a program’s source file with arguments to be used by the program itself. To illustrate, consider the following script file, main,py, which prints the command-line arguments list made available to the script as sys.argv:

# File main.py

import sys

print(sys.argv)

In the following command line, both python and main.py can also be complete directory paths, and the three arguments (a b –c) meant for the script show up in the sys.argv list. The first item in sys.argv is always the script file’s name, when it is known:

c:\Python30> python main.py a b –c 	# Most common: run a script file

['main.py', 'a', 'b', '-c']

Other code format specification options allow you to specify Python code to be run on the command line itself (-c), to accept code to run from the standard input stream (a – means read from a pipe or redirected input stream file), and so on:

c:\Python30> python -c "print(2 ** 100)" 	# Read code from command argument

1267650600228229401496703205376



c:\Python30> python -c "import main" 	# Import a file to run its code

['-c']



c:\Python30> python - < main.py a b –c 	# Read code from standard input

['-', 'a', 'b', '-c']



c:\Python30> python - a b -c < main.py 	# Same effect as prior line

['-', 'a', 'b', '-c']

The –m code specification locates a module on Python’s module search path (sys.path) and runs it as a top-level script (as module __main__). Leave off the “.py” suffix here, since the filename is a module:

c:\Python30> python -m main a b –c 	# Locate/run module as script

['c:\\Python30\\main.py', 'a', 'b', '-c']

The –m option also supports running modules in packages with relative import syntax, as well as modules located in .zip archives. This switch is commonly used to run the pdb debugger and profile profiler modules from a command line for a script invocation rather than interactively, though this usage mode seems to have changed somewhat in 3.0 (profile appears to have been affected by the removal of execfile in 3.0, and pdb steps into superfluous input/output code in the new 3.0 io module):

c:\Python30> python -m pdb main.py a b -c 	# Debug a script

--Return--

> c:\python30\lib\io.py(762)closed()->False

-> return self.raw.closed

(Pdb) c



c:\Python30> C:\python26\python -m pdb main.py a b -c # Better in 2.6?

> c:\python30\main.py(1)()

-> import sys

(Pdb) c



c:\Python30> python -m profile main.py a b -c 	# Profile a script



c:\Python30> python -m cProfile main.py a b -c 	# Low-overhead profiler

Immediately after the “python” and before the designation of code to be run, Python accepts additional arguments that control its own behavior. These arguments are consumed by Python itself and are not meant for the script being run. For example, -O runs Python in optimized mode, -u forces standard streams to be unbuffered, and –i enters interactive mode after running a script:

c:\Python30> python –u main.py a b -c 	# Unbuffered output streams

Python 2.6 supports additional options that promote 3.0 compatibility (−3, -Q) and detecting inconsistent tab indentation usage, which is always detected and reported in 3.0 (-t; see Chapter 12, if Tests and Syntax Rules). See the Python manuals or reference texts for more details on available command-line options. Or better yet, ask Python itself—run a command-line form like this:

c:\Python30> python -?

to request Python’s help display, which documents available command-line options. If you deal with complex command lines, be sure to also check out the standard library modules getopt and optparse, which support more sophisticated command-line processing.