After you’ve installed Python, you may want to configure some system settings that impact the way Python runs your code. (If you are just getting started with the language, you can probably skip this section completely; there is usually no need to specify any system settings for basic programs.)
Generally speaking, parts of the Python interpreter’s behavior can be configured with environment variable settings and command-line options. In this section, we’ll take a brief look at both, but be sure to see other documentation sources for more details on the topics we introduce here.
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 (you’ll find information on others in Python reference resources).
Table A-1. Important environment variables
|
Variable |
Role |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Windows launcher defaults (see Appendix B) |
These variables are straightforward to use, but here are a few pointers:
PATHThe PATH setting lists a set of directories that the operating system searches for executable programs, when they are invoked without a full directory path. 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 variable at all if you are willing to work in the directory where Python resides, or type the full path to Python in command lines. On Windows, for instance, the PATH is irrelevant if you run a cd C:\Python33 before running any code (to change to the directory where Python lives—though you shouldn’t generally store your own code in this directory per Chapter 3), or always type C:\Python33\python instead of just python (giving a full path).
Also note that PATH settings are mostly for launching programs from command lines; they are usually irrelevant when launching via icon clicks and IDEs—the former uses filename associations, and the latter uses built-in mechanisms, and doesn’t generally require this configuration step. See also Appendix B for details on 3.3’s automatic PATH setting option at install time.
PYTHONPATHThe 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. If used, this variable is set to a platform-dependent list of directory names, separated by colons on Unix and semicolons on Windows. This list normally includes just your own source code directories. Its content is merged into the sys.path module import search path, along with the script’s container directory, any .pth path file settings, and standard library directories.
You don’t need to set this variable unless you will be performing cross-directory imports—because Python always searches the home directory of the program’s top-level file automatically, this setting is required only if a module needs to import another module that lives in a different directory. See also the discussion of .pth path files later in this appendix for an alternative to PYTHONPATH. For more on the module search path, refer to Chapter 22.
PYTHONSTARTUPIf 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 rarely used but handy way to make sure you always load certain utilities when working interactively; it saves an import each time you start a Python session.
tkinter settingsIf you wish to use the tkinter GUI toolkit (named Tkinter in 2.X), you might have to set the two GUI variables in the last line of Table A-1 to the names of the source library directories of the Tcl and Tk systems (much like PYTHONPATH). However, these settings are not required on Windows systems (where tkinter support is installed alongside Python), and are usually not required on Mac OS X and Linux systems, unless the underlying Tcl and Tk libraries are either invalid or reside in nonstandard directories (see python.org’s Download page for more details).
PY_PYTHON, PY_PYTHON3, PY_PYTHON2These settings are used to specify default Pythons when you are using the new (at this writing) Windows launcher that ships with Python 3.3 and is available separately for other versions. Since we’ll be exploring the launcher in Appendix B, I’ll postpone further details here.
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—be sure to restart your Python IDEs and interactive sessions after making such changes if you want them to apply.
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) and save all your files in the same directory, configuration is probably 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 in either the utilities or package1 directories, you want to be able to say this in another file in another directory:
import spam
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 using PYTHONPATH as an example; do the same for other settings like PATH as needed (though 3.3 can set PATH automatically: see Appendix B).
On Unix systems, the way to set environment variables depends on the shell you use. Under the csh shell, you might add a line like the following in your .cshrc or .login file to set the Python module search path:
setenv PYTHONPATH /usr/home/pycode/utilities:/usr/lib/pycode/package1
This tells Python to look for imported modules in two user-defined directories. Alternatively, if you’re using the ksh shell, the setting might instead appear in your .kshrc file and look like this:
export PYTHONPATH="/usr/home/pycode/utilities:/usr/lib/pycode/package1"
Other shells may use different (but analogous) syntax.
If you are using MS-DOS or some now fairly old flavors of Windows, you may need to add an environment variable configuration command to your C:\autoexec.bat file, and reboot your machine for the changes to take effect. The configuration command on such machines has a syntax unique to DOS:
set PYTHONPATH=c:\pycode\utilities;d:\pycode\package1
You can type such a command in a DOS console window, too, but the setting will then be active only for that one console window. Changing your .bat file makes the change permanent and global to all programs, though this technique has been superseded in recent years by that described in the next section.
On all recent versions of Windows (including XP, Vista, 7, and 8), you can instead set PYTHONPATH and other variables via the system environment variable GUI without having to edit files, type command lines, or reboot. Select the Control Panel (in your Start button in Windows 7 and earlier, and in the desktop mode’s Settings “charm” on Windows 8), choose the System icon, pick the Advanced settings tab or link, and click the Environment Variables button at the bottom to edit or add new variables (PYTHONPATH is usually a new user variable). Use the same variable name and values syntax shown in the DOS set command in the preceding section. On Vista you may have to verify operations along the way.
You do not need to reboot your machine after this, but be sure to restart Python if it’s open so that it picks up your changes—it configures its import search path at startup time only. If you’re working in a Windows Command Prompt window, you’ll probably need to restart that to pick up your changes as well.
If you are an experienced Windows user, you may also be able to configure the module search path by using the Windows Registry Editor. To open this tool, type regedit in the Start→Run... interface on some Windows, in the search field at the bottom of the Start button display on Windows 7, and in a Command Prompt window on Windows 8 and others (among other routes). Assuming the typical registry tool is available on your machine, you can then navigate to Python’s entries and make your changes. This is a delicate and error-prone procedure, though, so unless you’re familiar with the registry, I suggest using other options (indeed, this is akin to performing brain surgery on your computer, so be careful!).
Finally, if you choose to extend the module search path with a .pth path file instead of the PYTHONPATH variable, you might instead code a text file that looks like the following on Windows (e.g., file C:\Python33\mypath.pth):
c:\pycode\utilities d:\pycode\package1
Its contents will differ per platform, and its container directory may differ per both platform and Python release. Python locates this file automatically when it starts up.
Directory names in path files may be absolute, or relative to the directory containing the path file; multiple .pth files can be used (all their directories are added), and .pth files may appear in various automatically checked directories that are platform- and version-specific. In general, a Python release numbered Python N.M typically looks for path files in C:\PythonNM and C:\PythonNM\Lib\site-packages on Windows, and in /usr/local/lib/pythonN.M/site-packages and /usr/local/lib/site-python on Unix and Linux. See Chapter 22 for more on using path files to configure the sys.path import search path.
Because environment settings are often optional, and because this isn’t a book on operating system shells, I’ll defer to other sources for further details. Consult your system shell’s manpages or other documentation for more information, and if you have trouble figuring out what your settings should be, ask your system administrator or another local expert for help.
When you start Python from a system command line (a.k.a. a shell prompt, or Command Prompt window), you can pass in a variety of option flags to control how Python runs your code. Unlike the system-wide environment variables of the prior section, command-line arguments can be different each time you run a script. The complete form of a Python command-line invocation in 3.3 looks like this (2.7 is roughly the same, with a few differences described ahead):
python [-bBdEhiOqsSuvVWxX] [-ccommand| -mmodule-name|script| - ] [args]
The rest of this section briefly demonstrates some of Python’s most commonly used arguments. For more details on available command-line options not covered here, see the Python manuals or reference texts. Or better yet, ask Python itself—run a command line form like this:
C:\code> python -h
to request Python’s help display, which documents all available command-line options. If you deal with complex command lines, be sure to also check out the standard library modules in this domain: the original getop, the newer argparse, and the now-deprecated (since 3.2) optparse, which support more sophisticated command-line processing. Also see Python’s library manuals and other references for more on the pdb and profile modules the following tour deploys.
Most command lines make use of only the script and args parts of the last section’s Python command-line format, to run a program’s source file with arguments to be used by the program itself. To illustrate, consider the following script—a text file named showargs.py, created in directory C:\code or another of your choosing—which prints the command-line arguments made available to the script as sys.argv, a Python list of Python strings (if you don’t yet know how to create or run Python script files, see the full coverage in Chapter 2 and Chapter 3; we’re interested only in command-line arguments here):
# File showargs.py
import sys
print(sys.argv)
In the following command line, both python and showargs.py can also be complete directory paths—the former is assumed to be on your PATH here, and the latter is assumed to be in the current directory. The three arguments (a b –c) meant for the script show up in the sys.argv list and can be inspected by your script’s code there; the first item in sys.argv is always the script file’s name, when it is known:
C:\code> python showargs.py a b -c # Most common: run a script file
['showargs.py', 'a', 'b', '-c']
As covered elsewhere in this book, Python lists print in square brackets and strings display in quotes.
Other code format specification options allow you to give Python code to be run on the command line itself (-c), and accept code to run from the standard input stream (a – means read from a pipe or redirected input stream file, terms also defined in full elsewhere in this text):
C:\code>python -c "print(2 ** 100)"# Read code from command argument 1267650600228229401496703205376 C:\code>python -c "import showargs"# Import a file to run its code ['-c'] C:\code>python - < showargs.py a b -c# Read code from standard input ['-', 'a', 'b', '-c'] C:\code>python - a b -c < showargs.py# Same effect as prior line ['-', 'a', 'b', '-c']
The –m code specification locates a module on Python’s module search path and then runs it as a top-level script (as module __main__). That is, it looks up a script the same way import operations do, using the directory list normally known as sys.path, which includes the current directory, PYTHONPATH settings, and standard libraries. Leave off the “.py” suffix here, as the filename is treated as a module.
C:\code> python -m showargs a b -c # Locate/run module as script
['c:\\code\\showargs.py', 'a', 'b', '-c']
The –m option also supports running tools, modules in packages with and without relative import syntax, and modules located in .zip archives. For instance, 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:
C:\code>python# Interactve debugger session >>>import pdb>>>pdb.run('import showargs')...more omitted: see pdb docsC:\code>python -m pdb showargs.py a b -c# Debugging a script (c=continue) > C:\code\showargs.py(2)<module>() -> import sys (Pdb)c['showargs.py', 'a', 'b', '-c'] ...more omitted: q to exit
The profiler runs and times your code; its output can vary per Python, operating system, and computer:
C:\code>python -m profile showargs.py a b -c# Profiling a script ['showargs.py', 'a', 'b', '-c'] 9 function calls in 0.016 seconds Ordered by: standard name ncalls tottime percall cumtime percall filename:lineno(function) 2 0.000 0.000 0.000 0.000 :0(charmap_encode) 1 0.000 0.000 0.000 0.000 :0(exec) ...more omitted: see profile docs
You might also use the -m switch to spawn Chapter 3’s IDLE GUI program located in the standard library from any other directory, and to start the pydoc and timeit tools modules with command lines as we do in this book in Chapter 15 and Chapter 21 (see those chapters for more details on the tools launched here):
c:\code>python -m idlelib.idle -n# Run IDLE in package, no subprocess c:\code>python -m pydoc -b# Run pydoc and timeit tools modules c:\code>python -m timeit -n 1000 -r 3 -s "L = [1,2,3,4,5]" "M = [x + 1 for x in L]"
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 and -u forces standard streams to be unbuffered—with the latter, any printed text will be finalized immediately, and won’t be delayed in a buffer:
C:\code>python -O showargs.py a b -c# Optimized: make/run ".pyo" byte code C:\code>python -u showargs.py a b -c# Unbuffered standard output stream
Finally, the –i flag enters interactive mode after running a script—especially useful as a debugging tool, because you can print variables’ final values after a successful run to get more details:
C:\code>python -i showargs.py a b -c# Go to interactive mode on script exit ['showargs.py', 'a', 'b', '-c'] >>>sys# Final value of sys: imported module <module 'sys' (built-in)> >>>^Z
You can also print variables this way after an exception shuts down your script to see what they looked like when the exception occurred, even if not running in debug mode—though you can start the debugger’s postmortem tool here as well (type is the Windows file display command; try a cat or other elsewhere):
C:\code>type divbad.pyX = 0 print(1 / X) C:\code>python divbad.py# Run the buggy script ...error text omittedZeroDivisionError: division by zero C:\code>python -i divbad.py# Print variable values at error ...error text omittedZeroDivisionError: division by zero >>>X0 >>>import pdb# Start full debugger session now >>>pdb.pm()> C:\code\divbad.py(2)<module>() -> print(1 / X) (Pdb)quit
Besides those just mentioned, Python 2.7 supports additional options that promote 3.X compatibility (−3 to warn about incompatibilities, and –Q to control division operator models) and detecting inconsistent tab indentation usage, which is always detected and reported in 3.X (-t; see Chapter 12). Again, you can always ask Python 2.X itself for more on the subject as needed:
C:\code> c:\python27\python -h
Technically, the preceding section described the arguments you can pass to the Python interpreter itself—the program usually named python.exe on Windows, and python on Linux (the .exe is normally omitted on Windows). As we’ll see in the next appendix, the Windows launcher shipped with Python 3.3 augments this story for users of 3.3 and later or the standalone launcher package. It adds new executables that accept Python version numbers as arguments in command lines used to start Python and your scripts (file what.py is listed and described in the next appendix, and simply prints the Python version number):
C:\code>py what.py# Windows launcher command lines 3.3.0 C:\code>py −2 what.py# Version number switch 2.7.3 C:\code>py −3.3 -i what.py -a -b -c# Arguments for all 3: py, python, script 3.3.0 >>> ^Z
In fact, as the last run of the preceding example shows, command lines using the launcher can give arguments for the launcher itself (−3.3), Python itself (-i), and your script (-a, -b, and -c). The launcher can also parse version numbers out of #! Unix lines at the top of script files instead. Because the next appendix is devoted to this launcher entirely, though, you’ll have to read on for the rest of this story.