----------------------------------------------------------------------------- README (top-level) ----------------------------------------------------------------------------- Congratulations! - you are now the proud owner of most of the free stuff in the Python world :-). The items you'll find on this CD represent an incredible amount of work, by an incredible group of people. This file briefly describes what's on this disk. It documents the top-level directory structure, provides some usage tips, and gives a few pointers to important packages. The contents of this document: - MAJOR COMPONENTS - DIRECTORY STRUCTURE - WHERE TO FIND PACKAGES - WHERE TO FIND EXECUTABLES - HOW TO USE PACKAGES - COMMON FILE TYPES - HOW TO UNPACK FILES - HOW TO USE SOURCE-CODE - HOW TO USE EXECUTABLES - HOW TO USE DOCUMENTS - HOW TO ADD EXTENSIONS - WHERE THIS STUFF CAME FROM - CREDITS ----------------------------------------------------------------------------- 1) MAJOR COMPONENTS ----------------------------------------------------------------------------- First, here's a high-level look at some of what is available on this CD. You'll find Python itself, the book's examples, a world-wide-web browser, some 50 Python executables, a collection of popular extensions, and much more. Some of the major packages on this disk include: The Basics ---------- - The book's examples - Python 1.3 source-code - Python 1.4 beta source-code - Tcl7.4 and Tk4.0 source-code (for the GUI examples) - Tcl7.5 and Tk4.1 source-code (for future expansion) - Gdbm source-code (for the persistence examples) Documentation ------------- - Python's standard reference manuals (postscript and hypertext) - Quick-reference documents - Most of the Python web-site HTML - The Tkinter 'life-preserver' reference manual Extra Packages -------------- - Grail: Python/Tk-based world-wide-web browser - WPY: MFC-based GUI system that runs on MS-Windows and X - ILU: CORBA-based distributed object system - SWIG: C extension glue-code generator - PIL: Python imaging library - Two Netscape plug-ins for Python (1 in WPY, and 1 in PythonWin) - A Netscape remote-control interface - A wealth of contributed extensions and tools Executables/Ports ----------------- - PythonWin: Microsoft Windows ports for PCs (with binaries) - Apple Macintosh ports (with binaries for 68K and PPC) - Python 1.3 UNIX platform binaries: Linux, Sun, HP, etc. - Special Python 1.3 binaries with Tk and Dbm pre-installed (UNIX, NT) - A special uncompressed build of PythonWin for PCs - Other PC binaries - DOS, QuickWin, etc. Notes: - Many of the packages on this CD are discussed briefly in appendix-A of the book ("And Other Cool Stuff"). - Although this is an extensive list, it doesn't represent everything available to Python users. Browse "http://www.python.org" for pointers to other Python-related software on the net. - Most of the files on this CD are snapshots of evolving systems. We'll try to keep the disk up-to-date, but most of the systems on it are likely to change over time, and new tools are bound to appear. Check any of the information sources listed in chapter 3 for current status and URLs. ----------------------------------------------------------------------------- 2) DIRECTORY STRUCTURE ----------------------------------------------------------------------------- Among other things, this CD contains mirror images of Python's FTP and WWW Internet sites (*). A few items have been deleted due to copyright restrictions, but you'll find almost everything from Python's on-line archives on this disk. The FTP and WWW site images reside in distinct top-level directories; their structure follows that at the Internet sites. Items not from Python's archives have their own top-level directories too. Here's a quick overview: Top-level directory ------------------- README You are here :-). examples/ Source code for all the examples in the book. Files are organized into subdirectories, by chapter or topic. The filenames of examples on the CD match those in the book. See the README in this directory for more details. ftp.python.org/ A snapshot of Python's FTP site on the Internet, with: - The Python source distribution - Some Python executables - The PythonWin and WPY systems - Other contributed software and more. See the subdirectory list below. gdbm/ The GNU Dbm-file distribution. For object persistence. grail/ The "Grail" world-wide-web browser. Written in Python, using its Tk interface (Tkinter) for the GUI. gzip/ The GNU "gzip" distribution. Includes a gzip binary for DOS, and a tar file (how do you gzip gzip without gzip? :-). ilu/ A language-independent, CORBA-based, distributed object programming system for Python. mac/ The latest Python Macintosh ports - includes 68000 and PowerPC binaries. pc/ A special uncompressed version of the PythonWin MS-Windows port of Python 1.3. pil/ The Python Imaging Library. A variety of graphics tools. special.bin/ Special Python 1.3 executables, with the Tk and Dbm extensions used in the book pre-installed. Binaries for most major UNIX platforms and MS-Windows/NT. See the README in this directory for more details too. swig/ The SWIG C extension code-generator system. tcltk/ Tcl and Tk distributions. For Python's "Tkinter" interface to Tk, used by the GUI examples in the text. www.python.org/ All the HTML from Python's web-site that's fit to print. Point your favorite web-browser at these files to view. Includes Python's reference manuals in hypertext form. ftp.python.org -------------- INDEX A simple-text description of this directory's contents. Most subdirectories of ftp.python.org have one of these. index.html An HTML-based description of this directory's contents. Most subdirectories of ftp.python.org have one of these too. binaries-1.3/ A variety of Python binary executable files for UNIX machines. Unpack and run, if your platform is listed. contrib/ A wide variety of contributed modules, extensions, and tools. See the contrib subdirectory list below. doc/ Python's standard documentation. - Reference manuals (tutorial, language, library, extending) - Tkinter reference manual - the Python FAQ, quick-reference documents, etc. Also see the www.python.org HTML versions of some of these. guido/ Guido's latest updates. Includes an updated version of Tkinter that supports Tk4.1, and runs on MS-Windows and the Macintosh (in addition to UNIX/X11). mac/ Older Macintosh ports. Also see the top-level "mac/" directory for more recent ports and binaries. mail/ Archived messages from the Python mail-list and newsgroup. misc/ Get the official Python anthem here :-). pc/ Old but useful ports and information for PC users. DOS, Windows 3.1, and OS/2 support. pythonwin/ The release directory for PythonWin - a Python port for MS-Windows which supports DLL's, MFC, sockets, and more. src/ The official Python source-code distribution directory. Contains the Python-1.3 source-code file. Also includes a file with just the Python source-library contents (you may need to install this if you're using a raw executable; see usage details below). Python-1.4 beta lives here too. wpy/ The release directory for WPY - a portable, MFC-based GUI API for Python that runs on both MS-Windows and UNIX/X11. ftp.python.org/contrib ---------------------- DataStructures/ Advanced data structure implementations Database/ Database interfaces and mechanisms Encoding/ Tools for encryption, compression, and other secrets Graphics/ Graphics: includes Tkinter and Rivet tools/extensions Misc/ Miscellaneous - things that don't fit elsewhere Network/ Network and WWW-related files Porting/ Hardware and operating-system port facilities System/ System tools and Python internals old/ Oldies-but-goodies - slightly dated contributions www.python.org -------------- Some highlights: doc/ Hypertext documentation. locator/ The PSA's software and services locator psa/ Information on the Python Software Activity python/ General Python information rpython/ Restricted execution mode information sigs/ Python special interest groups Note: Python's WWW information changes often. For more up-to-date reading, browse URL "http://www.python.org/". Other ----- For other subdirectories, it's probably easier to browse on your own, than to read about their contents here. One hint - where more than one version of a system is present, some packages have multiple subdirectories (ilu) and some have more than one tar file (tcltk). (*) For those new to the Internet: the acronyms FTP and WWW stand for file-transfer-protocol, and the world-wide-web. A URL is an Internet address ("http://www.python.org"). ----------------------------------------------------------------------------- 3) WHERE TO FIND PACKAGES ----------------------------------------------------------------------------- Some of the major packages on the CD are nested in the FTP or other directories. Here's a cross-reference from packages to CD locations: The Basics ---------- - The book's examples /examples - Python 1.3 source-code /ftp.python.org/src/python1.3.tar.gz (full source-code) /ftp.python.org/src/lib1.3.tar.gz (source-library only) - Python 1.4 beta source-code /ftp.python.org/src/beta - Tcl7.4 and Tk4.0 source-code /tcltk/tcl7.4.tar.gz (for Python-1.3) /tcltk/tk4.0.tar.gz - Tcl7.5 and Tk4.1 source-code /tcltk/tcl7.5.tar.gz (for Python-1.4 - future) /tcltk/tk4.1.tar.gz - Gdbm source-code /gdbm/gdbm-1.7.3.tar.gz Documentation ------------- - Python's standard reference manuals (postscript and hypertext) /ftp.python.org/doc/postscript-1.3.tar.gz /ftp.python.org/doc/html-1.3.tar.gz /ftp.python.org/doc/lib-info-1.3.tar.gz /www.python.org/doc/{lib, tut, ref, ext} - Quick-reference documents /ftp.python.org/doc/quick-ref.1.3.html /ftp.python.org/doc/QuickRef.ps.gz /ftp.python.org/doc/FAQ - Most of the Python web-site HTML /www.python.org (all) /ftp.python.org/doc/html-1.3.tar.gz (manuals) - The Tkinter 'life-preserver' reference manual /ftp.python.org/doc/tkinter-doc.tar.gz (postscript) /www.python.org/doc/life-preserver (html) Extra Packages -------------- - Grail: Python/Tk-based world-wide-web browser /grail - WPY: MFC-based GUI system that runs on MS-Windows and X /ftp.python.org/wpy - ILU: CORBA-based distributed object system /ilu - SWIG: C extension glue-code generator /swig - PIL: Python imaging library /pil - Two Netscape plug-ins for Python (1 in WPY, and 1 in PythonWin) /ftp.python.org/pythonwin /ftp.python.org/wpy - A Netscape remote-control interface /ftp.python.org/mac/beta/nsremote (older) /mac/nsremote - A wealth of contributed extensions and tools /ftp.python.org/contrib /ilu, /swig, /pil, /grail,... Executables/Ports ----------------- - PythonWin: Microsoft Windows ports for PCs (with binaries) /ftp.python.org/pythonwin (full release) /pc/pywcd3.zip (special uncompressed version) - Apple Macintosh ports (with binaries for 68K and PPC) /ftp.python.org/mac (older version) /mac/Python-133-68K.hqx (68000-based macs) /mac/Python-133-PPC.hqx (PowerPC-based macs) /mac/Python-133-SRC.hqx (full source release) - Python 1.3 UNIX platform binaries: Linux, Sun, HP, etc. /ftp.python.org/binaries-1.3 (see list below) - Special Python 1.3 binaries with Tk and Dbm pre-installed (UNIX, NT) /special.bin (see list below) - A special uncompressed build of PythonWin for PCs /pc/pywcd3.zip - Other PC binaries - DOS, QuickWin, etc. /ftp.python.org/pythonwin /ftp.python.org/wpy /ftp.python.org/pc The next section goes into more detail on executable file locations. And of course, there's more on the CD than listed here. For instance, a quick browse through the FTP "contrib" directory can show you many other packages which might be useful (see "/ftp.python.org/contrib"). ----------------------------------------------------------------------------- 4) WHERE TO FIND EXECUTABLES ----------------------------------------------------------------------------- All told, there are roughly 50 Python executables on this CD. You'll find ready-to-run binaries for a wide variety of UNIX, Microsoft, and Macintosh platforms. Since the executables are distributed among a number of directories, here is a guide to some of the CD directories that contain executables. If you find a file for your platform in one of these directories, you should be able to run Python immediately, after copying and unpacking (see section "How to Use Packages" below for usage tips). /special.bin/ ------------- Special Python-1.3 executables for UNIX and MS-Windows/NT, with the Tkinter and Dbm extensions used in the book pre-installed. These binaries can run all of the example programs from the text, which you'll find in the top-level "/examples" directory. - python-HP-UX-A.09.05-full.tar.gz - python-IRIX-5.3-full.tar.gz - python-Irix-4.0.5C - python-OSF1-V3.2-full.tar.gz - python-SunOS-4.1.4-full.tar.gz - python-ULTRIX-4.5-full.tar.gz - python-dgux-5.4R3.10.tar.gz - python-hppa1.1-hp-hpux10.10.tar.gz - python-linux-i486-1.2.13-elf.tar.gz - python-linux.tar.gz (Linux 2.0) - python-nt-3.51.zip (Windows/NT) - python-sun-sparc-solaris2.4.tar.gz - python-sun-sparc-solaris2.5.tar.gz - python-solaris-x86.tar.gz - python-bsdi-2.0.gz /ftp.python.org/binaries-1.3/ ----------------------------- A collection of 'vanilla' Python-1.3 executables for UNIX platforms. Some may have Tkinter and other extensions installed (it varies per contributor). Most support dynamic loading of C extensions. Note that some of the platforms supported here may overlap with those in the "/special.bin" list above - this is an earlier collection. - HPUX-PA-9000-700-905.tar.gz - aix-3.2.5.tar.gz - bsdi-1.1.tar.gz - hpux-9.04.tar.gz - i86-solaris-2.4.tar.gz - ilupython.aix.3.2.5.tar.gz - ilupython.osf3.0.tar.gz - linux-1.1.59-small.tar.gz - linux-1.1.59.tar.gz - linux-aout.tar.gz - linux-elf-libs.tar.gz - linux-elf-min.tar.gz - linux-elf.tar.gz - osf-3.0.tar.gz - osf-3.2C.tar.gz - sco-3.2.4.tar.Z - sgi-irix-5.2.tar.gz - sgi-irix-5.3.tar.gz - sparc-solaris-2.4.tar.gz - sparc-sunos-4.1.3.tar.gz - sunos-4.1.3.tar.gz - sunos-5.4.tar.gz - ultrix-4.4.tar.gz /pc/ ---- A special, uncompressed build of PythonWin for MS-Windows. This version runs more or less out-of-the-box: just unzip. Supports MFC, dynamic loading of DLL extensions, and more. See the NT executable in "/special.bin" for Tkinter support. - pywcd3.zip /mac/ ----- The latest Macintosh ports. The first two provide support for the Tkinter GUI extension; all include Apple-specific interfaces. - Python-133-68K.hqx (68000-based macs) - Python-133-PPC.hqx (PowerPC-based macs) - Python-133-68K-small.hqx (68K, without Tcl/Tk support) /ftp.python.org/pc/ ------------------- A variety of PC packages and support files. Some are somewhat dated, but still usable. - 16python.exe.gz - 32python.zip - dosbuild.1.2.zip - dosbuild.tar.gz - pyth_os2.zip - python1.2.dos.zip - qwpython.exe.gz /ftp.python.org/wpy/ -------------------- A variety of PC ports, plus a Linux build. WPY is actually a portable GUI tool (MFC-like, for UNIX and Windows), but it includes some Python binaries. /ftp.python.org/pythonwin/ -------------------------- A variety of PC ports. Also see "/pc" above. This is the official PythonWin release directory, with documentation, etc. /ftp.python.org/mac/ -------------------- Older (but usable) Macintosh ports. See "/mac" for more recent Macintosh executables. Notes: - If you don't find an executable for your platform in the binary directories, you can still build Python from the source-code distribution on this CD. See "How to Use Packages" below for source-code details. Python's C source-code is very portable; it compiles unchanged on most UNIX and UNIX-like platforms. Also: check the "ftp.python.org/contrib/Porting" directory for tips on building for other platforms. - A note for PC users - the PC binaries on this CD support: - DOS - Windows-3.1(1) (16-bit mode) - Windows-3.1(1) (32-bit mode) - OS/2 - Windows/NT - Windows-95 Some packages also use a 32-bit extender (win32s) for the older 16-bit MS-Windows platforms. Browse through the directories listed above to find the package you need; most have names that identify their platform/system. ----------------------------------------------------------------------------- 5) HOW TO USE PACKAGES ----------------------------------------------------------------------------- Items are stored in a variety of formats on this CD. Most use standard packaging techniques, but here are a few usage tips. Note: most of the directories in the ftp.python.org top-level directory contain "INDEX" and "index.html" files. Be sure to check these files for additional contents and usage information we won't repeat here. 5.1 COMMON FILE TYPES ---------------------- In general, a file's extension (filename suffix) identifies its type. Some of the file extensions you may find on this CD: .gz compressed with "gzip" (use gzip -d) .tar UNIX tar file archive .exe DOS or Windows executable .shar self-unpacking UNIX shell archive .hqx Mac BinHex 4.0 .sit StuffIt Light(TM) Mac archive .sea StuffIt Light(TM) self-extracting Mac archive .bin MacBinary format .html HyperText Mark-up Language (WWW) .el Emacs Lisp .ps PostScript .tex LaTeX documents .txt Text files .Z compressed with "compress" (use uncompress) .zip DOS zip archive .taz == .tar.Z .tgz == .tar.gz These suffixes may be combined. For example, a filename like "file.tar.gz" means that the file is a compressed tar file. It was first put in a tar archive, and then compressed with gzip. 5.2 HOW TO UNPACK FILES ------------------------ The most common file-type on the CD is a gzipped tar-file (suffix ".tar.gz"). To unpack a "file.tar.gz", follow these steps: 1) Copy the file from the CD to a working directory on your computer 2) Do: "gzip -d file.tar.gz" (this decompresses the file) 3) Do: "tar -xvf file.tar" (this pulls individual items out) The "gzip" program is available on the CD, if you can't find it on your machine. The top-level "gzip" directory contains a gzip executable for PCs, and a tar'd (but not gzipped! :-) source-code version which you can build locally. Especially for the non-UNIX packages, you might need to unpack with other tools ("zip", etc.). Unpacking tools are available for free from most major PC and Macintosh-related Internet sites. 5.3 HOW TO USE SOURCE-CODE --------------------------- Many of the packages are shipped in source-code form, which you need to compile and link with your C (or C++) compiler locally, to create an executable program or library. For instance, Python can be built on UNIX platforms by following these steps: 1) Copy and unpack the package as described above 2) Do: "cd Python-1.3" (go to the build-tree root) 3) Do: "./configure" (run auto-configuration script) 4) Do: "make" (build python libraries and executable) 5) Do: "make install" (put python in standard directories) Other source-code packages usually have similar build procedures. See chapter 3 of the book for more details on this process. Notes: - Python's full source-code distribution package can be found on this CD, in file: "/ftp.python.org/src/python1.3.tar.gz" - After building Python, you can also type "make test" to run its self-test diagnostics. - Most source-code distributions also come with their own specific installation instructions. Look for top-level "README" files for more details. - If you're trying to build source-code packages for PC or Macintosh systems, be sure to check the associated documentation. Build details will vary widely. 5.4 HOW TO USE EXECUTABLES --------------------------- Some of the packages on this CD contain executable binary files, which you can run immediately (without compiling source-code first). For the most part, they are located in the directories listed in section 4 above. Most executables come with their own "README" files or other documentation, describing any special configuration requirements - environment variables, etc. You should also consult the configuration section in chapter 3 of the book, for common Python environment details. But as a guideline, you usually follow these steps on a typical UNIX machine, before running a raw executable file: 1) Copy and unpack the executable's package as described above 2) Install Python's library directory (usually in /usr/local/lib/python) 3) Set Python environment variables (PYTHONPATH - the module search-path) 4) Add the Python executable's directory to your shell's search-path variable 5) For extensions: set environment variables, install libraries, as needed Once you've installed Python with these steps, simply type "python" to start-up the interactive command-line. Executables for other platforms (MS-Windows, Macintosh) may have very different configuration requirements, if any. In all cases, be sure to read the documentation associated with the executable's package first. Notes: - Naturally, you can only run a binary executable file on the machine it was built for. The executables' names and/or directories usually identify the hardware/operating-system for which they're intended. - In general, Python packages use standard configuration techniques on UNIX. But here are a few more tips on the installation steps above. [Note: if you're using MS-Windows or Macintosh executables, you can probably skip much of this material; see your package for details.] MORE ON STEP 2: PYTHON LIBRARY ------------------------------ Most Python programs rely on standard Python modules; these modules are shipped in a directory referred to as Python's 'source-library'. There are two ways to set-up Python's source-library on your machine: 2) File "/ftp.python.org/src/lib1.3.tar.gz" on the CD contains just the source-library. 2a) Copy and unpack this package as described above 2b) Add the "Lib" directory created by the unpacking step to the PYTHONPATH environment variable list. 2) Alternatively, you can get the source-library from Python's full source-distribution file - it's embedded in this package too. 2a) Copy and unpack package "/ftp.python.org/src/python1.3.tar.gz" 2b) Type "make libinstall" to install just the source-library in directory "/usr/local/lib/python". Note: If you don't have write-access to "/usr/local/lib", or you can't find the "make" program on your machine, just set PYTHONPATH to the "Lib" subdirectory in the unpacked Python source-distribution. MORE ON STEP 3: "PYTHONPATH" ---------------------------- This environment variable is used to find imported files. Include all the directories you wish to import modules from. This usually includes the Python source-library (wherever you installed it in step 2), and any of its subdirectories that you need to use; add "/tkinter" for Tkinter modules, etc. See your shell's man-page for list variable syntax (colon-separated strings are common - "a:b:c"). MORE ON STEP 5: EXTENSIONS, TKINTER ------------------------------------ Linked-in extensions may have additional configuration requirements. This varies widely per extension. As an example, if you're using an executable that supports the Tkinter GUI extension, you need to tell Tcl and Tk where to find their source-libraries. The procedures are similar to step 2 above for Python - follow either of these methods: 5) Unpack and install the Tcl and Tk packages. They can be found in the CD's "/tcltk" directory. Tcl/Tk source-libraries are embedded in these packages; to install them on your machine: 5a) Copy and unpack the Tcl and Tk packages (from "/tcltk") 5b) Type "make install" to install libraries in the standard places ("/usr/local/lib/{tcl, tk}"). 5) Alternatively, you can use the libraries without installing: 5a) Copy and unpack the Tcl and Tk packages (from "/tcltk") 5b) Set environment variables TCL_LIBRARY and TK_LIBRARY to the "library" subdirectories of the Tcl and Tk directories created by unpacking. As usual, see the "README" files of both packages for more details. Note that many machines have Tcl/Tk already installed; check your system's "/usr/local/lib" directory before unpacking packages. 5.5 HOW TO USE DOCUMENTS ------------------------- Documentation comes in a variety of flavors on the CD. The HTML files on this disk (suffix ".html") can be opened with your favorite web-browser. Postscript files (".ps") can be printed, or viewed interactively if you have a viewer. Others are text files, or use specialized text systems that require converters like LaTeX. Ask your local guru or consult the net if you need help with conversion procedures. 5.6 HOW TO ADD EXTENSIONS -------------------------- One other note: most of the executables on this CD support dynamic loading of C extension modules, according to the protocol of the host platform. But if you're using one that doesn't support this feature, you'll need to build Python from the source-code distribution to add extensions. See above for source-code build tips; see chapters 3 and 14 in the book for details on adding extensions, both statically and dynamically. Again, the Python source-distribution is in: "/ftp.python.org/src/python1.3.tar.gz". ----------------------------------------------------------------------------- 6) WHERE THIS STUFF CAME FROM ----------------------------------------------------------------------------- Finally, here are some of the URLs where we fetched items from. Although these are extremely prone to change, this might help if you need to get newer versions, related material, etc. - ftp.python.org/ ftp://ftp.python.org/pub/python - gdbm/ ftp://prep.ai.mit.edu/pub/gnu/ - grail/ http://monty.cnri.reston.va.us/grail/ - gzip/ ftp://prep.ai.mit.edu/pub/gnu/ - ilu/ ftp://ftp.parc.xerox.com/pub/ilu - mac/ ftp://ftp.cwi.nl/pub/jack/python/mac/ - pc/ [special contribution at ftp.python.org] - pil/ http://www.python.org/sigs/image-sig/Imaging.html - special.bin/ [special contributions at ftp.python.org] - swig/ http://www.cs.utah.edu/~beazley/python.html - tcltk/ ftp://ftp.sunlabs.com/pub/tcl - www.python.org/ http://www.python.org/ All of the FTP sites listed here support anonymous FTP; see chapter 3 for FTP usage details. ----------------------------------------------------------------------------- 7) CREDITS ----------------------------------------------------------------------------- Lots of people helped pull this CD together: - Jessica Hekman and Norm Walsh at O'Reilly did most of the packaging work; Jessica pulled everything off the net. - Frank Willison at O'Reilly helped with advice, coordination, and copyright negotiations. - Ken Manheimer (Python's ftp-master) helped with information and support at Python's Internet sites. - Guido van Rossum helped with questions, packaging, and inventing Python :-). - And members of the Python community contributed special packages and binary executables for the CD. In closing, I'd like to mention that this CD is really the product of an amazing community of developers. Most of what you'll find on it was contributed to the public-domain by members of the Python world. Although I can't list every individual here, I hope they'll accept my blanket thanks for many jobs well done. Have fun, Mark Lutz July, 1996 -----