Appendix A TOC Appendix C

Appendix B. Pragmatics

This appendix is a very brief introduction to some install-level details of Python use, and contains a list of Python Internet resources. More information on topics not covered fully here can be found at other resources:

· For additional install details, consult the various README text files in the examples distribution on this book's CD (view CD-ROM content online at http://examples.oreilly.com/python2), as well as the README files and other documentation that accompany the Python distributions and other packages on the CD. In particular, the README files in the Examples and Examples\PP2E directories contain book example tree documentation and Python install details not repeated in this appendix.

· For more background information on running Python programs in general, see the Python manuals included on this book's CD, or the introductory-level O'Reilly text Learning Python.

· For more background information on the core Python language itself, refer to the Python standard manuals included on this book's CD, and the O'Reilly texts Learning Python and Python Pocket Reference.

· For more information about all things Python, see http://www.python.org.This site has online Python documentation, interpreter downloads, search engines, and links to just about every other relevant Python site on the Web. For links to information about this book, refer back to the Preface.

B.1 Installing Python

This section gives an overview of install-related details -- instructions for putting the Python interpreter on your computer.

B.1.1 Windows

Python install details vary per platform and are described in the resources just listed. But as an overview, Windows users will find a Python self-installer executable at http://examples.oreilly.com/python2 (see the top-level Python 1.5.2 and 2.0 directories). Simply double-click the installer program and answer "yes," "next," or "default" to step through a default Windows install. Be sure to install Tcl/Tk too, if you are asked about it along the way.

After the install, you will find an entry for Python in your Start button's Programs menu; it includes options for running both the IDLE integrated GUI development interface and the command-line console session, viewing Python's standard manuals, and more. Python's manuals are installed with the interpreter in HTML form, and open locally in a web browser when selected.

Python also registers itself to open Python files on Windows, so you can simply click on Python scripts in a Windows file explorer window to launch them. You can also run Python scripts by typing python file.py command lines at any DOS command-line prompt, provided that the directory containing the python.exe Python interpreter program is added to your PATH DOS shell variable (see the configuration and running sections later).

Note that the standard Python package for Windows includes full Tkinter support. You do not need to install other packages or perform any extra install steps to run Tkinter GUIs on Windows; simply install Python. All necessary Tkinter components are installed by the Python self-installer, and Python automatically finds the necessary components without extra environment settings. The Windows install also includes the bsddb extension to support DBM-style files.

