ThisisPythonrelease1.2==========================What's new in this release?---------------------------This version provides new functionality as well as bug fixes, lots ofnew documentation, and quite a few new library modules. Everyoneshould upgrade. For a full list of what'snewandchanged,seeMisc/NEWS.WhatisPythonanyway?----------------------Pythonisaninterpretedobject-orientedprogramminglanguage,andisoftencomparedtoTcl,PerlorScheme.ForaquicksummaryofwhatPythoncanmeanforaUNIX/Cprogrammer,readMisc/BLURB.LUTZ.Ifyoudon't read instructions------------------------------Congratulations on getting this far. :-)To start building right away (on UNIX): type "./configure" in thecurrent directory and when it finishes, type "make". The sectionBuild Instructions below is still recommended reading. :-)Copyright issues----------------Python is COPYRIGHTED but free to use for all. See the full copyrightnotice at the end of this file.The Python distribution is *not* affected by the GNU Public Licence(GPL). There are interfaces to some GNU code but these are entirelyoptional and no GNU code is distributed with Python. For all thesepackages, GPL-free public domain versions also exist.Build instructions==================Before you start building Python, you must first configure it. Thisentails (at least) running the script "./configure", which figures outyour system configuration and creates several Makefiles. (It takes aminute or two -- please be patient!) When it'sdone,youarereadytorunmake.Typing"make"inthetopleveldirectorywillrecursivelyrunmakeineachofthesubdirectoriesParser,Objects,PythonandModules,creatingalibraryfileineachone.TheexecutableoftheinterpreterisbuiltintheModulessubdirectoryandmovedupherewhenitisbuilt.Ifyouwantorneedto,youcanalsochdirintoeachsubdirectoryinturnandrunmaketheremanually(dotheModulessubdirectorylast!).NOTE:ifyoureruntheconfigurescriptwithdifferentoptions,removeallobjectfilesbyrunning"make clean"beforerebuilding.Believeitornot,"make clean"sometimeshelpstocleanupotherinexplicableproblemsaswell.Tryitbeforesendinginabugreport!Troubleshooting---------------Ifyourunintotrouble,seesection3oftheFAQ(fileMisc/FAQ)forhintsonwhatcangowrong,andhowtofixit.Platformspecificnotes-----------------------Linux:Itispossiblethat"makesetup"failswithanobscuresederror.Thisisabuginbash.Replace/bin/shwith/bin/ashinbothmakesetupandMakefile.pre.in.ThishasbeenobservedinSlackwareversion2.2,bash1.14.3;Slackware2.1didnothavetheproblem.AIX:ReadthefileMisc/AIX-NOTESbeforetryingtobuild.HP-UX:ReadthefileMisc/HPUX-NOTESifyouwanttobeabletousesharedlibrariesfordynamicallyloadedmodules.Minix:Whenusingack,use"CC=cc AR=aal RANLIB=: ./configure"!SCO:1)Everythingworksmuchbetterifyouadd-U__STDC__tothedefs.ThisisbecausealltheSCOheaderfilesarebroken.Anythingthatisn't mentioned in the C standard it'sconditionallyexcludedwhen__STDC__isdefined.2)DuetotheU.S.exportrestrictions,SCObrokethecryptstuffoutintoaseparatelibrary,libcrypt_i.asotheLIBSneededbesetto:LIBS=' -lsocket -lcrypt_i'Configuringthesetofbuilt-inmodules---------------------------------------Youcanconfiguretheinterpretertocontainfewerormorebuilt-inmodulesbyeditingthefileModules/Setup.Thisfileisinitiallycopied(whenthetoplevelMakefilemakesModules/Makefileforthefirsttime)fromSetup.in;ifitdoesnotexistyet,makeacopyyourself.NevereditSetup.in--alwayseditSetup.Readthecommentsinthefileforinformationonwhatkindofeditsyoucanmake.WhenyouhaveeditedSetup,Makefileandconfig.cinModuleswillautomaticallyberebuiltthenexttimeyourunmakeinthetopleveldirectory.EspeciallyonSGIIRIX,therearemodulesthatinterfacetomanySGIspecificsystemlibraries,e.g.theGLlibraryandtheaudiohardware.Settingtheoptimization/debuggingoptions------------------------------------------Ifyouwanttochangetheoptimization/debuggingoptionsfortheCcompiler,assigntotheOPTvariableonthetoplevelmakecommand;e.g."make OPT=-g"willbuildadebuggingversionofPythononmostplatforms.ThedefaultisOPT=-O;avalueforOPTintheenvironmentwhentheconfigurescriptisrunoverridesthisdefault(likewiseforCC;andtheinitialvalueforLIBSisusedasthebasesetoflibrariestolinkwith).Testing-------Totesttheinterpreterthatyouhavejustbuilt,type"make test".Thisrunsthetestsetsilently,twice(oncewithnocompiledfiles,oncewiththecompiledfilesleftbytheprevioustestrun).Eachtestrunshouldprint"All tests OK."andnothingmore.(Thetestsetdoesnottestthebuilt-inmodules,butwillfindmostotherproblemswiththeinterpreter.)IMPORTANT:Ifthetestsfailandyoudecidetomailabugreport,*don't* include the output of "make test". It is useless. Run thefollowing command instead: PYTHONPATH=../Lib:../Lib/test:./Modules ./python -c 'importtestall'(substituting the top of the source tree for .. if you built in adifferent directory). This gives the output of the tests and showswhich test failed.Installing----------To install the interpreter as /usr/local/bin/python, type "makeinstall". To install the library as /usr/local/lib/python, type "makelibinstall". To install the manual page as/usr/local/man/man1/python.1, type "make maninstall". To install theEmacs editing mode for python, manually copy the fileMisc/python-mode.el to your local Emacs lisp directory. The directory/usr/local can be overridden at configuration time by passing--prefix=DIRECTORY to the configure script, or at make time by passing"prefix=DIRECTORY" to make. See below for more information on --prefix.If you plan to do development of extension modules or to embed Pythonin another application and don'twanttoreferencetheoriginalsourcetree,youcantype"make inclinstall"and"make libainstall"toinstalltheincludefilesandlib*.afiles,respectively,as/usr/local/include/Py/*.h and /usr/local/lib/python/lib/lib*.a. Themake libainstall target also installs copies of several other filesused or produced during the build process which are needed to buildextensions or to generate their Makefiles.Configuration options and variables-----------------------------------Some special cases are handled by passing environment variables oroptions to the configure script.NOTE: if you rerun the configure script with different options, removeall object files by running "make clean" before rebuilding.--with(out)-gcc: The configure script uses gcc (the GNU C compiler) if it finds it. If you don't want this, or if this compiler is installed but broken on your platform, pass the option --without-gcc. You can also pass "CC=cc" (or whatever the name of the proper C compiler is) in the environment, but the advantage of using --without-gcc is that this option is remembered by the config.status script for its --recheck option.--prefix, --exec-prefix: If you want to install the binaries and the Python library somewhere else than in /usr/local/{bin,lib}, you can pass the option --prefix=DIRECTORY; the interpreter binary will be installed as DIRECTORY/bin/python and the library files as DIRECTORY/lib/python/*. If you pass --exec-prefix=DIRECTORY (as well) this overrides the installation prefix for architecture-dependent files (like the interpreter binary). Note that --prefix=DIRECTORY also affects the default module search path (sys.path), when Modules/config.c is compiled. Passing make the option prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the prefix set at configuration time; this may be more convenient than re-running the configure script if you change your mind about the install prefix...--with-readline: You can use the GNU readline library to improve the interactive user interface: this gives you line editing and command history when calling python interactively. You need to configure build the GNU readline library before running the configure script. Its sources are not distributed with Python; you can ftp them from any GNU mirror site, or from its home site: <URL:ftp://slc2.ins.cwru.edu/pub/dist/readline-2.0.tar.gz> (or a higher version number -- using version 1.x is not recommended). A GPL-free version was posted to comp.sources.misc in volume 31 and is widely available from FTP archive sites, e.g. <URL:ftp://gatekeeper.dec.com/.b/usenet/comp.sources.misc/ volume31/editline/part01.Z> Pass the Python configure script the option --with-readline=DIRECTORY where DIRECTORY is the absolute pathname of the directory where you've built the readline library. Some hints on building and using the readline library are in the FAQ (file Misc/FAQ).--with-thread: On SGI IRIX, and on Sun SOLARIS 2, you can use multiple threads. To enable this, pass --with-thread. In the Modules/Setup file, enable the thread module. (Threads aren't enabled automatically because there are run-time penalties when support for them is compiled in even if you don't use them.)--with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is supported by the "dl" library by Jack Jansen, which is ftp'able from <URL:ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z>. This is enabled (after you've ftp'ed and compiled the dl library!) by passing --with-sgi-dl=DIRECTORY where DIRECTORY is the absolute pathname of the dl library. (Don't bother on IRIX 5, it already has dynamic linking using SunOS style shared libraries.) Support for this feature is deprecated.--with-dl-dld: Dynamic loading of modules is rumoured to be supported on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent Symmetry (Dynix), and Atari ST. This is done using a combination of the GNU dynamic loading package (<URL:ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z>) and an emulation of the SGI dl library mentioned above (the emulation can be found at <URL:ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z>). To enable this, ftp and compile both libraries, then call the configure passing it the option --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is the absolute pathname of the dl emulation library and DLD_DIRECTORY is the absolute pathname of the GNU dld library. (Don't bother on SunOS 4 or 5, they already have dynamic linking using shared libraries.) Support for this feature is deprecated.--with-libm, --with-libc: It is possible to specify alternative versions for the Math library (default -lm) and the C library (default the empty string) using the options --with-libm=STRING and --with-libc=STRING, respectively. E.g. if your system requires that you pass -lc_s to the C compiler to use the shared C library, you can pass --with-libc=-lc_s. These libraries are passed after all other libraries, the C library last.Extensions----------You can also build an "extended" interpreter, using modules that arenot contained in the Modules directory. Extensions are distributed asa separate tar file (currently extensions.tar.gz). See the READMEfile there.Building for multiple architectures (using the VPATH feature)-------------------------------------------------------------If your file system is shared between multiple architectures, itusually is not necessary to make copies of the sources for eacharchitecture you want to support. If the make program supports theVPATH feature, you can create an empty build directory for eacharchitecture, and in each directory run the configure script (on theappropriate machine with the appropriate options). This creates thenecessary subdirectories and the Makefiles therein. The Makefilescontain a line VPATH=... which points to directory containing theactual sources. (On SGI systems, use "smake" instead of "make" if youuse VPATH -- don't try gnumake.)For example, the following is all you need to build a minimal Pythonin /usr/tmp/python (assuming ~guido/src/python is the topleveldirectory and you want to build in /usr/tmp/python): $ mkdir /usr/tmp/python $ cd /usr/tmp/python $ ~guido/src/python/configure [...] $ make [...] $Note that Modules/Makefile copies the original Setup file to the builddirectory if it finds no Setup file there. This means that you canedit the Setup file for each architecture independently. For thisreason, subsequent changes to the original Setup file are not trackedautomatically, as they might overwrite local changes. To force a copyof a changed original Setup file, delete the target Setup file. (Themakesetup script supports multiple input files, so if you want to befancy you can change the rules to create an empty Setup.local if itdoesn't exist and run it with arguments $(srcdir)/Setup Setup.local;however this assumes that you only need to add modules.)Building on non-UNIX systems----------------------------On non-UNIX systems, you will have to fake the effect of running theconfigure script manually. A good start is to copy the fileconfig.h.in to config.h and edit the latter to reflect the actualconfiguration of your system. Most symbols must simply be defined as1 only if the corresponding feature is present and can be left aloneotherwise; however RETSIGTYPE must always be defined, either as int oras void, and the *_t type symbols must be defined as some variant ofint if they need to be defined at all. Then arrange that the symbolHAVE_CONFIG_H is defined during compilation (usually by passing anargument of the form `-DHAVE_CONFIG_H' to the compiler, but this isnecessarily system-dependent).I have tried to collect instructions, Makefiles and additional sourcesfor various platforms in this release. The following directoriesexist:Mac/ Apple Macintosh, using THINK C 6.0 or MPW 3.2.Dos/ MS-DOS and Windows 3.1, using Microsoft C.Nt/ Windows NT, using Microsoft Visual C/C++.Os2/ OS/2.Most of these instructions were last tested with a previous Pythonrelease, so you may still experience occasional problems. If you havefixes or suggestions, please let me know and I'll try to incorporatethem in the next release.Miscellaneous issues====================Documentation-------------All documentation is provided in the subdirectory Doc in the form ofLaTeX files. In order of importance for new users: Tutorial (tut),Library Reference (lib), Language Reference (ref), Extending (ext).Especially the Library Reference is of immense value since much ofPython's power (including the built-in data types and functions!) isdescribed here.To print the documentation from the LaTeX files, chdir into the Docsubdirectory, type "make" (let's hope you have LaTeX installed!), andsend the four resulting PostScript files (tut.ps, lib.ps, ref.ps, andext.ps) to the printer. See the README file there.All documentation is also available on-line via the World-Wide Web(WWW): <URL:http://www.cwi.nl/~guido/Python.html>. It can also bedownloaded separately from the ftp archives (see below) in Emacs INFO,HTML or PostScript form -- see the FAQ (file Misc/FAQ) for more info.Emacs mode----------There's an excellent Emacs editing mode for Python code; see the fileMisc/python-mode.el. Originally written by Tim Peters, who's nolonger on the net, it is now maintained by Barry Warsaw<bwarsaw@cnri.reston.va.com>.Bug reports-----------Bugs are best reported to the comp.lang.python newsgroup or the Pythonmailing list -- see the section "Newsgroup and mailing list" below.Before posting, read the FAQ (file Misc/FAQ) first to see if yourproblem has already been answered!Ftp access----------Python's "home ftp site" is ftp.cwi.nl, directory pub/python. See theFAQ (file Misc/FAQ) for a list of other ftp sites carrying the Pythondistribution.Newsgroup and mailing list--------------------------There are a newsgroup and a mailing list devoted to Pythonprogramming, design and bugs. The newsgroup, comp.lang.python,contains exactly the same messages as the mailing list. To subscribeto the mailing list, send mail containing your real name and e-mailaddress to "python-list-request@cwi.nl" (a real person reads thesemessages, so no LISTPROC or Majordomo commands, please).The Tk interface----------------Tk (the user interface component of John Ousterhout's Tcl language) isalso usable from Python. Since this requires that you first build andinstall Tcl/Tk, the Tk interface is not enabled by default. Itrequires Tcl 7.3 and Tk 3.6. It doesn't work yet with Tk 4.0-beta!(Actually, the C code does, but the Tkinter.py module hasn't beenadapted yet.) For more info about Tk, including pointers to thesource, see John Ousterhout's home page at<URL:http://playground.sun.com/~ouster/>.To enable the Python/Tk interface, once you've built and installedTcl/Tk, all you need to do is edit two lines in Modules/Setup; searchfor the string "tkinter". Un-comment one (normally the first) of thelines beginning with "#tkinter" and un-comment the line beginning with"#TKPATH". (If you have installed Tcl/Tk in unusual places you willhave to edit the first line as well to fix the -I and -L options.)See the Build Instructions above for more details.There is little documentation. Begin with fetching the "Tk Lifesaver"document, e.g. <URL:ftp://ftp.cwi.nl/pub/python/tkinter-doc.tar.gz> (agzipped tar file containing a PostScript file). There are demos inthe Demo/tkinter directory, in the subdirectories guido, matt and www.Note that there's a Python module called "Tkinter" (capital T) whichlives in Lib/tkinter/Tkinter.py, and a C module called "tkinter"(lower case t) which lives in Modules/tkintermodule.c. Demos andnormal Tk applications only import the Python Tkinter module -- onlythe latter uses the C tkinter module directly. In order to find the Ctkinter module, it must be compiled and linked into the Pythoninterpreter -- the tkinter line in the Setup file does this. In orderto find the Python Tkinter module, sys.path must be set correctly --the TKPATH assignment in the Setup file takes care of this, but onlyif you install Python properly ("make install libinstall"). (You canalso use dynamic loading for the C tkinter module, in which case youmust manually fix up sys.path or set $PYTHONPATH for the PythonTkinter module.)Distribution structure----------------------Most subdirectories have their own README file. Most files havecomments.ChangeLog A raw list of changes since the first 1.0.0 BETA releaseContrib/ Interesting or useful Python code contributed by othersDemo/ Demonstration scripts, modules and programsDoc/ Documentation (LaTeX sources)Extensions/ Extension modules (distributed separately)Grammar/ Input for the parser generatorInclude/ Public header filesLib/ Python library modulesMakefile.in Source from which config.status creates MakefileMisc/ Miscellaneous filesModules/ Implementation of most built-in modulesObjects/ Implementation of most built-in object typesParser/ The parser and tokenizer and their input handlingPython/ The "compiler" and interpreterREADME The file you're reading nowTools/ Some useful programs written in Pythonacconfig.h Additional input for the autoheader programconfig.h.in Source from which config.status creates config.hconfigure Configuration shell script (GNU autoconf output)configure.in Configuration specification (GNU autoconf input)The following files will (may) be created in the toplevel directory bythe configuration and build processes:Makefile Build rulesconfig.cache cache of configuration variablesconfig.h Configuration headerconfig.log log from last configure runconfig.status status from last run of configure scriptpython The executable interpretertags, TAGS Tags files for vi and EmacsAuthor's address----------------Guido van RossumCWI, dept. CSTP.O. Box 940791090 GB AmsterdamThe NetherlandsE-mail: guido@cwi.nlCopyright notice================The Python source is copyrighted, but you can freely use and copy itas long as you don't change or remove the copyright notice:----------------------------------------------------------------------Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,The Netherlands. All Rights ReservedPermission to use, copy, modify, and distribute this software and itsdocumentation for any purpose and without fee is hereby granted,provided that the above copyright notice appear in all copies and thatboth that copyright notice and this permission notice appear insupporting documentation, and that the names of Stichting MathematischCentrum or CWI not be used in advertising or publicity pertaining todistribution of the software without specific, written prior permission.STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TOTHIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY ANDFITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLEFOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGESWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN ANACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUTOF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.------------------------------------------------------------------------Guido van Rossum, CWI, Amsterdam <mailto:guido@cwi.nl><http://www.cwi.nl/~guido/>