Because examples are central to the structure of this book, I want to briefly describe how to use them here. In general, though, see the following text files in the examples directory for more details:
- README-root.txt
Package structure notes
- PP3E\README-PP3E.txt
General usage notes
Of these, the README-PP3E.txt file is the most informative. In addition, the PP3E\Config directory contains low-level configuration file examples for Windows and Linux, which may or may not be applicable to your usage. I give an overview of some setup details here, but the preceding files give the complete description.
In a sense, the directory containing the book’s examples is itself a fairly sophisticated Python software system and the examples within it have been upgraded structurally in a number of important ways:
- Examples directory tree: a package
The entire examples distribution has been organized as one Python module package to facilitate cross-directory imports and avoid name clashes with other Python code installed on your computer. All cross-directory imports in book examples are package imports, relative to the examples root directory.
Using directory paths in import statements (instead of a complex
PYTHONPATH) also tends to make it easier to tell where modules come from. Moreover, you now need to add only one directory to yourPYTHONPATHsearch-path setting for the entire book examples tree: the directory containing the PP3E examples root directory. To reuse code in this book within your own applications, simply import through the PP3E package root (e.g.,from PP3E.Launcher import which, orimport PP3E.Gui.Tools.threadtools).- Example filenames
Module names are now descriptive and of arbitrary length (I punted on 8.3 DOS compatibility long ago), and any remaining all-uppercase filenames are long gone.
- Example listing titles
Labels of example listings give the full directory pathname of the example’s source file to help you locate it in the examples distribution. For instance, an example source-code file whose name is given as Example N-M: PP3E\Internet\Ftp\sousa.py refers to the file sousa.py in the PP3E\Internet\Ftp subdirectory of the examples directory. The examples directory is the directory containing the top-level PP3E directory of the book examples tree. The examples tree is simply the Examples directory of the book examples distribution, described further in the next section.
- Example command lines
Similarly, command lines give their directory context. For example, when a command line is shown typed after a system prompt, as in
...\PP3E\System\Streams>, it is really to be typed at a system command-line prompt, while working in the PP3E\System\Streams subdirectory in your examples directory. Unix and Linux users: think / when you see \ in filename paths.- Example launchers
Because it’s just plain fun to click on things right away, there are also self-configuring demo launcher programs (described later), to give you a quick look at Python scripts in action with minimal configuration requirements. You can generally run them straight from the examples package without any configuration.
You can find the book examples distribution package on the book’s web page at O’Reilly’s web site, http://www.oreilly.com/catalog/python3/. The book examples directory is located in the PP3E subdirectory of the topmost Examples directory in the package—that is, Examples\PP3E on Windows and Examples/PP3E on Linux.
If you’ve copied the examples to your machine, the examples directory is wherever you copied the PP3E root directory. Example titles reflect this tree’s structure. For instance, an example title of PP3E\Preview\mod.py refers to the Examples\PP3E\Preview\mod.py file at the top level of the book examples distribution package.
You can run most of the examples from within the package directly, but if you obtained them on a CD, you’ll want to copy them to a writable medium such as your hard drive to make changes, and to allow Python to save .pyc compiled bytecode files for quicker startups. See the example package’s top-level README file for more details, or browse the examples directory in your favorite file explorer for a quick tour.
Depending on how often the book’s distribution package is maintained, it may also contain extra open source packages such as the latest releases of Python, the SWIG code generator, and Windows extensions, but you can always find up-to-date releases of Python and other packages on the Web (see Python’s web site, http://www.python.org, or search the Web). In fact, you should—most likely, the Web will very quickly become more current than any extra software included in the book’s package.
Now the fun stuff—if you want to see some Python examples right away, do this:
Install Python from the book’s distribution package or from Python’s web site (http://www.python.org), unless it is already present on your computer. If you use a Linux or recent Macintosh, Python is probably already installed. On Windows, click on the name of the Python self-installer program and do a default install (click Yes or Next in response to every prompt). On other systems, see the README file.
Start one of the following self-configuring scripts located in the top-level Examples\PP3E directory of the book examples package. Either click on their icons in your file explorer, or run them from your system prompt (e.g., a Windows console box, or Linux xterm) using command lines of the form
pythonscriptname(you may need to use the full path topythonif it’s not implicit on your system):- Launch_PyDemos.pyw
The main Python/Tk demo launcher toolbar
- Launch_PyGadgets_bar.pyw
A Python/Tk utilities launcher bar
- Launch_PyGadgets.py
Starts the standard Python/Tk utilities
- LaunchBrowser.py
Opens the web examples index page in your web browser
The Launch_* scripts start
Python programs portably[*] and require only that Python be installed—you don’t need
to set any environment variables first to run them. LaunchBrowser will work if it can find a web
browser on your machine even if you don’t have an Internet link
(though some Internet examples won’t work completely without a live
link).
The demo launchers also include a number of web-based programs that use a web browser for their interface. When run, these programs launch a locally running web server coded in Python (we’ll meet this server script later in this book). Although these programs can run on a remote server too, they still require a local Python installation to be used with a server running on your machine.
This section goes into a few additional details about running the book’s example programs. If you’re in a hurry, feel free to skip this and run the programs yourself now.
To help organize the book’s examples, I’ve provided a demo launcher program GUI, PyDemos2.pyw, in the top-level PP3E directory of the examples distribution. Figure P-1 shows PyDemos in action on Windows after pressing a few buttons. We’ll meet in this text all the programs shown in the figure. The launcher bar itself appears on the top right of the screen; with it, you can run most of the major graphical examples in the book with a mouse click, and view their source code in pop-up windows. The demo launcher bar can also be used to start major Internet book examples if a browser can be located on your machine and a Python-coded server can be started.
Besides launching demos, the PyDemos source code provides pointers to major examples in the examples tree; see its code for details. You’ll also find automated build scripts for the Python/C integration examples in the Integration examples directory, which serve as indexes to major C examples.
I’ve also included a top-level program called
PyGadgets.py, and its relative,
PyGadgets_bar.pyw, to launch some of the more useful GUI book examples
for real use instead of demonstration (mostly, the programs I use;
configure as desired). Run PyGadgets_bar to see how it looks—it’s a
simple row of buttons that pop up many of the same programs shown in
Figure P-1, but for
everyday use, not for demonstrations. All of its programs are
presented in this book as well and are included in the examples
distribution package. See the end of Chapter 10 for more on PyDemos and
PyGadgets.
Most demos and gadgets require a Python with Tkinter GUI support, but that is the default configuration for Python out-of-the-box on Windows. As a result, most of the demos and gadgets should “just work” on Windows. On some other platforms, you may need to install or enable Tkinter for your Python; try it and see—if you get an error about Tkinter not being found, you’ll need to configure it. If it’s not already present, Tkinter support can be had freely on the Web for all major platforms (more on this in the GUI part of this book, but search the Web with Google for quick pointers).
Two external dependency notes: PyPhoto will not run without PIL, and PyMailCGI runs without PyCrypto but uses it if installed. Both PIL and PyCrypto are open source third-party extension packages, but must be installed in addition to Python. Some book examples use additional third-party tools (for instance, ZODB and MySQL in the database chapter), but these are not launched from the demos and gadgets interfaces.
To run the files listed in the preceding section directly,
you’ll also need to set up your Python module search path, typically
with your PYTHONPATH environment
variable or a .pth file. The book examples tree
ships as a simple directory and does not use Python’s Distutils scripts to install itself in
your Python’s site packages directory (this system works well for
packed software, but can add extra steps for viewing book
examples).
If you want to run a collection of Python demos from the book right away, though, and you don’t want to bother with setting up your environment first, simply run these self-launching utility scripts in the PP3E directory instead:
Launch_PyDemos.pyw
Launch_PyGadgets_bar.pyw
Launch_PyGadgets.py
These Python-coded launcher scripts assume Python has already been installed, but will automatically find your Python executable and the book examples distribution and set up your Python module and system search paths as needed to run their programs. You can probably run these launcher scripts by simply clicking on their names in a file explorer, and you should be able to run them directly from the book’s examples package tree (you can read more about these scripts in Part II of the book).
Beginning with this edition of the book, its browser-based Internet examples are not installed on a remote server. Instead, we’ll be using a Python-coded web server running locally to test these examples. If you launch this server, though, you can also test-drive browser-based examples too. You can find more on this in the Internet section of this book.
For a quick look, though, PyDemos attempts to launch both a web server and a web browser on your machine automatically for the major example web pages. You start the browser by running the LaunchBrowser.py script in the examples root directory. That script tries to find a usable browser on your machine, with generally good results; see the script for more details if it fails. The server is implemented by a Python script, assuming you have permission to run an HTTP server on your machine (you generally do on Windows).
Provided the server starts and LaunchBrowser can find a browser on your
machine, some demo buttons will pop up web pages automatically.
Figure P-2, for
example, shows the web examples index page running under a local
server and the Firefox browser.
Clicking this page’s links runs various server-side Python CGI scripts presented in the book. Of special interest, the getfile.html link on this page allows you to view the source code of any other file in the book’s web server directory—HTML code, Python CGI scripts, and so on; see Chapter 16 for details.
To summarize, here is what you’ll find in the top-level Examples\PP3E directory of the book’s examples package:
- PyDemos.pyw
Button bar for starting major GUI and Internet examples in demo mode
- PyGadgets_bar.pyw
Button bar for starting GUIs in PyGadgets on demand
- PyGadgets.py
Starts programs in nondemo mode for regular use
- Launch_*.py*
Starts the PyDemos and PyGadgets programs using Launcher.py to autoconfigure search paths (run these for a quick look)
- LaunchBrowser.py
Opens example web pages with an automatically located web browser
- Launcher.py
Utility used to start programs without environment settings—finds Python, sets
PYTHONPATH, and spawns Python programs
You’ll also find subdirectories for examples from each major topic area of the book. In addition, the top-level PP3E\PyTools directory contains Python-coded command-line utilities for converting line feeds in all example text files to DOS or Unix format (useful if they look odd in your text editor); making all example files writable (useful if you drag-and-drop off a CD on some platforms); deleting old .pyc bytecode files in the tree; and more. Again, see the example directory’s README-PP3E.txt file for more details on all example issues.
[*] All the demo and launcher scripts are written portably but are known to work only on Windows and Linux at the time of this writing; they may require minor changes on other platforms. Apologies if you’re using a platform that I could not test: Tk runs on Windows, X Windows, and Macs; Python itself runs on everything from PDAs, iPods, and cell phones to real-time systems, mainframes, and supercomputers; and my advance for writing this book wasn’t as big as you may think.
Get Programming Python, 3rd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