If you plan on doing any Windows-specific work such as COM development, you will probably want to install the extra win32all extensions package (available at http://examples.oreilly.com/python2 as well as at http://www.python.org). This package registers Python for Active Scripting, provides MFC wrappers and COM integration, and more (see Chapter 15). Also note that Python distributions available from other sources (e.g., the ActivePython distribution from ActiveState, http://www.activestate.com) may include both Python and the Windows extensions package.

B.1.2 Unix and Linux

Python may already be available on these platforms (it's often installed as a standard part of Linux these days); check your /usr/bin and /usr/local/bin directories to see if a Python interpreter is lurking there. If not, Python is generally installed on these platforms from either an rpm package (which installs Python executables and libraries automatically) or the source code distribution package (which you unpack and compile locally on your computer). Compiling Python from its source on Linux is a trivial task -- usually just a matter of typing two or three simple command lines. See the Python source distribution's top-level README files and Linux rpm documentation for more details.

B.1.3 Macintosh and Others

Please see the documentation associated with the Macintosh ports for install and usage details. For other platforms, you will likely need to find ports at http://www.python.org and consult the port's install notes or documentation.

B.2 Book Examples Distribution

This section briefly discusses the book's example source code distribution, and covers example usage details.

B.2.1 The Book Examples Package

The Examples\PP2E CD directory is a Python module package that contains source code files for all examples presented in this book (and more). The PP2E package in turn contains nested module packages that partition the example files into subdirectories by topic. You can either run files straight off the CD, or copy the PP2E directory onto your machine's hard drive (copying over allows you to change the files, and lets Python store their compiled bytecode for faster startups).

Either way, the directory that contains the PP2E root must generally be listed on the Python module search path (normally, the PYTHONPATH environment variable). This is the only entry that you must add to the Python path, though; import statements in book examples are always package import paths relative to the PP2E root directory unless the imported module lives in the same directory as the importer.

Also in the examples package, you'll find scripts for converting example files' line-feeds to and from Unix format (they are in DOS format on the CD--see http://examples.oreilly.com/python2), making files writable (useful after a drag-and-drop on Windows), and more. See the README files at the top of the Examples and PP2E directory trees for more details on package tree usage and utilities.

B.2.2 Running the Demo Launcher Scripts

The top level of the CD's Examples\PP2E package (see http://examples.oreilly.com/python2) includes Python self-configuring scripts that can be run to launch major book examples, even if you do not configure your environment. That is, they should work even of you don't set your PATH or PYTHONPATH shell variables. These two scripts, PyDemos and PyGadgets, are presented in Chapter 8, and described more fully in both this book's Preface and the CD's README files (see http://examples.oreilly.com/python2). In most cases, you should be able to run these scripts right off the book's CD by double-clicking on them in a file explorer GUI (assuming Python has been installed, of course).

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.

B.4 Running Python Programs

Python code can be typed at a >>> interactive prompt, run from a C program, or placed in text files and run. There is a variety of ways to run code in files:

Running from a command line

Python files can always be run by typing a command of the form python file.py in your system shell or console box, as long as the Python interpreter program is on your system's search path. On Windows, you can type this command in an MS-DOS console box; on Linux, use an xterm.

Running by clicking

Depending on your platform, you can usually start Python program files by double-clicking on their icons in a file explorer user interface. On Windows, for instance, .py Python files are automatically registered such that they can be run by being clicked (as are .pyc and .pyw files).

Running by importing and reloading

Files can also be run by importing them, either interactively or from within another module file. To rerun a module file's code again without exiting Python, be sure to run a call like reload(module).

Running files in IDLE

For many, running a console window and one or more separate text editor windows constitutes an adequate Python development environment. For others, IDLE -- the Python Integrated Development Environment (but really named for Monty Python's Eric Idle) -- is a development environment GUI for Python. It can also be used to run existing program files or develop new systems from scratch. IDLE is written in Python/Tkinter, and thus is portable across Windows, X Windows (Unix), and Macintosh. It ships (for free) as a standard tool with the Python interpreter. On Windows, IDLE is installed automatically with Python; see Section B.1.1 under Section B.1 earlier in this appendix.

IDLE lets you edit, debug, and run Python programs. It does syntax coloring for edited Python code, sports an object browser the lets you step through your system's objects in parallel with its source code, and offers a point-and-click debugger interface for Python. See IDLE's help text and page at http://www.python.org for more details. Or simply play with it on your machine; most of its interfaces are intuitive and easy to learn. The only thing IDLE seems to lack today is a point-and-click GUI builder (but Tkinter's simplicity tends to make such builders less important in Python work).

Running files in Pythonwin

Pythonwin is another freely available, open source IDE for Python, but is targeted at Windows platforms only. It makes use of the MFC integration made available to Python programmers in the win32all Windows-specific Python extensions package described in Chapter 15. In fact, Pythonwin is something of an example application of these Windows tools. Pythonwin supports source code editing and launching much like IDLE does (and there has been some cross-pollination between these systems). It doesn't sport all the features or portability of IDLE, but offers tools all its own for Windows developers. Fetch and install the win32all Windows extensions package to experiment with Pythonwin. You can also find this package on this book's CD (see http://examples.oreilly.com/python2).

Running Python from other IDEs

If you are accustomed to more sophisticated development environments, see the Visual Python products from Active State (http://www.activestate.com), and the PythonWorks products from PythonWare (http://www.pythonware.com). Both are emerging as I write this, and promise to provide advanced integrated development tool suites for Python programmers. For instance, ActiveState's plans include support for developing Python programs under both Microsoft's Visual Studio and the Mozilla application environment, as well as a Python port to the C#/.NET environment. PythonWare's products support visual interface development and a suite of development tools.

Other platforms have additional ways to launch Python programs (e.g., dropping files on Mac icons). Here are a few more hints for Unix and Windows users:

Unix and Linux users

You can also make Python module files directly executable by adding the special #!/usr/bin/python type line at the top of the file and giving the file executable permissions with a chmod command. If you do, you can run Python files simply by typing their names (e.g., file.py ), as though they were compiled executables. See Chapter 2, for more details.

Windows users

If you see a flash when you click on a Python program in the file explorer, it's probably the console box that Python pops up to represent the program's standard input/output streams. If you want to keep the program's output up so that you can see it, add a call raw_input( ) to the bottom of your program; this call pauses until you press the Enter key. If you write your own GUI and don't want to see the console pop-up at all, name your source files with a .pyw extension instead of .py.

Windows NT and 2000

You can also launch a Python script file from a command-line prompt simply by typing the name of the script's file (e.g., file.py ). These platforms correctly run the script with the Python interpreter without requiring the special #! first line needed to run files directly in Unix. To run Python command lines on Windows 9x platforms, you'll need to add the word "python" before the filename and make sure the python.exe executable is on your PATH setting (as described earlier). On all Windows platforms, you may also click on Python filenames in a Windows explorer to start them.

B.5 Python Internet Resources

Finally, Table B-1 lists some of the most useful Internet sites for Python information and resources. Nearly all of these are accessible from Python's home page (http://www.python.org) and most are prone to change over time, so be sure to consult Python's home page for up-to-date details.

Appendix A TOC Appendix C